Referência da classe DataStore - ClickHouse Documentation

Esta referência documenta as principais classes da API do DataStore.

DataStore

A principal classe semelhante a um DataFrame para manipulação de dados.

from chdb.datastore import DataStore

Construtor

DataStore(data=None, columns=None, index=None, dtype=None, copy=None)

Parâmetros:

Parâmetro	Tipo	Descrição
`data`	dict/list/DataFrame/DataStore	Dados de entrada
`columns`	list	Nomes das colunas
`index`	Index	Índice da linha
`dtype`	dict	Tipos de dados das colunas
`copy`	bool	Copiar os dados

Exemplos:

# A partir de um dicionário
ds = DataStore({'a': [1, 2, 3], 'b': ['x', 'y', 'z']})

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

# DataStore vazio
ds = DataStore()

Propriedades

Propriedade	Tipo	Descrição
`columns`	Index	Nomes das colunas
`dtypes`	Series	Tipos de dados das colunas
`shape`	tuple	(linhas, colunas)
`size`	int	Total de elementos
`ndim`	int	Número de dimensões (2)
`empty`	bool	Se o DataFrame está vazio
`values`	ndarray	Dados subjacentes em um array NumPy
`index`	Index	Índice das linhas
`T`	DataStore	Transposição
`axes`	list	Lista de eixos

Métodos de fábrica

Método	Descrição
`uri(uri)`	Fábrica universal baseada em URI
`from_file(path, ...)`	Criar a partir de um arquivo
`from_df(df)`	Criar a partir de um DataFrame do pandas
`from_s3(url, ...)`	Criar a partir do S3
`from_gcs(url, ...)`	Criar a partir do Google Cloud Storage
`from_azure(url, ...)`	Criar a partir do Azure Blob
`from_mysql(...)`	Criar a partir do MySQL
`from_postgresql(...)`	Criar a partir do PostgreSQL
`from_clickhouse(...)`	Criar a partir do ClickHouse
`from_mongodb(...)`	Criar a partir do MongoDB
`from_sqlite(...)`	Criar a partir do SQLite
`from_iceberg(path)`	Criar a partir de uma tabela Iceberg
`from_delta(path)`	Criar a partir do Delta Lake
`from_numbers(n)`	Criar com números sequenciais
`from_random(rows, cols)`	Criar com dados aleatórios
`run_sql(query)`	Criar a partir de uma consulta SQL

Consulte Métodos de fábrica para detalhes.

Métodos de consulta

Método	Retorna	Descrição
`select(*cols)`	DataStore	Seleciona colunas
`filter(condition)`	DataStore	Filtra linhas
`where(condition)`	DataStore	Alias de filter
`sort(*cols, ascending=True)`	DataStore	Ordena linhas
`orderby(*cols)`	DataStore	Alias de sort
`limit(n)`	DataStore	Limita linhas
`offset(n)`	DataStore	Ignora linhas
`distinct(subset=None)`	DataStore	Remove duplicatas
`groupby(*cols)`	LazyGroupBy	Agrupa linhas
`having(condition)`	DataStore	Filtra grupos
`join(right, ...)`	DataStore	Faz join entre DataStores
`union(other, all=False)`	DataStore	Combina DataStores
`when(cond, val)`	CaseWhen	CASE WHEN

Consulte Construção de consultas para mais detalhes.

Métodos compatíveis com o pandas

Consulte Compatibilidade com o pandas para ver a lista completa de 209 métodos. Indexação: head(), tail(), sample(), loc, iloc, at, iat, query(), isin(), where(), mask(), get(), xs(), pop() Agregação: sum(), mean(), std(), var(), min(), max(), median(), count(), nunique(), quantile(), describe(), corr(), cov(), skew(), kurt() Manipulação: drop(), drop_duplicates(), dropna(), fillna(), replace(), rename(), assign(), astype(), copy() Ordenação: sort_values(), sort_index(), nlargest(), nsmallest(), rank() Reformatação: pivot(), pivot_table(), melt(), stack(), unstack(), transpose(), explode(), squeeze() Combinação: merge(), join(), concat(), append(), combine(), update(), compare() Aplicação/Transformação: apply(), applymap(), map(), agg(), transform(), pipe(), groupby() Séries temporais: rolling(), expanding(), ewm(), shift(), diff(), pct_change(), resample()

Métodos de E/S

Método	Descrição
`to_csv(path, ...)`	Exportar para CSV
`to_parquet(path, ...)`	Exportar para Parquet
`to_json(path, ...)`	Exportar para JSON
`to_excel(path, ...)`	Exportar para Excel
`to_df()`	Converter para DataFrame do pandas
`to_pandas()`	Alias de `to_df`
`to_arrow()`	Converter para tabela Arrow
`to_dict(orient)`	Converter para dicionário
`to_records()`	Converter para registros
`to_numpy()`	Converter para array NumPy
`to_sql()`	Gerar string SQL
`to_string()`	Representação em string
`to_markdown()`	Tabela Markdown
`to_html()`	Tabela HTML

