> ## 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.

# Modelo de execução do DataStore

> Entenda a avaliação preguiçosa, os gatilhos de execução e o cache no DataStore

Entender o modelo de avaliação preguiçosa do DataStore é essencial para usá-lo com eficiência e obter o melhor desempenho.

<div id="lazy-evaluation">
  ## Avaliação preguiçosa
</div>

O DataStore usa **avaliação preguiçosa** - as operações não são executadas imediatamente; em vez disso, são registradas e compiladas em consultas SQL otimizadas. A execução só acontece quando os resultados são realmente necessários.

<div id="lazy-vs-eager">
  ### Exemplo: Preguiçoso vs Eager
</div>

```python theme={null}
from pathlib import Path
Path("sales.csv").write_text("""\
region,product,category,amount,quantity,price,date,order_id
East,Widget,Electronics,5200,10,120,2024-01-15,1001
West,Gadget,Electronics,800,5,160,2024-02-20,1002
East,Gizmo,Home,6500,3,100,2024-03-10,1003
North,Widget,Electronics,4500,6,150,2024-06-18,1004
West,Gadget,Electronics,2000,8,250,2024-09-14,1005
""")

from chdb import datastore as pd

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

# Estas operações NÃO foram executadas ainda
result = (ds
    .filter(ds['amount'] > 1000)    # Registrado, não executado
    .select('region', 'amount')      # Registrado, não executado
    .groupby('region')               # Registrado, não executado
    .agg({'amount': 'sum'})          # Registrado, não executado
    .sort('sum', ascending=False)    # Registrado, não executado
)

# Ainda sem execução - apenas construindo o plano de consulta
print(result.to_sql())
# SELECT region, SUM(amount) AS sum
# FROM file('sales.csv', 'CSVWithNames')
# WHERE amount > 1000
# GROUP BY region
# ORDER BY sum DESC

# AGORA a execução acontece
df = result.to_df()  # <-- Dispara a execução
```

<div id="benefits">
  ### Benefícios da Avaliação Preguiçosa
</div>

1. **Otimização de Consultas**: várias operações são compiladas em uma única consulta SQL otimizada
2. **Pushdown de Filtros**: os filtros são aplicados no nível da fonte de dados
3. **Poda de Colunas**: apenas as colunas necessárias são lidas
4. **Decisões Adiadas**: o mecanismo de execução pode ser escolhido em tempo de execução
5. **Inspeção do Plano**: você pode visualizar e depurar a consulta antes de executá-la

***

<div id="triggers">
  ## Gatilhos de execução
</div>

A execução é acionada automaticamente quando você precisa dos valores reais:

<div id="automatic-triggers">
  ### Gatilhos automáticos
</div>

| Gatilho              | Exemplo            | Descrição                  |
| -------------------- | ------------------ | -------------------------- |
| `print()` / `repr()` | `print(ds)`        | Exibe os resultados        |
| `len()`              | `len(ds)`          | Obtém a contagem de linhas |
| `.columns`           | `ds.columns`       | Obtém os nomes das colunas |
| `.dtypes`            | `ds.dtypes`        | Obtém os tipos das colunas |
| `.shape`             | `ds.shape`         | Obtém as dimensões         |
| `.index`             | `ds.index`         | Obtém o índice das linhas  |
| `.values`            | `ds.values`        | Obtém o array NumPy        |
| Iteração             | `for row in ds`    | Itera sobre as linhas      |
| `to_df()`            | `ds.to_df()`       | Converte para pandas       |
| `to_pandas()`        | `ds.to_pandas()`   | Alias de to\_df            |
| `to_dict()`          | `ds.to_dict()`     | Converte para dict         |
| `to_numpy()`         | `ds.to_numpy()`    | Converte para array        |
| `.equals()`          | `ds.equals(other)` | Compara DataStores         |

**Exemplos:**

```python theme={null}
# Todos estes acionam a execução
print(ds)              # Exibir
len(ds)                # 1000
ds.columns             # Index(['name', 'age', 'city'])
ds.shape               # (1000, 3)
list(ds)               # Lista de valores
ds.to_df()             # pandas DataFrame
```

<div id="stay-lazy">
  ### Operações que permanecem preguiçosas
</div>

