> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Modo de desempenho (compat_mode)

> Modo de desempenho com foco em SQL que desativa a sobrecarga de compatibilidade com pandas para máximo throughput

O DataStore tem dois modos de compatibilidade que determinam se a saída é formatada para compatibilidade com pandas ou otimizada para o desempenho de Raw SQL.

<div id="overview">
  ## Visão geral
</div>

| Modo | Valor de `compat_mode` | Descrição |
| - | - | - |
| **Pandas** (padrão) | `"pandas"` | Compatibilidade total com o comportamento do pandas. Ordem das linhas preservada, MultiIndex, set\_index, correções de dtype, desempates em ordenação estável, wrappers `-If`/`isNaN`. |
| **Performance** | `"performance"` | Execução priorizando SQL. Toda a sobrecarga de compatibilidade com pandas é removida. Vazão máxima, mas os resultados podem diferir estruturalmente do pandas. |

<div id="what-it-disables">
  ### O que o modo de desempenho desativa
</div>

| Sobrecarga | Comportamento do modo Pandas | Comportamento do modo de desempenho |
| - | - | - |
| **Preservação da ordem das linhas** | injeção de `_row_id`, `rowNumberInAllBlocks()` e subconsultas `__orig_row_num__` | Desativado — a ordem das linhas não é garantida |
| **Critério de desempate para ordenação estável** | `rowNumberInAllBlocks() ASC` acrescentado a ORDER BY | Desativado — empates podem ficar em ordem arbitrária |
| **`preserve_order` do Parquet** | `input_format_parquet_preserve_order=1` | Desativado — leitura paralela de Parquet permitida |
| **ORDER BY automático do GroupBy** | `ORDER BY group_key` adicionado (padrão do pandas `sort=True`) | Desativado — grupos retornados em ordem arbitrária |
| **WHERE `dropna` do GroupBy** | `WHERE key IS NOT NULL` adicionado (padrão do pandas `dropna=True`) | Desativado — grupos com NULL incluídos |
| **`set_index` do GroupBy** | Chaves de grupo definidas como índice | Desativado — as chaves de grupo permanecem como colunas |
| **Colunas MultiIndex** | `agg({'col': ['sum','mean']})` retorna colunas MultiIndex | Desativado — nomes de colunas simples (`col_sum`, `col_mean`) |
| **Wrappers `-If`/`isNaN`** | `sumIf(col, NOT isNaN(col))` para `skipna` | Desativado — `sum(col)` simples (o ClickHouse ignora NULL nativamente) |
| **`toInt64` em count** | `toInt64(count())` para corresponder ao int64 do pandas | Desativado — retorna o `dtype` SQL nativo |
| **`fillna(0)` para soma com todos os valores NaN** | A soma de todos os valores NaN retorna 0 (comportamento do pandas) | Desativado — retorna NULL |
| **Correções de Dtype** | `abs()` sem sinal→com sinal, etc. | Desativado — tipos SQL nativos |
| **Preservação do índice** | Restaura o índice original após a execução do SQL | Desativado |
| **`first()`/`last()`** | `argMin/argMax(col, rowNumberInAllBlocks())` | `any(col)` / `anyLast(col)` — mais rápido, mas não determinístico |
| **Agregação em uma única consulta SQL** | O GroupBy de ColumnExpr materializa um DataFrame intermediário | Injeta `LazyGroupByAgg` na cadeia de operações lazy — uma única consulta SQL |

***

<div id="enabling">
  ## Ativando o modo de desempenho
</div>

<div id="using-config">
  ### Usando o objeto de configuração
</div>

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

# Enable performance mode
config.use_performance_mode()

# Back to pandas compatibility
config.use_pandas_compat()

# Check current mode
print(config.compat_mode)  # 'pandas' or 'performance'
```

<div id="using-functions">
  ### Usando funções de nível de módulo
</div>

```python theme={null}
from chdb.datastore.config import set_compat_mode, CompatMode, is_performance_mode

