Métodos de fábrica do DataStore

Crie instâncias do DataStore a partir de arquivos, bancos de dados, armazenamento em nuvem e lagos de dados

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 ...")