| Operação               | Retorna     | Descrição                   |
| ---------------------- | ----------- | --------------------------- |
| `filter()`             | DataStore   | Adiciona cláusula WHERE     |
| `select()`             | DataStore   | Adiciona seleção de colunas |
| `sort()`               | DataStore   | Adiciona ORDER BY           |
| `groupby()`            | LazyGroupBy | Prepara GROUP BY            |
| `join()`               | DataStore   | Adiciona JOIN               |
| `ds['col']`            | ColumnExpr  | Referência de coluna        |
| `ds[['col1', 'col2']]` | DataStore   | Seleção de colunas          |

**Exemplos:**

```python theme={null}
# Estas NÃO acionam a execução - permanecem preguiçosas
result = ds.filter(ds['age'] > 25)      # Retorna DataStore
result = ds.select('name', 'age')        # Retorna DataStore
result = ds['name']                      # Retorna ColumnExpr
result = ds.groupby('city')              # Retorna LazyGroupBy
```

***

<div id="three-phase">
  ## Execução em três fases
</div>

As operações do DataStore seguem um modelo de execução em três fases:

<div id="phase-1">
  ### Fase 1: Construção da consulta SQL (Preguiçoso)
</div>

As operações que podem ser expressas em SQL são acumuladas:

```python theme={null}
result = (ds
    .filter(ds['status'] == 'active')   # WHERE
    .select('user_id', 'amount')         # SELECT
    .groupby('user_id')                  # GROUP BY
    .agg({'amount': 'sum'})              # SUM()
    .sort('sum', ascending=False)        # ORDER BY
    .limit(10)                           # LIMIT
)
# Tudo compilado em uma única consulta SQL
```

<div id="phase-2">
  ### Fase 2: Ponto de execução
</div>

Quando um gatilho é acionado, o SQL acumulado é executado:

```python theme={null}
# Execução acionada aqui
df = result.to_df()  
# A consulta SQL otimizada é executada agora
```

<div id="phase-3">
  ### Fase 3: Operações com DataFrame (se houver)
</div>

Se você encadear operações apenas do pandas após a execução:

```python theme={null}
# Operações mistas
result = (ds
    .filter(ds['amount'] > 100)          # Fase 1: SQL
    .to_df()                             # Fase 2: Executar
    .pivot_table(...)                    # Fase 3: pandas
)
```

***

<div id="explain">
  ## Visualizando planos de execução
</div>

Use `explain()` para ver o que será executado:

```python title="Query" theme={null}
ds = pd.read_csv("sales.csv")

query = (ds
    .filter(ds['amount'] > 1000)
    .groupby('region')
    .agg({'amount': ['sum', 'mean']})
)

# Visualizar plano de execução
query.explain()
```

```text title="Response" theme={null}
Pipeline:
  1. Source: file('sales.csv', 'CSVWithNames')
  2. Filter: amount > 1000
  3. GroupBy: region
  4. Aggregate: sum(amount), avg(amount)

Generated SQL:
SELECT region, SUM(amount) AS sum, AVG(amount) AS mean
FROM file('sales.csv', 'CSVWithNames')
WHERE amount > 1000
GROUP BY region
```

Use `verbose=True` para obter mais detalhes:

```python theme={null}
query.explain(verbose=True)
```

Consulte [Depuração: explain()](/pt-BR/products/chdb/debugging/explain) para acessar a documentação completa.

***

<div id="caching">
  ## Armazenamento em cache
</div>

O DataStore armazena em cache os resultados da execução para evitar consultas redundantes.

<div id="how-caching">
  ### Como o cache funciona
</div>

```python theme={null}
from pathlib import Path
Path("data.csv").write_text("""\
name,age,city,salary,department
Alice,25,NYC,55000,Engineering
Bob,30,LA,65000,Product
Charlie,35,NYC,80000,Engineering
Diana,28,SF,70000,Design
Eve,42,NYC,95000,Product
""")

ds = pd.read_csv("data.csv")
result = ds.filter(ds['age'] > 25)

# Primeiro acesso - executa a consulta
print(result.shape)  # Executa e armazena em cache

# Segundo acesso - usa o cache
print(result.columns)  # Usa o resultado em cache

# Terceiro acesso - usa o cache
df = result.to_df()  # Usa o resultado em cache
```

<div id="cache-invalidation">
  ### Invalidação do cache
</div>

O cache é invalidado quando operações alteram o DataStore:

```python theme={null}
result = ds.filter(ds['age'] > 25)
print(result.shape)  # Executa, armazena em cache

# Nova operação invalida o cache
result2 = result.filter(result['city'] == 'NYC')
print(result2.shape)  # Reexecuta (consulta diferente)
```

<div id="cache-control">
  ### Controle manual do cache
</div>