# Enable performance mode
set_compat_mode(CompatMode.PERFORMANCE)

# Check
print(is_performance_mode())  # True

# Back to default
set_compat_mode(CompatMode.PANDAS)
```

<div id="using-imports">
  ### Usando imports de conveniência
</div>

```python theme={null}
from chdb import use_performance_mode, use_pandas_compat

use_performance_mode()
# ... high-performance operations ...
use_pandas_compat()
```

<Note>
  Ao definir o modo de desempenho, o mecanismo de execução é configurado automaticamente como `chdb`. Você não precisa chamar `config.use_chdb()` separadamente.
</Note>

***

<div id="when-to-use">
  ## Quando usar o modo de desempenho
</div>

**Use o modo de desempenho quando:**

* Estiver processando grandes conjuntos de dados (de centenas de milhares a milhões de linhas)
* Estiver executando workloads com muita agregação (groupby, sum, mean, count)
* A ordem das linhas não importar (por exemplo, resultados agregados, relatórios, dashboards)
* Quiser o máximo de throughput de SQL com o mínimo de sobrecarga
* O uso de memória for uma preocupação (leitura paralela de Parquet, sem DataFrames intermediários)

**Permaneça no modo pandas quando:**

* Precisar do comportamento exato do pandas (ordem das linhas, MultiIndex, dtypes)
* Depender de `first()`/`last()` retornarem a verdadeira primeira/última linha
* Usar `shift()`, `diff()`, `cumsum()` que dependem da ordem das linhas
* Estiver escrevendo testes que comparam a saída do DataStore com a do pandas

***

<div id="behavior-differences">
  ## Diferenças de comportamento
</div>

<div id="row-order">
  ### Ordem das linhas
</div>

No modo de desempenho, a ordem das linhas **não é garantida** em nenhuma operação. Isso inclui:

* Resultados de filtro
* Resultados de agregação do GroupBy
* `head()` / `tail()` sem `sort_values()` explícito
* Agregações `first()` / `last()`

Se você precisar de resultados ordenados, adicione um `sort_values()` explícito:

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

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

# Unordered (fast)
result = ds.groupby("region")["revenue"].sum()

# Ordered (still fast, just adds ORDER BY)
result = ds.groupby("region")["revenue"].sum().sort_values()
```

<div id="groupby-results">
  ### Resultados de GroupBy
</div>

| Aspecto | Modo Pandas | Modo de desempenho |
| - | - | - |
| Localização da chave de agrupamento | Índice (com `set_index`) | Coluna comum |
| Ordem dos grupos | Ordenados pela chave (padrão) | Ordem arbitrária |
| Grupos NULL | Excluídos (padrão `dropna=True`) | Incluídos |
| Formato da coluna | MultiIndex para múltiplas agregações | Nomes simples (`col_func`) |
| `first()`/`last()` | Determinístico (ordem das linhas) | Não determinístico (`any()`/`anyLast()`) |

<div id="aggregation">
  ### Agregação
</div>

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

# Sum of all-NaN group returns NULL (not 0)
# Count returns native uint64 (not forced int64)
# No -If wrappers: sum() instead of sumIf()
result = ds.groupby("cat")["val"].sum()
```

<div id="single-sql">
  ### Execução com uma única consulta SQL
</div>

No modo de desempenho, a agregação groupby de `ColumnExpr` (por exemplo, `ds[condition].groupby('col')['val'].sum()`) é executada como uma **única consulta SQL**, em vez do processo de duas etapas usado no modo pandas:

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

# Pandas mode: two SQL queries (filter → materialize → groupby)
# Performance mode: one SQL query (WHERE + GROUP BY in same query)
result = ds[ds["rating"] > 3.5].groupby("category")["revenue"].sum()

# Generated SQL (single query):
# SELECT category, sum(revenue) FROM data WHERE rating > 3.5 GROUP BY category
```