Consulte Operações de E/S para mais detalhes.

Métodos de depuração

Método	Descrição
`explain(verbose=False)`	Exibir plano de execução
`clear_cache()`	Limpar resultados em cache

Consulte Depuração para mais detalhes.

Métodos Mágicos

Método	Descrição
`__getitem__(key)`	`ds['col']`, `ds[['a', 'b']]`, `ds[condition]`
`__setitem__(key, value)`	`ds['col'] = value`
`__delitem__(key)`	`del ds['col']`
`__len__()`	`len(ds)`
`__iter__()`	`for col in ds`
`__contains__(key)`	`'col' in ds`
`__repr__()`	`repr(ds)`
`__str__()`	`str(ds)`
`__eq__(other)`	`ds == other`
`__ne__(other)`	`ds != other`
`__lt__(other)`	`ds < other`
`__le__(other)`	`ds <= other`
`__gt__(other)`	`ds > other`
`__ge__(other)`	`ds >= other`
`__add__(other)`	`ds + other`
`__sub__(other)`	`ds - other`
`__mul__(other)`	`ds * other`
`__truediv__(other)`	`ds / other`
`__floordiv__(other)`	`ds // other`
`__mod__(other)`	`ds % other`
`__pow__(other)`	`ds ** other`
`__and__(other)`	`ds & other`
`__or__(other)`	`ds	other`
`__invert__()`	`~ds`
`__neg__()`	`-ds`
`__pos__()`	`+ds`
`__abs__()`	`abs(ds)`

ColumnExpr

Representa uma expressão de coluna para avaliação preguiçosa. É retornada ao acessar uma coluna.

# ColumnExpr é retornado automaticamente
col = ds['name']  # Retorna ColumnExpr

Propriedades

Propriedade	Tipo	Descrição
`name`	str	Nome da coluna
`dtype`	dtype	Tipo de dados

Acessores

Acessor	Descrição	Métodos
`.str`	Operações com strings	56 métodos
`.dt`	Operações de data e hora	42+ métodos
`.arr`	Operações com arrays	37 métodos
`.json`	Processamento de JSON	13 métodos
`.url`	Processamento de URL	15 métodos
`.ip`	Operações com endereços IP	9 métodos
`.geo`	Operações geoespaciais/de distância	14 métodos

Consulte Acessores para ver a documentação completa.

Operações aritméticas

ds['total'] = ds['price'] * ds['quantity']
ds['profit'] = ds['revenue'] - ds['cost']
ds['ratio'] = ds['a'] / ds['b']
ds['squared'] = ds['value'] ** 2
ds['remainder'] = ds['value'] % 10

Operações de comparação

ds[ds['age'] > 25]           # Maior que
ds[ds['age'] >= 25]          # Maior ou igual
ds[ds['age'] < 25]           # Menor que
ds[ds['age'] <= 25]          # Menor ou igual
ds[ds['name'] == 'Alice']    # Igual
ds[ds['name'] != 'Bob']      # Diferente

Operações lógicas

ds[(ds['age'] > 25) & (ds['city'] == 'NYC')]    # AND
ds[(ds['age'] > 25) | (ds['city'] == 'NYC')]    # OR
ds[~(ds['status'] == 'inactive')]               # NOT

Métodos

Método	Descrição
`as_(alias)`	Definir nome do alias
`cast(dtype)`	Converter para o tipo
`astype(dtype)`	Alias para cast
`isnull()`	É NULL
`notnull()`	Não é NULL
`isna()`	Alias para isnull
`notna()`	Alias para notnull
`isin(values)`	Em uma lista de valores
`between(low, high)`	Entre dois valores
`fillna(value)`	Preencher valores NULL
`replace(to_replace, value)`	Substituir valores
`clip(lower, upper)`	Limitar valores
`abs()`	Valor absoluto
`round(decimals)`	Arredondar valores
`floor()`	Arredondar para baixo
`ceil()`	Arredondar para cima
`apply(func)`	Aplicar função
`map(mapper)`	Mapear valores

Métodos de agregação

Método	Descrição
`sum()`	Soma
`mean()`	Média
`avg()`	Alias de mean
`min()`	Mínimo
`max()`	Máximo
`count()`	Contagem de valores não nulos
`nunique()`	Contagem de valores únicos
`std()`	Desvio padrão
`var()`	Variância
`median()`	Mediana
`quantile(q)`	Quantil
`first()`	Primeiro valor
`last()`	Último valor
`any()`	Pelo menos um true
`all()`	Todos true

LazyGroupBy

Representa um DataStore agrupado usado em operações de agregação.

