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

# Operações de E/S do DataStore

> Leitura e gravação de dados com o DataStore - todos os formatos e destinos compatíveis

O DataStore oferece suporte à leitura e à gravação de dados em diversos formatos de arquivo e fontes de dados.

<div id="reading">
  ## Lendo dados
</div>

<div id="read-csv">
  ### Arquivos CSV
</div>

```python theme={null}
read_csv(filepath_or_buffer, sep=',', header='infer', names=None, 
         usecols=None, dtype=None, nrows=None, skiprows=None,
         compression=None, encoding=None, **kwargs)
```

**Exemplos:**

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

# Leitura básica de CSV
ds = pd.read_csv("data.csv")

# Com opções
ds = pd.read_csv(
    "data.csv",
    sep=";",                    # Delimitador personalizado
    header=0,                   # Índice da linha de cabeçalho
    names=['a', 'b', 'c'],      # Nomes de colunas personalizados
    usecols=['a', 'b'],         # Ler apenas colunas específicas
    dtype={'a': 'Int64'},       # Especificar tipos de dados
    nrows=1000,                 # Ler apenas as primeiras 1000 linhas
    skiprows=1,                 # Ignorar a primeira linha
    compression='gzip',         # Arquivo comprimido
    encoding='utf-8'            # Codificação
)

# A partir de URL
ds = pd.read_csv("https://example.com/data.csv")
```

<div id="read-parquet">
  ### Arquivos Parquet
</div>

Recomendado para grandes conjuntos de dados — formato colunar com melhor compressão.

```python theme={null}
read_parquet(path, columns=None, **kwargs)
```

**Exemplos:**

```python theme={null}
# Leitura básica de Parquet
ds = pd.read_parquet("data.parquet")

# Lê apenas colunas específicas (eficiente - lê somente os dados necessários)
ds = pd.read_parquet("data.parquet", columns=['col1', 'col2', 'col3'])

# A partir do S3
ds = pd.read_parquet("s3://bucket/data.parquet")
```

<div id="read-json">
  ### Arquivos JSON
</div>

```python theme={null}
read_json(path_or_buf, orient=None, lines=False, **kwargs)
```

**Exemplos:**

```python theme={null}
# JSON padrão
ds = pd.read_json("data.json")

# JSON Lines (delimitado por nova linha)
ds = pd.read_json("data.jsonl", lines=True)

# JSON com orientação específica
ds = pd.read_json("data.json", orient='records')
```

<div id="read-excel">
  ### Arquivos Excel
</div>

```python theme={null}
read_excel(io, sheet_name=0, header=0, names=None, **kwargs)
```

**Exemplos:**

```python theme={null}
# Lê a primeira planilha
ds = pd.read_excel("data.xlsx")

# Lê uma planilha específica
ds = pd.read_excel("data.xlsx", sheet_name="Sheet1")
ds = pd.read_excel("data.xlsx", sheet_name=2)  # Terceira planilha

# Lê múltiplas planilhas (retorna dict)
sheets = pd.read_excel("data.xlsx", sheet_name=['Sheet1', 'Sheet2'])
```

<div id="read-sql">
  ### Bancos de dados SQL
</div>

```python theme={null}
read_sql(sql, con, **kwargs)
```

**Exemplos:**

```python theme={null}
# Ler a partir de uma consulta SQL
ds = pd.read_sql("SELECT * FROM users", connection)
ds = pd.read_sql("SELECT * FROM orders WHERE date > '2024-01-01'", connection)
```

<div id="read-other">
  ### Outros formatos
</div>

```python theme={null}
# Feather (Arrow)
ds = pd.read_feather("data.feather")

# ORC
ds = pd.read_orc("data.orc")

# Pickle
ds = pd.read_pickle("data.pkl")

# Formatado com largura fixa
ds = pd.read_fwf("data.txt", widths=[10, 20, 15])

# Tabelas HTML
ds = pd.read_html("https://example.com/table.html")[0]
```

***

<div id="writing">
  ## Gravação de dados
</div>

<div id="to-csv">
  ### to\_csv
</div>

Exportar em formato CSV.

```python theme={null}
to_csv(path_or_buf=None, sep=',', na_rep='', header=True, 
       index=True, mode='w', compression=None, **kwargs)
```

**Exemplos:**

```python theme={null}
ds = pd.read_parquet("data.parquet")

# Exportação básica
ds.to_csv("output.csv")

# Com opções
ds.to_csv(
    "output.csv",
    sep=";",                    # Delimitador personalizado
    index=False,                # Não incluir índice
    header=True,                # Incluir cabeçalho
    na_rep='NULL',              # Representar NaN como 'NULL'
    compression='gzip'          # Compactar saída
)

