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	Cópia dos dados

Exemplos:

# From dictionary
ds = DataStore({'a': [1, 2, 3], 'b': ['x', 'y', 'z']})

# From pandas DataFrame
import pandas as pd
ds = DataStore(pd.DataFrame({'a': [1, 2, 3]}))

# Empty DataStore
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	Indica 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)`	Método de fábrica universal a partir de URI
`from_file(path, ...)`	Cria a partir de arquivo
`from_df(df)`	Cria a partir de DataFrame do pandas
`from_s3(url, ...)`	Cria a partir de S3
`from_gcs(url, ...)`	Cria a partir de Google Cloud Storage
`from_azure(url, ...)`	Cria a partir de Blob do Azure
`from_mysql(...)`	Cria a partir de MySQL
`from_postgresql(...)`	Cria a partir de PostgreSQL
`from_clickhouse(...)`	Cria a partir de ClickHouse
`from_mongodb(...)`	Cria a partir de MongoDB
`from_sqlite(...)`	Cria a partir de SQLite
`from_iceberg(path)`	Cria a partir de tabela Iceberg
`from_delta(path)`	Cria a partir de Delta Lake
`from_numbers(n)`	Cria com números sequenciais
`from_random(rows, cols)`	Cria com dados aleatórios
`run_sql(query)`	Cria a partir de 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 para filter
`sort(*cols, ascending=True)`	DataStore	Ordena linhas
`orderby(*cols)`	DataStore	Alias para 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 pandas

Consulte Compatibilidade com pandas para obter 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() Remodelagem: 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)`	Exibe o Plano de Execução
`clear_cache()`	Limpa os 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 lazy. É retornado ao acessar uma coluna.

# ColumnExpr is returned automatically
col = ds['name']  # Returns ColumnExpr

Propriedades

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

Acessores

Acessor	Descrição	Métodos
`.str`	Operações com strings	56 métodos
`.dt`	Operações de DateTime	42+ métodos
`.arr`	Operações com Array	37 métodos
`.json`	Análise de JSON	13 métodos
`.url`	Análise de URL	15 métodos
`.ip`	Operações com endereços IP	9 métodos
`.geo`	Operações de Geo/distância	14 métodos

Consulte Acessores para 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]           # Greater than
ds[ds['age'] >= 25]          # Greater or equal
ds[ds['age'] < 25]           # Less than
ds[ds['age'] <= 25]          # Less or equal
ds[ds['name'] == 'Alice']    # Equal
ds[ds['name'] != 'Bob']      # Not equal

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 o nome do alias
`cast(dtype)`	Converter para um tipo
`astype(dtype)`	Alias para cast
`isnull()`	É NULL
`notnull()`	Não é NULL
`isna()`	Alias para isnull
`notna()`	Alias para notnull
`isin(values)`	Estar 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 para mean
`min()`	Valor 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 para operações de agregação.

# LazyGroupBy is returned automatically
grouped = ds.groupby('category')  # Returns LazyGroupBy

Métodos

Método	Retorna	Descrição
`agg(spec)`	DataStore	Agregação
`aggregate(spec)`	DataStore	Alias para 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 distinta 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 função por grupo
`transform(func)`	DataStore	Transforma por grupo
`filter(func)`	DataStore	Filtra grupos

Seleção de colunas

# Select column after groupby
grouped['amount'].sum()     # Returns DataStore
grouped[['a', 'b']].sum()   # Returns DataStore

Especificações de agregação

# Single aggregation
grouped.agg({'amount': 'sum'})

# Multiple aggregations per column
grouped.agg({'amount': ['sum', 'mean', 'count']})

# Named aggregations
grouped.agg(
    total=('amount', 'sum'),
    average=('amount', 'mean'),
    count=('id', 'count')
)

LazySeries

Representa uma Series lazy (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 dos valores
`unique()`	Valores únicos
`nunique()`	Número de valores únicos
`mode()`	Valor mais frequente
`to_list()`	Converte em lista
`to_numpy()`	Converte em array
`to_frame()`	Converte em DataStore

F (Funções)

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

from chdb.datastore import F, Field

# Aggregations
F.sum(Field('amount'))
F.avg(Field('price'))
F.count(Field('id'))
F.quantile(Field('value'), 0.95)

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

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

Consulte Agregação para mais detalhes.

Campo

Referência a uma coluna pelo nome.

from chdb.datastore import Field

# Create field reference
amount = Field('amount')
price = Field('price')

# Use in expressions
F.sum(Field('amount'))
F.avg(Field('price'))

CaseWhen

Construtor de expressões CASE WHEN.

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

# Assign to column
ds['grade'] = result

Window

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

from chdb.datastore import F

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

# Use with aggregation
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 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

​Window

DataStore

Construtor

Propriedades

Métodos de fábrica

Métodos de consulta

Métodos compatíveis com 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

Window