Métodos de fábrica do DataStore - ClickHouse Documentation

O DataStore oferece mais de 20 métodos de fábrica para criar instâncias a partir de diversas fontes de dados, incluindo arquivos locais, bancos de dados, armazenamento em nuvem e lagos de dados.

Interface universal de URI

O método uri() é o ponto de entrada universal recomendado, que detecta automaticamente o tipo da origem:

from chdb.datastore import DataStore

# Arquivos locais
ds = DataStore.uri("data.csv")
ds = DataStore.uri("/path/to/data.parquet")

# Armazenamento em nuvem
ds = DataStore.uri("s3://bucket/data.parquet?nosign=true")
ds = DataStore.uri("https://example.com/data.csv")

# Bancos de dados
ds = DataStore.uri("mysql://user:pass@host:3306/db/table")
ds = DataStore.uri("postgresql://user:pass@host:5432/db/table")

Referência da sintaxe de URI

tipo de origem	Formato de URI	Exemplo
Arquivo local	`path/to/file`	`data.csv`, `/abs/path/data.parquet`
S3	`s3://bucket/path`	`s3://mybucket/data.parquet?nosign=true`
GCS	`gs://bucket/path`	`gs://mybucket/data.csv`
Azure	`az://container/path`	`az://mycontainer/data.parquet`
HTTP/HTTPS	`https://url`	`https://example.com/data.csv`
MySQL	`mysql://user:pass@host:port/db/table`	`mysql://root:pass@localhost:3306/mydb/users`
PostgreSQL	`postgresql://user:pass@host:port/db/table`	`postgresql://postgres:pass@localhost:5432/mydb/users`
SQLite	`sqlite:///path?table=name`	`sqlite:///data.db?table=users`
ClickHouse	`clickhouse://host:port/db/table`	`clickhouse://localhost:9000/default/hits`

Fontes de arquivo

`from_file`

Cria um DataStore a partir de um arquivo local ou remoto, com detecção automática de formato.

DataStore.from_file(path, format=None, compression=None, **kwargs)

Parâmetros:

Parâmetro	Tipo	Padrão	Descrição
`path`	str	obrigatório	Caminho do arquivo (local ou URL)
`format`	str	`None`	Formato do arquivo (detectado automaticamente se for `None`)
`compression`	str	`None`	Tipo de compressão (detectado automaticamente se for `None`)

Formatos suportados: CSV, TSV, Parquet, JSON, JSONLines, ORC, Avro, Arrow Exemplos:

from chdb.datastore import DataStore

# Detectar formato automaticamente pela extensão
ds = DataStore.from_file("data.csv")
ds = DataStore.from_file("data.parquet")
ds = DataStore.from_file("data.json")

# Formato explícito
ds = DataStore.from_file("data.txt", format="CSV")

# Com compressão
ds = DataStore.from_file("data.csv.gz", compression="gzip")

Funções de leitura compatíveis com o Pandas

from chdb import datastore as pd

# Arquivos CSV
ds = pd.read_csv("data.csv")
ds = pd.read_csv("data.csv", sep=";", header=0, nrows=1000)

# Arquivos Parquet (recomendado para grandes conjuntos de dados)
ds = pd.read_parquet("data.parquet")
ds = pd.read_parquet("data.parquet", columns=['col1', 'col2'])

# Arquivos JSON
ds = pd.read_json("data.json")
ds = pd.read_json("data.jsonl", lines=True)

# Arquivos Excel
ds = pd.read_excel("data.xlsx", sheet_name="Sheet1")

Armazenamento em nuvem

`from_s3`

Cria um DataStore a partir do Amazon S3.

DataStore.from_s3(url, access_key_id=None, secret_access_key=None, format=None, **kwargs)

Parâmetros:

Parâmetro	Tipo	Padrão	Descrição
`url`	str	obrigatório	URL do S3 (s3://bucket/path)
`access_key_id`	str	`None`	ID da chave de acesso AWS
`secret_access_key`	str	`None`	Chave de acesso secreta AWS
`format`	str	`None`	Formato do arquivo (detectado automaticamente)

Exemplos:

from chdb.datastore import DataStore

# Acesso anônimo (bucket público)
ds = DataStore.from_s3("s3://bucket/data.parquet")

# Com credenciais
ds = DataStore.from_s3(
    "s3://bucket/data.parquet",
    access_key_id="AKIAIOSFODNN7EXAMPLE",
    secret_access_key="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
)

# Usando URI com parâmetros de consulta
ds = DataStore.uri("s3://bucket/data.parquet?nosign=true")
ds = DataStore.uri("s3://bucket/data.parquet?access_key_id=KEY&secret_access_key=SECRET")

`from_gcs`

Cria um DataStore a partir do Google Cloud Storage.

DataStore.from_gcs(url, credentials_path=None, **kwargs)

Exemplos:

ds = DataStore.from_gcs("gs://bucket/data.parquet")
ds = DataStore.from_gcs("gs://bucket/data.parquet", credentials_path="/path/to/creds.json")

`from_azure`

Cria um DataStore a partir do Azure Blob Storage.

DataStore.from_azure(url, account_name=None, account_key=None, **kwargs)

Exemplos:

ds = DataStore.from_azure(
    "az://container/data.parquet",
    account_name="myaccount",
    account_key="mykey"
)

`from_hdfs`

Cria um DataStore a partir do HDFS.

DataStore.from_hdfs(url, **kwargs)

Exemplos:

ds = DataStore.from_hdfs("hdfs://namenode:8020/path/data.parquet")

`from_url`

Cria um DataStore a partir de uma URL HTTP/HTTPS.

DataStore.from_url(url, format=None, **kwargs)

Exemplos:

ds = DataStore.from_url("https://example.com/data.csv")
ds = DataStore.from_url("https://raw.githubusercontent.com/user/repo/main/data.parquet")

Bancos de dados

`from_mysql`

Cria um DataStore a partir de um banco de dados MySQL.

DataStore.from_mysql(host, database, table, user, password, port=3306, **kwargs)

Parâmetros:

Parâmetro	Tipo	Padrão	Descrição
`host`	str	obrigatório	Host do MySQL
`database`	str	obrigatório	Nome do banco de dados
`table`	str	obrigatório	Nome da tabela
`user`	str	obrigatório	Nome de usuário
`password`	str	obrigatório	Senha
`port`	int	`3306`	Número da porta

Exemplos:

ds = DataStore.from_mysql(
    host="localhost",
    database="mydb",
    table="users",
    user="root",
    password="password"
)

# Usando URI
ds = DataStore.uri("mysql://root:password@localhost:3306/mydb/users")

`from_postgresql`

Cria um DataStore a partir de um banco de dados PostgreSQL.

DataStore.from_postgresql(host, database, table, user, password, port=5432, **kwargs)

Exemplos:

ds = DataStore.from_postgresql(
    host="localhost",
    database="mydb",
    table="users",
    user="postgres",
    password="password"
)

# Usando URI
ds = DataStore.uri("postgresql://postgres:password@localhost:5432/mydb/users")

`from_clickhouse`

Cria um DataStore a partir do servidor ClickHouse.

DataStore.from_clickhouse(host, database, table, user=None, password=None, port=9000, **kwargs)

Exemplos:

ds = DataStore.from_clickhouse(
    host="localhost",
    database="default",
    table="hits",
    user="default",
    password=""
)

# Modo de nível de conexão (explorar bancos de dados)
ds = DataStore.from_clickhouse(
    host="analytics.company.com",
    user="analyst",
    password="secret"
)
ds.databases()                  # Listar bancos de dados
ds.tables("production")         # Listar tabelas
result = ds.sql("SELECT * FROM production.users LIMIT 10")

`from_mongodb`

Cria um DataStore a partir do MongoDB.

DataStore.from_mongodb(uri, database, collection, **kwargs)

Exemplos:

ds = DataStore.from_mongodb(
    uri="mongodb://localhost:27017",
    database="mydb",
    collection="users"
)

`from_sqlite`

Cria um DataStore a partir de um banco de dados SQLite.

DataStore.from_sqlite(database_path, table, **kwargs)

Exemplos:

ds = DataStore.from_sqlite("data.db", table="users")

# Usando URI
ds = DataStore.uri("sqlite:///data.db?table=users")

Lagos de dados

`from_iceberg`

Cria um DataStore a partir de uma tabela Apache Iceberg.

DataStore.from_iceberg(path, **kwargs)

Exemplos:

ds = DataStore.from_iceberg("/path/to/iceberg_table")
ds = DataStore.uri("iceberg://catalog/namespace/table")

`from_delta`

Cria um DataStore a partir de uma tabela Delta Lake.

DataStore.from_delta(path, **kwargs)

Exemplos:

ds = DataStore.from_delta("/path/to/delta_table")
ds = DataStore.uri("deltalake:///path/to/delta_table")

`from_hudi`

Cria um DataStore a partir de uma tabela Hudi do Apache.

DataStore.from_hudi(path, **kwargs)

Exemplos:

ds = DataStore.from_hudi("/path/to/hudi_table")
ds = DataStore.uri("hudi:///path/to/hudi_table")

Fontes em memória

`from_df` / `from_dataframe`

Cria um DataStore a partir de um DataFrame do pandas.

DataStore.from_df(df, name=None)
DataStore.from_dataframe(df, name=None)  # alias

Exemplos:

import pandas
from chdb.datastore import DataStore

pdf = pandas.DataFrame({'a': [1, 2, 3], 'b': ['x', 'y', 'z']})
ds = DataStore.from_df(pdf)

Construtor de `DataFrame`

Crie um DataStore com um construtor semelhante ao do pandas.

from chdb import datastore as pd

# A partir de dicionário
ds = pd.DataFrame({
    'name': ['Alice', 'Bob'],
    'age': [25, 30]
})

# A partir de um DataFrame do pandas
import pandas
pdf = pandas.DataFrame({'a': [1, 2, 3]})
ds = pd.DataFrame(pdf)

Fontes especiais

`from_numbers`

Cria um DataStore com números sequenciais (útil para testes).

DataStore.from_numbers(count, **kwargs)

Exemplos:

ds = DataStore.from_numbers(1000000)  # 1M linhas com coluna 'number'
result = ds.filter(ds['number'] % 2 == 0).head(10)  # Números pares

`from_random`

Cria um DataStore com dados aleatórios.

DataStore.from_random(rows, columns, **kwargs)

Exemplos:

ds = DataStore.from_random(rows=1000, columns=5)

`run_sql`

Cria um DataStore a partir de uma consulta SQL em texto puro.

DataStore.run_sql(query)

Exemplos:

ds = DataStore.run_sql("""
    SELECT number, number * 2 as doubled
    FROM numbers(100)
    WHERE number % 10 = 0
""")

Tabela de resumo

Método	Tipo de origem	Exemplo
`uri()`	Universal	`DataStore.uri("s3://bucket/data.parquet")`
`from_file()`	Arquivos locais/remotos	`DataStore.from_file("data.csv")`
`read_csv()`	Arquivos CSV	`pd.read_csv("data.csv")`
`read_parquet()`	Arquivos Parquet	`pd.read_parquet("data.parquet")`
`from_s3()`	Amazon S3	`DataStore.from_s3("s3://bucket/path")`
`from_gcs()`	Google Cloud Storage	`DataStore.from_gcs("gs://bucket/path")`
`from_azure()`	Azure Blob	`DataStore.from_azure("az://container/path")`
`from_hdfs()`	HDFS	`DataStore.from_hdfs("hdfs://host/path")`
`from_url()`	HTTP/HTTPS	`DataStore.from_url("https://example.com/data.csv")`
`from_mysql()`	MySQL	`DataStore.from_mysql(host, db, table, user, pass)`
`from_postgresql()`	PostgreSQL	`DataStore.from_postgresql(host, db, table, user, pass)`
`from_clickhouse()`	ClickHouse	`DataStore.from_clickhouse(host, db, table)`
`from_mongodb()`	MongoDB	`DataStore.from_mongodb(uri, db, collection)`
`from_sqlite()`	SQLite	`DataStore.from_sqlite("data.db", table)`
`from_iceberg()`	Apache Iceberg	`DataStore.from_iceberg("/path/to/table")`
`from_delta()`	Delta Lake	`DataStore.from_delta("/path/to/table")`
`from_hudi()`	Apache Hudi	`DataStore.from_hudi("/path/to/table")`
`from_df()`	DataFrame do pandas	`DataStore.from_df(pandas_df)`
`DataFrame()`	Dicionário/DataFrame	`pd.DataFrame({'a': [1, 2, 3]})`
`from_numbers()`	Números em sequência	`DataStore.from_numbers(1000000)`
`from_random()`	Dados aleatórios	`DataStore.from_random(rows=1000, columns=5)`
`run_sql()`	SQL puro	`DataStore.run_sql("SELECT * FROM ...")`

​Interface universal de URI

​Referência da sintaxe de URI

​Fontes de arquivo

​from_file

​Funções de leitura compatíveis com o Pandas

​Armazenamento em nuvem

​from_s3

​from_gcs

​from_azure

​from_hdfs

​from_url

​Bancos de dados

​from_mysql

​from_postgresql

​from_clickhouse

​from_mongodb

​from_sqlite

​Lagos de dados

​from_iceberg

​from_delta

​from_hudi

​Fontes em memória

​from_df / from_dataframe

​Construtor de DataFrame

​Fontes especiais

​from_numbers

​from_random

​run_sql

​Tabela de resumo

Interface universal de URI

Referência da sintaxe de URI

Fontes de arquivo

`from_file`

Funções de leitura compatíveis com o Pandas

Armazenamento em nuvem

`from_s3`

`from_gcs`

`from_azure`

`from_hdfs`

`from_url`

Bancos de dados

`from_mysql`

`from_postgresql`

`from_clickhouse`

`from_mongodb`

`from_sqlite`

Lagos de dados

`from_iceberg`

`from_delta`

`from_hudi`

Fontes em memória

`from_df` / `from_dataframe`

Construtor de `DataFrame`

Fontes especiais

`from_numbers`

`from_random`

`run_sql`

Tabela de resumo