# LazyGroupBy é retornado automaticamente
grouped = ds.groupby('category')  # Retorna LazyGroupBy

Métodos

Método	Retorna	Descrição
`agg(spec)`	DataStore	Agrega
`aggregate(spec)`	DataStore	alias de agg
`sum()`	DataStore	Soma por grupo
`mean()`	DataStore	Média por grupo
`count()`	DataStore	Contagem por grupo
`min()`	DataStore	Mínimo por grupo
`max()`	DataStore	Máximo por grupo
`std()`	DataStore	Desvio padrão por grupo
`var()`	DataStore	Variância por grupo
`median()`	DataStore	Mediana por grupo
`nunique()`	DataStore	Contagem de valores únicos por grupo
`first()`	DataStore	Primeiro valor por grupo
`last()`	DataStore	Último valor por grupo
`nth(n)`	DataStore	Enésimo valor por grupo
`head(n)`	DataStore	Primeiros n por grupo
`tail(n)`	DataStore	Últimos n por grupo
`apply(func)`	DataStore	Aplica a função por grupo
`transform(func)`	DataStore	Transforma por grupo
`filter(func)`	DataStore	Filtra grupos

Seleção de colunas

# Selecionar coluna após groupby
grouped['amount'].sum()     # Retorna DataStore
grouped[['a', 'b']].sum()   # Retorna DataStore

Especificações de agregação

# Agregação única
grouped.agg({'amount': 'sum'})

# Múltiplas agregações por coluna
grouped.agg({'amount': ['sum', 'mean', 'count']})

# Agregações nomeadas
grouped.agg(
    total=('amount', 'sum'),
    average=('amount', 'mean'),
    count=('id', 'count')
)

LazySeries

Representa uma Series com avaliação preguiçosa (coluna única).

Propriedades

Propriedade	Tipo	Descrição
`name`	str	Nome da Series
`dtype`	dtype	Tipo de dado

Métodos

Herda a maioria dos métodos de ColumnExpr. Principais métodos:

Método	Descrição
`value_counts()`	Frequência de valores
`unique()`	Valores únicos
`nunique()`	Contagem de valores únicos
`mode()`	Moda
`to_list()`	Converte para lista
`to_numpy()`	Converte para array
`to_frame()`	Converte para DataStore

F (Funções)

Espaço de nomes das funções do ClickHouse.

from chdb.datastore import F, Field

# Agregações
F.sum(Field('amount'))
F.avg(Field('price'))
F.count(Field('id'))
F.quantile(Field('value'), 0.95)

# Condicional
F.sum_if(Field('amount'), Field('status') == 'completed')
F.count_if(Field('active'))

# Janela
F.row_number().over(order_by='date')
F.lag('price', 1).over(partition_by='product', order_by='date')

Consulte Agregação para obter detalhes.

Campo

Referência a uma coluna pelo nome.

from chdb.datastore import Field

# Criar referência de campo
amount = Field('amount')
price = Field('price')

# Usar em expressões
F.sum(Field('amount'))
F.avg(Field('price'))

CaseWhen

Classe para criar expressões CASE WHEN.

# Criar expressão case-when
result = (ds
    .when(ds['score'] >= 90, 'A')
    .when(ds['score'] >= 80, 'B')
    .when(ds['score'] >= 70, 'C')
    .otherwise('F')
)

# Atribuir à coluna
ds['grade'] = result

Janela

Especificação da janela para funções de janela.

from chdb.datastore import F

# Criar janela
window = F.window(
    partition_by='category',
    order_by='date',
    rows_between=(-7, 0)
)

# Usar com agregação
ds['rolling_avg'] = F.avg('price').over(window)

​DataStore

​Construtor

​Propriedades

​Métodos de fábrica

​Métodos de consulta

​Métodos compatíveis com o pandas

​Métodos de E/S

​Métodos de depuração

​Métodos Mágicos

​ColumnExpr

​Propriedades

​Acessores

​Operações aritméticas

​Operações de comparação

​Operações lógicas

​Métodos

​Métodos de agregação

​LazyGroupBy

​Métodos

​Seleção de colunas

​Especificações de agregação

​LazySeries

​Propriedades

​Métodos

​Classes relacionadas

​F (Funções)

​Campo

​CaseWhen

​Janela

DataStore

Construtor

Propriedades

Métodos de fábrica

Métodos de consulta

Métodos compatíveis com o pandas

Métodos de E/S

Métodos de depuração

Métodos Mágicos

ColumnExpr

Propriedades

Acessores

Operações aritméticas

Operações de comparação

Operações lógicas

Métodos

Métodos de agregação

LazyGroupBy

Métodos

Seleção de colunas

Especificações de agregação

LazySeries

Propriedades

Métodos

Classes relacionadas

F (Funções)

Campo

CaseWhen

Janela