Isso elimina a necessidade de materializar o DataFrame intermediário e pode reduzir significativamente o uso de memória e o tempo de execução.

***

<div id="vs-execution-engine">
  ## Comparação com o mecanismo de execução
</div>

O modo de desempenho (`compat_mode`) e o mecanismo de execução (`execution_engine`) são **eixos de configuração independentes**:

| Configuração | Controla | Valores |
| - | - | - |
| `execution_engine` | **Qual mecanismo** executa a computação | `auto`, `chdb`, `pandas` |
| `compat_mode` | **Se** a saída deve ser reformatada para compatibilidade com pandas | `pandas`, `performance` |

Ao definir `compat_mode='performance'`, `execution_engine='chdb'` é definido automaticamente, já que o modo de desempenho foi projetado para execução de SQL.

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

# These are independent
config.use_chdb()              # Force chDB engine, keep pandas compat
config.use_performance_mode()  # Force chDB + remove pandas overhead
```

***

<div id="testing">
  ## Testes no modo de desempenho
</div>

Ao escrever testes para o modo de desempenho, os resultados podem diferir do pandas na ordem das linhas e no formato estrutural. Use estas estratégias:

<div id="sort-then-compare">
  ### Ordenar e depois comparar (agregações, filtros)
</div>

```python theme={null}
# Sort both sides by the same columns before comparing
ds_result = ds.groupby("cat")["val"].sum()
pd_result = pd_df.groupby("cat")["val"].sum()

ds_sorted = ds_result.sort_index()
pd_sorted = pd_result.sort_index()
np.testing.assert_array_equal(ds_sorted.values, pd_sorted.values)
```

<div id="value-range-check">
  ### Verificação da faixa de valores (primeiro/último)
</div>

```python theme={null}
# first() with any() returns an arbitrary element from the group
result = ds.groupby("cat")["val"].first()
for group_key in groups:
    assert result.loc[group_key] in group_values[group_key]
```

<div id="schema-and-count">
  ### Esquema e contagem (LIMIT sem ORDER BY)
</div>

```python theme={null}
# head() without sort_values: row set is non-deterministic
result = ds.head(5)
assert len(result) == 5
assert set(result.columns) == expected_columns
```

***

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

<div id="enable-early">
  ### 1. Ative logo no início do script
</div>

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

config.use_performance_mode()

# All subsequent operations benefit
ds = pd.read_parquet("data.parquet")
result = ds[ds["amount"] > 100].groupby("region")["amount"].sum()
```

<div id="explicit-sort">
  ### 2. Adicione ordenação explícita quando a ordem for importante
</div>

```python theme={null}
# For display or downstream processing that expects order
result = (ds
    .groupby("region")["revenue"].sum()
    .sort_values(ascending=False)
)
```

<div id="batch-etl">
  ### 3. Use para cargas de trabalho de batch/ETL
</div>

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

# ETL pipeline — order doesn't matter, throughput does
summary = (ds
    .filter(ds["date"] >= "2024-01-01")
    .groupby(["region", "product"])
    .agg({"revenue": "sum", "quantity": "sum", "rating": "mean"})
)
summary.to_df().to_parquet("summary.parquet")
```

<div id="switch-modes">
  ### 4. Alternar entre modos em uma sessão
</div>

```python theme={null}
# Performance mode for heavy computation
config.use_performance_mode()
aggregated = ds.groupby("cat")["val"].sum()

# Back to pandas mode for exact-match comparison
config.use_pandas_compat()
detailed = ds[ds["val"] > 100].head(10)
```

***

<div id="related">
  ## Documentação relacionada
</div>

* [mecanismo de execução](/pt-BR/chdb/configuration/execution-engine) — Seleção do mecanismo (auto/chdb/pandas)
* [Performance Guide](/pt-BR/chdb/guides/pandas-performance) — Dicas gerais de otimização
* [Key Differences from pandas](/pt-BR/chdb/guides/pandas-differences) — Diferenças de comportamento