# Para string
csv_string = ds.to_csv()
```

<div id="to-parquet">
  ### to\_parquet
</div>

Exporte no formato Parquet (recomendado para grandes volumes de dados).

```python theme={null}
to_parquet(path, engine='pyarrow', compression='snappy', **kwargs)
```

**Exemplos:**

```python theme={null}
# Exportação básica
ds.to_parquet("output.parquet")

# Com opções de compressão
ds.to_parquet("output.parquet", compression='gzip')
ds.to_parquet("output.parquet", compression='zstd')

# Saída particionada
ds.to_parquet(
    "output/",
    partition_cols=['year', 'month']
)
```

<div id="to-json">
  ### to\_json
</div>

Exporta no formato JSON.

```python theme={null}
to_json(path_or_buf=None, orient='records', lines=False, **kwargs)
```

**Exemplos:**

```python theme={null}
# JSON padrão (array de registros)
ds.to_json("output.json", orient='records')

# JSON Lines (um objeto JSON por linha)
ds.to_json("output.jsonl", lines=True)

# Diferentes orientações
ds.to_json("output.json", orient='split')    # {columns, data, index}
ds.to_json("output.json", orient='records')  # [{col: val}, ...]
ds.to_json("output.json", orient='columns')  # {col: {idx: val}}

# Para string
json_string = ds.to_json()
```

<div id="to-excel">
  ### to\_excel
</div>

Exporta em formato Excel.

```python theme={null}
to_excel(excel_writer, sheet_name='Sheet1', index=True, **kwargs)
```

**Exemplos:**

```python theme={null}
# Planilha única
ds.to_excel("output.xlsx")
ds.to_excel("output.xlsx", sheet_name="Data", index=False)

# Múltiplas planilhas
with pd.ExcelWriter("output.xlsx") as writer:
    ds1.to_excel(writer, sheet_name="Sales")
    ds2.to_excel(writer, sheet_name="Inventory")
```

<div id="to-sql-method">
  ### to\_sql
</div>

Exportar para um banco de dados SQL ou gerar uma string SQL.

```python theme={null}
to_sql(name=None, con=None, schema=None, if_exists='fail', **kwargs)
```

**Exemplos:**

```python theme={null}
# Gerar consulta SQL (sem execução)
sql = ds.to_sql()
print(sql)
# SELECT ...
# FROM ...
# WHERE ...

# Gravar no banco de dados
ds.to_sql("table_name", connection, if_exists='replace')
```

<div id="to-other">
  ### Outros métodos de exportação
</div>

```python theme={null}
# Para pandas DataFrame
df = ds.to_df()
df = ds.to_pandas()

# Para Arrow Table
table = ds.to_arrow()

# Para array NumPy
arr = ds.to_numpy()

# Para dicionário
d = ds.to_dict()
d = ds.to_dict(orient='records')  # Lista de dicionários
d = ds.to_dict(orient='list')     # Dicionário de listas

# Para registros (lista de tuplas)
records = ds.to_records()

# Para string
s = ds.to_string()
s = ds.to_string(max_rows=100)

# Para Markdown
md = ds.to_markdown()

# Para HTML
html = ds.to_html()

# Para LaTeX
latex = ds.to_latex()

# Para área de transferência
ds.to_clipboard()

# Para pickle
ds.to_pickle("output.pkl")

# Para feather
ds.to_feather("output.feather")
```

***

<div id="format-comparison">
  ## Comparação entre formatos de arquivo
</div>

| Formato     | Velocidade de leitura | Velocidade de escrita | Tamanho do arquivo | Esquema | Melhor para                                |
| ----------- | --------------------- | --------------------- | ------------------ | ------- | ------------------------------------------ |
| **Parquet** | Rápida                | Rápida                | Pequeno            | Sim     | Grandes volumes de dados, análises         |
| **CSV**     | Média                 | Rápida                | Grande             | Não     | Compatibilidade, dados simples             |
| **JSON**    | Lenta                 | Média                 | Grande             | Parcial | APIs, dados aninhados                      |
| **Excel**   | Lenta                 | Lenta                 | Médio              | Parcial | Compartilhamento com usuários não técnicos |
| **Feather** | Muito rápida          | Muito rápida          | Médio              | Sim     | Comunicação entre processos, pandas        |

<div id="recommendations">
  ### Recomendações
</div>

1. **Para workloads de analytics:** Use Parquet
   * O formato colunar permite ler apenas as colunas necessárias
   * Excelente compressão
   * Preserva os tipos de dados

2. **Para troca de dados:** Use CSV ou JSON
   * Compatibilidade universal
   * Legível para humanos

3. **Para interoperabilidade com pandas:** Use Feather ou Arrow
   * Serialização mais rápida
   * Preserva os tipos

***

<div id="compression">
  ## Suporte à compressão
</div>

<div id="read-compressed">
  ### Leitura de arquivos comprimidos
</div>

```python theme={null}
# Detecção automática pela extensão
ds = pd.read_csv("data.csv.gz")
ds = pd.read_csv("data.csv.bz2")
ds = pd.read_csv("data.csv.xz")
ds = pd.read_csv("data.csv.zst")

