> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuração do motor de execução

> Configure o motor de execução do DataStore - auto, chdb ou pandas

O DataStore pode executar operações usando diferentes backends. Este guia explica como configurar e otimizar a seleção do motor de execução.

<div id="engines">
  ## Motores disponíveis
</div>

| Motor    | Descrição                                                      | Ideal para                                                |
| -------- | -------------------------------------------------------------- | --------------------------------------------------------- |
| `auto`   | Seleciona automaticamente o melhor motor para cada operação    | Uso geral (padrão)                                        |
| `chdb`   | Força todas as operações a serem executadas via ClickHouse SQL | Grandes conjuntos de dados, agregações                    |
| `pandas` | Força todas as operações a serem executadas via pandas         | Testes de compatibilidade, recursos específicos do pandas |

<div id="setting">
  ## Configurando o motor
</div>

<div id="global">
  ### Configuração global
</div>

```python theme={null}
from chdb.datastore.config import config

# Opção 1: Usando o método set
config.set_execution_engine('auto')    # Padrão
config.set_execution_engine('chdb')    # Forçar ClickHouse
config.set_execution_engine('pandas')  # Forçar pandas

# Opção 2: Usando atalhos
config.use_auto()     # Seleção automática
config.use_chdb()     # Forçar ClickHouse
config.use_pandas()   # Forçar pandas
```

<div id="checking">
  ### Verificando o motor atual
</div>

```python theme={null}
print(config.execution_engine)  # 'auto', 'chdb' ou 'pandas'
```

***

<div id="auto-mode">
  ## Modo automático
</div>

No modo `auto` (padrão), o DataStore seleciona o motor mais adequado para cada operação:

<div id="auto-chdb">
  ### Operações executadas no chDB
</div>

* Filtragem compatível com SQL (`filter()`, `where()`)
* Seleção de colunas (`select()`)
* Ordenação (`sort()`, `orderby()`)
* Agrupamento e agregação (`groupby().agg()`)
* Junções (`join()`, `merge()`)
* Valores distintos (`distinct()`, `drop_duplicates()`)
* Limitação de resultados (`limit()`, `head()`, `tail()`)

<div id="auto-pandas">
  ### Operações executadas no pandas
</div>

* Funções `apply` personalizadas (`apply(custom_func)`)
* Tabelas dinâmicas complexas com agregações customizadas
* Operações que não podem ser expressas em SQL
* Quando a entrada já é um `DataFrame` do pandas

<div id="auto-example">
  ### Exemplo
</div>

```python theme={null}
from chdb import datastore as pd
from chdb.datastore.config import config

config.use_auto()  # Padrão

ds = pd.read_csv("data.csv")

# Isso usa chDB (SQL)
result = (ds
    .filter(ds['amount'] > 100)   # SQL: WHERE
    .groupby('region')            # SQL: GROUP BY
    .agg({'amount': 'sum'})       # SQL: SUM()
)

# Isso usa pandas (função personalizada)
result = ds.apply(lambda row: complex_calculation(row), axis=1)
```

***

<div id="chdb-mode">
  ## Modo chDB
</div>

Force todas as operações por meio do ClickHouse SQL:

```python theme={null}
config.use_chdb()
```

<div id="chdb-when">
  ### Quando usar
</div>

* Processamento de grandes volumes de dados (milhões de linhas)
* Cargas de trabalho com muita agregação
* Quando você quer o máximo de otimização de SQL
* Comportamento consistente em todas as operações

<div id="chdb-performance">
  ### Características de desempenho
</div>

| Tipo de operação            | Desempenho                      |
| --------------------------- | ------------------------------- |
| GroupBy/Agregação           | Excelente (até 20x mais rápido) |
| Filtragem complexa          | Excelente                       |
| Ordenação                   | Muito bom                       |
| Filtros simples individuais | Bom (leve sobrecarga)           |

<div id="chdb-limitations">
  ### Limitações
</div>

* Funções personalizadas em Python podem não ser compatíveis
* Alguns recursos específicos do pandas exigem conversão

***

<div id="pandas-mode">
  ## Modo pandas
</div>

Force todas as operações a passar pelo pandas:

```python theme={null}
config.use_pandas()
```

<div id="chdb-when">
  ### Quando usar
</div>

* Testes de compatibilidade com o pandas
* Uso de funcionalidades específicas do pandas
* Depuração de problemas relacionados ao pandas
* Quando os dados já estão no formato do pandas

<div id="chdb-performance">
  ### Características de desempenho
</div>

| Tipo de operação             | Desempenho               |
| ---------------------------- | ------------------------ |
| Operações simples e isoladas | Bom                      |
| Funções personalizadas       | Excelente                |
| Agregações complexas         | Mais lentas que o chDB   |
| Grandes volumes de dados     | Uso intensivo de memória |

***

<div id="cross-datastore">
  ## Motor entre DataStores
</div>

Configure o motor para operações que combinam colunas de diferentes DataStores:

```python theme={null}
# Definir engine cross-DataStore
config.set_cross_datastore_engine('auto')
config.set_cross_datastore_engine('chdb')
config.set_cross_datastore_engine('pandas')
```

<div id="auto-example">
  ### Exemplo
</div>

```python theme={null}
ds1 = pd.read_csv("sales.csv")
ds2 = pd.read_csv("inventory.csv")

# Esta operação envolve dois DataStores
result = ds1.join(ds2, on='product_id')
# Usa a configuração cross_datastore_engine
```

***

<div id="selection-logic">
  ## Lógica de seleção do motor
</div>

<div id="decision-tree">
  ### Árvore de decisão do modo automático
</div>

```text theme={null}
Operação solicitada
    │
    ├─ Pode ser expressa em SQL?
    │      │
    │      ├─ Sim → Use chDB
    │      │
    │      └─ Não → Use pandas
    │
    └─ Operação Cross-DataStore?
           │
           └─ Use a configuração cross_datastore_engine
```

<div id="function-override">
  ### Override em nível de função
</div>

Algumas funções podem ter o motor configurado explicitamente:

```python theme={null}
from chdb.datastore.config import function_config

# Forçar funções específicas a usar um engine específico
function_config.use_chdb('length', 'substring')
function_config.use_pandas('upper', 'lower')
```

Consulte [Configuração de função](/pt-BR/products/chdb/configuration/function-config) para mais detalhes.

***

<div id="performance-comparison">
  ## Comparação de desempenho
</div>

Resultados do benchmark em 10 milhões de linhas:

| Operação              | pandas (ms) | chdb (ms) | Ganho de desempenho |
| --------------------- | ----------- | --------- | ------------------- |
| Contagem com GroupBy  | 347         | 17        | 19.93x              |
| Operações combinadas  | 1,535       | 234       | 6.56x               |
| Pipeline complexo     | 2,047       | 380       | 5.39x               |
| Filter+Sort+Head      | 1,537       | 350       | 4.40x               |
| Agregação com GroupBy | 406         | 141       | 2.88x               |
| Filtro único          | 276         | 526       | 0.52x               |

**Principais conclusões:**

* o chDB se destaca em agregações e pipelines complexos
* o pandas é um pouco mais rápido em operações simples e isoladas
* use o modo `auto` para aproveitar o melhor dos dois

***

<div id="best-practices">
  ## Boas práticas
</div>

<div id="start-with-auto-mode">
  ### 1. Comece pelo modo automático
</div>

```python theme={null}
config.use_auto()  # Deixe o DataStore decidir
```

<div id="profile-before-forcing">
  ### 2. Faça profiling antes de forçar
</div>

```python theme={null}
config.enable_profiling()
# Execute sua carga de trabalho
# Verifique o relatório do Profiler para ver onde o tempo é gasto
```

<div id="force-engine-for-specific-workloads">
  ### 3. Forçar o motor para cargas de trabalho específicas
</div>

```python theme={null}
# Para workloads com agregação pesada
config.use_chdb()

# Para testes de compatibilidade com pandas
config.use_pandas()
```

<div id="use-explain-to-understand-execution">
  ### 4. Use explain() para entender a execução
</div>

```python theme={null}
ds = pd.read_csv("data.csv")
query = ds.filter(ds['age'] > 25).groupby('city').agg({'salary': 'sum'})

# Veja qual SQL será gerado
query.explain()
```

***

<div id="troubleshooting">
  ## Solução de problemas
</div>

<div id="issue-operation-slower">
  ### Problema: Operação mais lenta que o esperado
</div>

```python theme={null}
# Verificar o engine atual
print(config.execution_engine)

# Ativar debug para ver o que está acontecendo
config.enable_debug()

# Tentar forçar um engine específico
config.use_chdb()  # or config.use_pandas()
```

<div id="issue-unsupported-operation">
  ### Problema: operação não suportada no modo chdb
</div>

```python theme={null}
# Algumas operações do pandas não são suportadas em SQL
# Solução: use o modo automático
config.use_auto()

# Ou converta explicitamente para pandas primeiro
df = ds.to_df()
result = df.some_pandas_specific_operation()
```

<div id="issue-memory-issues">
  ### Problema: uso excessivo de memória com grandes volumes de dados
</div>

```python theme={null}
# Use o engine chdb para evitar carregar todos os dados na memória
config.use_chdb()

# Filtre antecipadamente para reduzir o tamanho dos dados
result = ds.filter(ds['date'] >= '2024-01-01').to_df()

# Para maior throughput em grandes datasets, use o modo de desempenho
# que habilita leitura paralela de Parquet e agregação em SQL único
config.use_performance_mode()
```

<Tip>
  **Modo de desempenho**

  Se você estiver executando cargas de trabalho pesadas de agregação e não precisar de compatibilidade exata com a saída do pandas (ordem das linhas, MultiIndex, correções de dtype), considere usar o [Modo de desempenho](/pt-BR/products/chdb/configuration/performance-mode). Ele define automaticamente o motor como `chdb` e remove toda a sobrecarga de compatibilidade com o pandas.
</Tip>