```python theme={null}
# Limpar cache
ds.clear_cache()

# Desativar cache
from chdb.datastore.config import config
config.set_cache_enabled(False)
```

***

<div id="mixing">
  ## Combinando operações de SQL e Pandas
</div>

O DataStore lida de forma inteligente com operações que combinam SQL e pandas:

<div id="sql-ops">
  ### Operações compatíveis com SQL
</div>

São convertidas em SQL:

* `filter()`, `where()`
* `select()`
* `groupby()`, `agg()`
* `sort()`, `orderby()`
* `limit()`, `offset()`
* `join()`, `union()`
* `distinct()`
* Operações em colunas (matemática, comparação, métodos de string)

<div id="pandas-ops">
  ### Operações exclusivas do Pandas
</div>

Estas operações acionam a execução e usam o Pandas:

* `apply()` com funções personalizadas
* `pivot_table()` com agregações complexas
* `stack()`, `unstack()`
* Operações em DataFrames já executados

<div id="hybrid">
  ### Pipelines híbridos
</div>

```python theme={null}
# Fase SQL
result = (ds
    .filter(ds['amount'] > 100)      # SQL
    .groupby('category')              # SQL
    .agg({'amount': 'sum'})           # SQL
)

# Fase de execução + pandas
result = (result
    .to_df()                          # Executar SQL
    .pivot_table(...)                 # operação pandas
)
```

***

<div id="engine-selection">
  ## Seleção do mecanismo de execução
</div>

O DataStore pode executar operações com diferentes mecanismos:

<div id="auto-mode">
  ### Modo automático (padrão)
</div>

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

config.set_execution_engine('auto')  # Padrão
# Seleciona automaticamente o melhor mecanismo por operação
```

<div id="chdb-engine">
  ### Forçar o mecanismo chDB
</div>

```python theme={null}
config.set_execution_engine('chdb')
# Todas as operações usam ClickHouse SQL
```

<div id="pandas-engine">
  ### Forçar o mecanismo do pandas
</div>

```python theme={null}
config.set_execution_engine('pandas')
# Todas as operações usam pandas
```

Consulte [Configuração: Mecanismo de execução](/pt-BR/products/chdb/configuration/execution-engine) para mais detalhes.

***

<div id="performance">
  ## Impactos no desempenho
</div>

<div id="filter-early">
  ### Bom: aplique o filtro no início
</div>

```python theme={null}
# Bom: Filtrar no SQL, depois agregar
result = (ds
    .filter(ds['date'] >= '2024-01-01')  # Reduz os dados antecipadamente
    .groupby('category')
    .agg({'amount': 'sum'})
)
```

<div id="filter-late">
  ### Ruim: filtrar só no fim
</div>

```python theme={null}
# Ruim: Agregar tudo e depois filtrar
result = (ds
    .groupby('category')
    .agg({'amount': 'sum'})
    .to_df()
    .query('sum > 1000')  # Filtro do Pandas após a agregação
)
```

<div id="select-early">
  ### Bom: selecione as colunas desde o início
</div>

```python theme={null}
# Bom: Selecionar colunas em SQL
result = (ds
    .select('user_id', 'amount', 'date')
    .filter(ds['date'] >= '2024-01-01')
    .groupby('user_id')
    .agg({'amount': 'sum'})
)
```

<div id="sql-work">
  ### Bom: deixe o SQL fazer o trabalho
</div>

```python theme={null}
# Bom: Agregação complexa em SQL
result = (ds
    .groupby('category')
    .agg({
        'amount': ['sum', 'mean', 'count'],
        'quantity': 'sum'
    })
    .sort('sum', ascending=False)
    .limit(10)
)
# Uma consulta SQL faz tudo

# Ruim: Múltiplas consultas separadas
sums = ds.groupby('category')['amount'].sum().to_df()
means = ds.groupby('category')['amount'].mean().to_df()
# Duas consultas em vez de uma
```

***

<div id="best-practices">
  ## Resumo das práticas recomendadas
</div>

1. **Encadeie as operações antes de executar** - Monte a consulta completa e só então acione a execução uma vez
2. **Filtre o quanto antes** - Reduza os dados na origem
3. **Selecione apenas as colunas necessárias** - A eliminação de colunas melhora o desempenho
4. **Use `explain()` para entender a execução** - Depure antes de executar
5. **Deixe o SQL cuidar das agregações** - O ClickHouse é otimizado para isso
6. **Fique atento aos gatilhos de execução** - Evite execuções antecipadas acidentais
7. **Use cache com critério** - Entenda quando o cache é invalidado