# Compressão explícita
ds = pd.read_csv("data.csv", compression='gzip')
```

<div id="write-compressed">
  ### Gravação de Arquivos Comprimidos
</div>

```python theme={null}
# CSV com compressão
ds.to_csv("output.csv.gz", compression='gzip')
ds.to_csv("output.csv.bz2", compression='bz2')

# Parquet (sempre comprimido)
ds.to_parquet("output.parquet", compression='snappy')  # Padrão
ds.to_parquet("output.parquet", compression='gzip')
ds.to_parquet("output.parquet", compression='zstd')    # Melhor taxa
ds.to_parquet("output.parquet", compression='lz4')     # Mais rápido
```

<div id="compression-options">
  ### Opções de Compressão
</div>

| Compressão | Velocidade   | Taxa de compressão | Caso de uso                |
| ---------- | ------------ | ------------------ | -------------------------- |
| `snappy`   | Muito rápida | Baixa              | Padrão para Parquet        |
| `lz4`      | Muito rápida | Baixa              | Prioridade para velocidade |
| `gzip`     | Média        | Alta               | Compatibilidade            |
| `zstd`     | Rápida       | Muito alta         | Melhor equilíbrio          |
| `bz2`      | Lenta        | Muito alta         | Compressão máxima          |

***

<div id="streaming">
  ## E/S de streaming
</div>

Para arquivos muito grandes que não cabem na memória:

<div id="chunked-read">
  ### Leitura em fragmentos
</div>

```python theme={null}
# Ler em fragmentos
for chunk in pd.read_csv("large.csv", chunksize=100000):
    # Processar cada fragmento
    process(chunk)

# Usando iterador
reader = pd.read_csv("large.csv", iterator=True)
chunk = reader.get_chunk(10000)
```

<div id="clickhouse-streaming">
  ### Usando o ClickHouse Streaming
</div>

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

# Transmite do arquivo sem carregar tudo na memória
ds = DataStore.from_file("huge.parquet")

# As operações são lazy - computa apenas o necessário
result = ds.filter(ds['amount'] > 1000).head(100)
```

***

<div id="remote">
  ## Fontes de dados remotas
</div>

<div id="http">
  ### HTTP/HTTPS
</div>

```python theme={null}
# Ler de URL
ds = pd.read_csv("https://example.com/data.csv")
ds = pd.read_parquet("https://example.com/data.parquet")
```

<div id="s3">
  ### S3
</div>

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

# Acesso anônimo
ds = DataStore.uri("s3://bucket/data.parquet?nosign=true")

# Com credenciais
ds = DataStore.from_s3(
    "s3://bucket/data.parquet",
    access_key_id="KEY",
    secret_access_key="SECRET"
)
```

<div id="cloud">
  ### GCS, Azure, HDFS
</div>

Consulte [Métodos de fábrica](/pt-BR/products/chdb/datastore/factory-methods) para ver as opções de armazenamento em nuvem.

***

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

<div id="use-parquet-for-large-files">
  ### 1. Use o Parquet para arquivos grandes
</div>

```python theme={null}
# Converta CSV para Parquet para melhor desempenho
ds = pd.read_csv("large.csv")
ds.to_parquet("large.parquet")

# Leituras futuras são muito mais rápidas
ds = pd.read_parquet("large.parquet")
```

<div id="select-only-needed-columns">
  ### 2. Selecione apenas as colunas necessárias
</div>

```python theme={null}
# Eficiente - lê apenas col1 e col2
ds = pd.read_parquet("data.parquet", columns=['col1', 'col2'])

# Ineficiente - lê todas as colunas e depois filtra
ds = pd.read_parquet("data.parquet")[['col1', 'col2']]
```

<div id="use-compression">
  ### 3. Use compressão
</div>

```python theme={null}
# Tamanho de arquivo menor, geralmente mais rápido devido a menos E/S
ds.to_parquet("output.parquet", compression='zstd')
```

<div id="batch-writes">
  ### 4. Escritas em lote
</div>

```python theme={null}
# Escreva uma vez, não em um loop
result = process_all_data(ds)
result.to_parquet("output.parquet")

# NÃO faça isso (ineficiente)
for chunk in chunks:
    chunk.to_parquet(f"output_{i}.parquet")
```