Referência da API Python do chDB

Executa uma consulta SQL usando o mecanismo do chDB.

Esta é a principal função de consulta, que executa instruções SQL usando o mecanismo do ClickHouse embutido. Oferece suporte a vários formatos de saída e pode trabalhar com bancos de dados temporários ou baseados em arquivos.

Sintaxe

chdb.query(sql, output_format='CSV', path='', udf_path='')

Parâmetros

Retornar

Retorna o resultado da consulta no formato especificado:

Gerar

Exemplos

>>> # Basic CSV query
>>> result = chdb.query("SELECT 1, 'hello'")
>>> print(result)
"1,hello"

>>> # Query with DataFrame output
>>> df = chdb.query("SELECT 1 as id, 'hello' as msg", "DataFrame")
>>> print(df)
   id    msg
0   1  hello

>>> # Query with file-based database
>>> result = chdb.query("CREATE TABLE test (id INT) ENGINE = Memory", path="mydb.chdb")

Executa consulta SQL usando o mecanismo do chDB.

Esta é a principal função de consulta, que executa instruções SQL usando o mecanismo do ClickHouse embutido. Oferece suporte a vários formatos de saída e pode funcionar com bancos de dados temporários ou baseados em arquivo.

Sintaxe

chdb.sql(sql, output_format='CSV', path='', udf_path='')

Parâmetros

Retornar

Retorna o resultado da consulta no formato especificado:

Gerar

Exemplos

>>> # Basic CSV query
>>> result = chdb.query("SELECT 1, 'hello'")
>>> print(result)
"1,hello"

>>> # Query with DataFrame output
>>> df = chdb.query("SELECT 1 as id, 'hello' as msg", "DataFrame")
>>> print(df)
   id    msg
0   1  hello

>>> # Query with file-based database
>>> result = chdb.query("CREATE TABLE test (id INT) ENGINE = Memory", path="mydb.chdb")

Converte o resultado da consulta em uma tabela do PyArrow.

Converte o resultado de uma consulta do chDB em uma tabela do PyArrow para processamento eficiente de dados em formato colunar. Retorna uma tabela vazia se o resultado estiver vazio.

Sintaxe

chdb.to_arrowTable(res)

Parâmetros

Retorna

Exceções

Exemplo

>>> result = chdb.query("SELECT 1 as id, 'hello' as msg", "Arrow")
>>> table = chdb.to_arrowTable(result)
>>> print(table.to_pandas())
   id    msg
0   1  hello

Converte o resultado da consulta em um DataFrame do pandas.

Converte o resultado de uma consulta do chDB em um DataFrame do pandas, primeiro convertendo-o em uma tabela do PyArrow e depois em pandas usando multithreading para melhor desempenho.

Sintaxe

chdb.to_df(r)

Parâmetros

Retorna

Lança

Exemplo

>>> result = chdb.query("SELECT 1 as id, 'hello' as msg", "Arrow")
>>> df = chdb.to_df(result)
>>> print(df)
   id    msg
0   1  hello

As seguintes funções de sessão estão disponíveis:

Cria uma conexão com o servidor em segundo plano do chDB.

Esta função estabelece uma Connection com o engine de banco de dados chDB (ClickHouse). Cada chamada retorna uma conexão independente, e qualquer número de conexões com o mesmo caminho de banco de dados pode estar aberto ao mesmo tempo.

chdb.connect(connection_string: str = ':memory:') → Connection

Parâmetros:

Formatos básicos

Com parâmetros de consulta

Tratamento de parâmetros de consulta

Os parâmetros de consulta são passados para o mecanismo do ClickHouse como argumentos de inicialização. Tratamento especial de parâmetros:

Para ver a lista completa de parâmetros, consulte clickhouse local --help --verbose

Retorna

Gerar

Exemplos

>>> # Temporary database
>>> conn = connect()
>>> conn = connect(":memory:")
>>>
>>> # File-based database
>>> conn = connect("my_data.db")
>>> conn = connect("/path/to/data.db")
>>>
>>> # With parameters
>>> conn = connect("data.db?mode=ro")  # Read-only mode
>>> conn = connect(":memory:?verbose&log-level=debug")  # Debug logging
>>>
>>> # Using context manager for automatic cleanup
>>> with connect("data.db") as conn:
...     result = conn.query("SELECT 1")
...     print(result)
>>> # Connection automatically closed

Veja também

• Connection - Classe de conexão com o banco de dados
• Cursor - Cursor do banco de dados para operações da DB-API 2.0

Bases: Exception

Classe base de exceção para erros relacionados ao chDB.

Essa exceção é levantada quando a execução de uma consulta do chDB falha ou encontra um erro. Ela herda da classe Exception padrão do Python e fornece informações de erro do mecanismo do ClickHouse subjacente.

Bases: object

A sessão preserva o estado da consulta. Se path for None, a sessão usará o banco de dados temporário (:memory:) compartilhado por todo o processo; assim, todas as sessões sem path terão acesso às tabelas umas das outras. Seu diretório temporário será removido somente quando a última sessão ou conexão desse tipo for fechada. Você também pode informar um path para criar um banco de dados nesse caminho, onde seus dados serão armazenados.

Você também pode usar uma string de conexão para informar o path e outros parâmetros.

class chdb.session.Session(path=None)

Exemplos

Faz a limpeza dos recursos da sessão com tratamento de exceções.

Este método tenta fechar a sessão enquanto suprime quaisquer exceções que possam ocorrer durante o processo de limpeza. É particularmente útil em cenários de tratamento de erros ou quando você precisa garantir que a limpeza ocorra independentemente do estado da sessão.

Sintaxe

cleanup()

Exemplos

>>> session = Session("test.db")
>>> try:
...     session.query("INVALID SQL")
... finally:
...     session.cleanup()  # Limpeza segura independentemente dos erros

Veja também

• close() - Para fechar explicitamente a sessão, com propagação de erro

Fecha a sessão e libera os recursos.

Este método fecha a conexão subjacente e redefine o estado global da sessão. Após chamar este método, a sessão se torna inválida e não pode mais ser usada para novas consultas.

Sintaxe

close()

Exemplos

>>> session = Session("test.db")
>>> session.query("SELECT 1")
>>> session.close()  # Fecha explicitamente a sessão

Executa uma consulta SQL e retorna os resultados.

Este método executa uma consulta SQL no banco de dados da sessão e retorna os resultados no formato especificado. O método oferece suporte a vários formatos de saída e preserva o estado da sessão entre consultas.

Sintaxe

query(sql, fmt='CSV', udf_path='')

Parâmetros

Retorna

Retorna os resultados da consulta no formato especificado. O tipo de retorno exato depende do parâmetro de formato:

• Formatos de texto (CSV, JSON etc.) retornam str
• Formatos binários (Arrow, Parquet) retornam bytes

Gera

Exemplos

>>> session = Session("test.db")
>>>
>>> # Basic query with default CSV format
>>> result = session.query("SELECT 1 as number")
>>> print(result)
number
1

>>> # Query with JSON format
>>> result = session.query("SELECT 1 as number", fmt="JSON")
>>> print(result)
{"number": "1"}

>>> # Complex query with table creation
>>> session.query("CREATE TABLE test (id INT, name String) ENGINE = Memory")
>>> session.query("INSERT INTO test VALUES (1, 'Alice'), (2, 'Bob')")
>>> result = session.query("SELECT * FROM test ORDER BY id")
>>> print(result)
id,name
1,Alice
2,Bob

Veja também

• send_query() - Para executar consultas em streaming
• sql - Alias deste método

Executa uma consulta SQL e retorna um iterador de resultados em streaming.

Este método executa uma consulta SQL no banco de dados da sessão e retorna um objeto de resultado em streaming que permite percorrer os resultados sem carregar tudo na memória de uma só vez. Isso é particularmente útil para grandes conjuntos de resultados.

Sintaxe

send_query(sql, fmt='CSV') → StreamingResult

Parâmetros

Retorna

Gera

Exemplos

>>> session = Session("test.db")
>>> session.query("CREATE TABLE big_table (id INT, data String) ENGINE = MergeTree() order by id")
>>>
>>> # Inserir grande conjunto de dados
>>> for i in range(1000):
...     session.query(f"INSERT INTO big_table VALUES ({i}, 'data_{i}')")
>>>
>>> # Transmitir resultados para evitar problemas de memória
>>> streaming_result = session.send_query("SELECT * FROM big_table ORDER BY id")
>>> for chunk in streaming_result:
...     print(f"Processing chunk: {len(chunk)} bytes")
...     # Processar fragmento sem carregar o conjunto de resultados inteiro

>>> # Using with context manager
>>> with session.send_query("SELECT COUNT(*) FROM big_table") as stream:
...     for result in stream:
...         print(f"Count result: {result}")

Veja também

• query() - Para executar consultas sem streaming
• chdb.state.sqlitelike.StreamingResult - Iterador de resultados em streaming

Executa uma consulta SQL e retorna os resultados.

Este método executa uma consulta SQL no banco de dados da sessão e retorna os resultados no formato especificado. O método oferece suporte a vários formatos de saída e mantém o estado da sessão entre consultas.

Sintaxe

sql(sql, fmt='CSV', udf_path='')

Parâmetros

Retorno

Retorna os resultados da consulta no formato especificado. O tipo de retorno exato depende do parâmetro fmt:

• Formatos de texto (CSV, JSON etc.) retornam str
• Formatos binários (Arrow, Parquet) retornam bytes

Exceções:

Exemplos

>>> session = Session("test.db")
>>>
>>> # Basic query with default CSV format
>>> result = session.query("SELECT 1 as number")
>>> print(result)
number
1

>>> # Query with JSON format
>>> result = session.query("SELECT 1 as number", fmt="JSON")
>>> print(result)
{"number": "1"}

>>> # Complex query with table creation
>>> session.query("CREATE TABLE test (id INT, name String) ENGINE = MergeTree() order by id")
>>> session.query("INSERT INTO test VALUES (1, 'Alice'), (2, 'Bob')")
>>> result = session.query("SELECT * FROM test ORDER BY id")
>>> print(result)
id,name
1,Alice
2,Bob

Veja também

• send_query() - Para executar consultas em streaming
• sql - Apelido deste método

Cria uma Connection para o servidor em segundo plano do chDB.

Esta função estabelece uma conexão com o database engine do chDB (ClickHouse). Cada chamada retorna uma conexão independente, e qualquer número de conexões com o mesmo caminho de banco de dados pode estar aberto ao mesmo tempo.

Sintaxe

chdb.state.connect(connection_string: str = ':memory:') → Connection

Parâmetros

Formatos básicos

Formatos de string de conexão compatíveis:

Com parâmetros de consulta

Tratamento de parâmetros de consulta

Os parâmetros de consulta são passados para o mecanismo do ClickHouse como argumentos de inicialização. Tratamento especial de parâmetros:

Para ver a lista completa de parâmetros, consulte clickhouse local --help --verbose

Retorna

Gera

Exemplos

>>> # Temporary database
>>> conn = connect()
>>> conn = connect(":memory:")
>>>
>>> # File-based database
>>> conn = connect("my_data.db")
>>> conn = connect("/path/to/data.db")
>>>
>>> # With parameters
>>> conn = connect("data.db?mode=ro")  # Read-only mode
>>> conn = connect(":memory:?verbose&log-level=debug")  # Debug logging
>>>
>>> # Using context manager for automatic cleanup
>>> with connect("data.db") as conn:
...     result = conn.query("SELECT 1")
...     print(result)
>>> # Connection automatically closed

Veja também

• Connection - Classe de conexão com banco de dados
• Cursor - Cursor de banco de dados para operações da DB-API 2.0

Classes base: object

Sintaxe

class chdb.state.sqlitelike.Connection(connection_string: str)

Fecha a conexão e libera os recursos.

Este método fecha a conexão com o banco de dados e libera todos os recursos associados, incluindo cursores ativos. Após chamar este método, a conexão se torna inválida e não pode mais ser usada em outras operações.

Sintaxe

close() → None

Exemplos

>>> conn = connect("test.db")
>>> # Usar a conexão para consultas
>>> conn.query("CREATE TABLE test (id INT) ENGINE = Memory")
>>> # Fechar quando terminar
>>> conn.close()

>>> # Usando com gerenciador de contexto (limpeza automática)
>>> with connect("test.db") as conn:
...     conn.query("SELECT 1")
...     # Conexão fechada automaticamente

Crie um objeto Cursor para executar consultas.

Este método cria um cursor de banco de dados que fornece a interface padrão DB-API 2.0 para executar consultas e obter resultados. O cursor permite um controle mais detalhado sobre a execução de consultas e a obtenção de resultados.

Sintaxe

cursor() → Cursor

Retorna

Exemplos

>>> conn = connect(":memory:")
>>> cursor = conn.cursor()
>>> cursor.execute("CREATE TABLE test (id INT, name String) ENGINE = Memory")
>>> cursor.execute("INSERT INTO test VALUES (1, 'Alice')")
>>> cursor.execute("SELECT * FROM test")
>>> rows = cursor.fetchall()
>>> print(rows)
((1, 'Alice'),)

Veja também

• Cursor - Implementação do cursor do banco de dados

Execute uma consulta SQL e retorne todos os resultados.

Este método executa uma consulta SQL de forma síncrona e retorna o conjunto completo de resultados. Ele oferece suporte a vários formatos de saída e aplica automaticamente o pós-processamento específico de cada formato.

Sintaxe

query(query: str, format: str = 'CSV') → Any

Parâmetros:

Retorna

Gera

Exemplos

>>> conn = connect(":memory:")
>>>
>>> # Consulta CSV básica
>>> result = conn.query("SELECT 1 as num, 'hello' as text")
>>> print(result)
num,text
1,hello

>>> # Formato DataFrame
>>> df = conn.query("SELECT number FROM numbers(5)", "dataframe")
>>> print(df)
   number
0       0
1       1
2       2
3       3
4       4

Veja também

• send_query() - Para executar consultas em streaming

Executa uma consulta SQL e retorna um iterador de resultados em streaming.

Este método executa uma consulta SQL e retorna um objeto StreamingResult que permite iterar pelos resultados sem carregar tudo na memória de uma só vez. Isso é ideal para processar grandes conjuntos de resultados.

Sintaxe

send_query(query: str, format: str = 'CSV') → StreamingResult

Parâmetros

Retorna

Gera

Exemplos

>>> conn = connect(":memory:")
>>>
>>> # Streaming básico
>>> stream = conn.send_query("SELECT number FROM numbers(1000)")
>>> for chunk in stream:
...     print(f"Processando fragmento: {len(chunk)} bytes")

>>> # Usando gerenciador de contexto para limpeza
>>> with conn.send_query("SELECT * FROM large_table") as stream:
...     chunk = stream.fetch()
...     while chunk:
...         process_data(chunk)
...         chunk = stream.fetch()

>>> # Formato Arrow com streaming de RecordBatch
>>> stream = conn.send_query("SELECT * FROM data", "Arrow")
>>> reader = stream.record_batch(rows_per_batch=10000)
>>> for batch in reader:
...     print(f"Batch shape: {batch.num_rows} x {batch.num_columns}")

Veja também

• query() - Para executar consultas sem streaming
• StreamingResult - Iterador de resultados em streaming

Bases: object

Iterador de resultados em streaming para processar resultados de consultas grandes.

Esta classe fornece uma interface de iterador para transmitir resultados de consultas sem carregar todo o conjunto de resultados na memória. Ela oferece suporte a vários formatos de saída e fornece métodos para buscar resultados manualmente e para streaming de PyArrow RecordBatch.

class chdb.state.sqlitelike.StreamingResult

Obtém o próximo fragmento dos resultados em streaming.

Este método recupera o próximo fragmento de dados disponível no resultado da consulta em streaming. O formato dos dados retornados depende do formato especificado quando a consulta em streaming foi iniciada.

Sintaxe

fetch() → Any

Retorna

Exemplos

>>> stream = conn.send_query("SELECT * FROM large_table")
>>> chunk = stream.fetch()
>>> while chunk is not None:
...     process_data(chunk)
...     chunk = stream.fetch()

Cancela a consulta em streaming e libera os recursos.

Este método cancela qualquer consulta em streaming em andamento e libera os recursos associados. Ele deve ser chamado quando você quiser interromper o processamento dos resultados antes que o stream termine.

Sintaxe

cancel() → None

Exemplos

>>> stream = conn.send_query("SELECT * FROM very_large_table")
>>> for i, chunk in enumerate(stream):
...     if i >= 10:  # Processa apenas os primeiros 10 fragmentos
...         stream.cancel()
...         break
...     process_data(chunk)

Fecha o resultado em streaming e libera os recursos.

Alias para cancel(). Fecha o iterador do resultado em streaming e libera quaisquer recursos associados.

Sintaxe

close() → None

Crie um PyArrow RecordBatchReader para processar lotes com eficiência.

Este método cria um PyArrow RecordBatchReader que permite iterar com eficiência pelos resultados da consulta no formato Arrow. Esta é a maneira mais eficiente de processar grandes conjuntos de resultados ao usar o PyArrow.

Sintaxe

record_batch(rows_per_batch: int = 1000000) → pa.RecordBatchReader

Parâmetros

Retorno

Exemplos

>>> stream = conn.send_query("SELECT * FROM data", format="Arrow")
>>> reader = stream.record_batch(rows_per_batch=10000)
>>> for batch in reader:
...     print(f"Processing batch: {batch.num_rows} rows")
...     df = batch.to_pandas()
...     process_dataframe(df)

StreamingResult oferece suporte ao protocolo de iteração do Python, permitindo seu uso direto em loops for:

>>> stream = conn.send_query("SELECT number FROM numbers(1000000)")
>>> for chunk in stream:
...     print(f"Chunk size: {len(chunk)} bytes")

StreamingResult é compatível com o protocolo de gerenciador de contexto para limpeza automática de recursos:

>>> with conn.send_query("SELECT * FROM data") as stream:
...     for chunk in stream:
...         process(chunk)
>>> # Stream fechado automaticamente

Bases: object

class chdb.state.sqlitelike.Cursor(connection)

Fecha o cursor e libera os recursos.

Este método fecha o cursor e libera todos os recursos associados. Após chamar este método, o cursor se torna inválido e não pode mais ser usado em operações posteriores.

Sintaxe

close() → None

Exemplos

>>> cursor = conn.cursor()
>>> cursor.execute("SELECT 1")
>>> result = cursor.fetchone()
>>> cursor.close()  # Libera os recursos do cursor

Retorna uma lista com os nomes das colunas da última consulta executada.

Este método retorna os nomes das colunas da consulta SELECT executada mais recentemente. Os nomes são retornados na mesma ordem em que aparecem no conjunto de resultados.

Sintaxe

column_names() → list

Retorna

Exemplos

>>> cursor = conn.cursor()
>>> cursor.execute("SELECT id, name, email FROM users LIMIT 1")
>>> print(cursor.column_names())
['id', 'name', 'email']

Veja também

• column_types() - Obter informações sobre tipos de coluna
• description - descrição de coluna da DB-API 2.0

Retorna uma lista dos tipos das colunas da última consulta executada.

Este método retorna os nomes dos tipos de coluna do ClickHouse da consulta SELECT executada mais recentemente. Os tipos são retornados na mesma ordem em que aparecem no conjunto de resultados.

Sintaxe

column_types() → list

Retorna

Exemplos

>>> cursor = conn.cursor()
>>> cursor.execute("SELECT toInt32(1), toString('hello')")
>>> print(cursor.column_types())
['Int32', 'String']

Veja também

• column_names() - Obtém informações sobre os nomes das colunas
• description - descrição da coluna da DB-API 2.0

Executa o commit de qualquer transação pendente.

Este método executa o commit de qualquer transação pendente do banco de dados. No ClickHouse, a maioria das operações é confirmada automaticamente, mas este método é fornecido para compatibilidade com a DB-API 2.0.

Sintaxe

commit() → None

Exemplos

>>> cursor = conn.cursor()
>>> cursor.execute("INSERT INTO test VALUES (1, 'data')")
>>> cursor.commit()

Retorna a descrição das colunas de acordo com a especificação DB-API 2.0.

Esta propriedade retorna uma lista de tuplas de 7 itens que descrevem cada coluna no conjunto de resultados da última consulta SELECT executada. Cada tupla contém: (name, type_code, display_size, internal_size, precision, scale, null_ok)

Atualmente, apenas name e type_code são fornecidos; os outros campos são definidos como None.

Retorna

Exemplos

>>> cursor = conn.cursor()
>>> cursor.execute("SELECT id, name FROM users LIMIT 1")
>>> for desc in cursor.description:
...     print(f"Column: {desc[0]}, Type: {desc[1]}")
Column: id, Type: Int32
Column: name, Type: String

Veja também

• column_names() - Obtenha apenas os nomes das colunas
• column_types() - Obtenha apenas os tipos das colunas

Executa uma consulta SQL e prepara os resultados para recuperação.

Este método executa uma consulta SQL e prepara os resultados para serem recuperados usando os métodos fetch. Ele lida com a interpretação dos dados de resultado e com a conversão automática de tipos de dados do ClickHouse.

Sintaxe

execute(query: str) → None

Parâmetros:

Exceções

Exemplos

>>> cursor = conn.cursor()
>>>
>>> # Executar DDL
>>> cursor.execute("CREATE TABLE test (id INT, name String) ENGINE = Memory")
>>>
>>> # Executar DML
>>> cursor.execute("INSERT INTO test VALUES (1, 'Alice')")
>>>
>>> # Executar SELECT e buscar resultados
>>> cursor.execute("SELECT * FROM test")
>>> rows = cursor.fetchall()
>>> print(rows)
((1, 'Alice'),)

Veja também

• fetchone() - Retorna uma única linha
• fetchmany() - Retorna várias linhas
• fetchall() - Retorna todas as linhas restantes

Busca todas as linhas restantes do resultado da consulta.

Este método recupera todas as linhas restantes do conjunto de resultados da consulta atual a partir da posição atual do cursor. Ele retorna uma tupla de tuplas de linhas, com a conversão adequada para tipos Python aplicada.

Sintaxe

fetchall() → tuple

Retorna:

Exemplos

>>> cursor = conn.cursor()
>>> cursor.execute("SELECT id, name FROM users")
>>> all_users = cursor.fetchall()
>>> for user_id, user_name in all_users:
...     print(f"User {user_id}: {user_name}")

Veja também

• fetchone() - Obtém uma única linha
• fetchmany() - Obtém várias linhas em lotes

Recupera várias linhas do resultado da consulta.

Este método recupera até ‘size’ linhas do conjunto de resultados da consulta atual. Ele retorna uma tupla de tuplas de linhas, em que cada linha contém valores de colunas com a conversão apropriada para tipos Python.

Sintaxe

fetchmany(size: int = 1) → tuple

Parâmetros

Retorno

Exemplos

>>> cursor = conn.cursor()
>>> cursor.execute("SELECT * FROM large_table")
>>>
>>> # Processe os resultados em lotes
>>> while True:
...     batch = cursor.fetchmany(100)  # Busca 100 linhas de cada vez
...     if not batch:
...         break
...     process_batch(batch)

Veja também

• fetchone() - Retorna uma única linha
• fetchall() - Retorna todas as linhas restantes

Busca a próxima linha do resultado da consulta.

Este método recupera a próxima linha disponível do conjunto de resultados da consulta atual. Ele retorna uma tupla contendo os valores das colunas, com a conversão adequada para tipos Python aplicada.

Sintaxe

fetchone() → tuple | None

Retorna:

Exemplos

>>> cursor = conn.cursor()
>>> cursor.execute("SELECT id, name FROM users")
>>> row = cursor.fetchone()
>>> while row is not None:
...     user_id, user_name = row
...     print(f"User {user_id}: {user_name}")
...     row = cursor.fetchone()

Veja também

• fetchmany() - Busca várias linhas
• fetchall() - Busca todas as linhas restantes

Converte o resultado da consulta em uma tabela PyArrow.

Esta função converte os resultados de consultas do chdb para o formato de tabela PyArrow, que oferece acesso eficiente a dados colunares e interoperabilidade com outras bibliotecas de processamento de dados.

Sintaxe

chdb.state.sqlitelike.to_arrowTable(res)

Parâmetros:

Retorna

Gera

Exemplos

>>> import chdb
>>> result = chdb.query("SELECT 1 as num, 'hello' as text", "Arrow")
>>> table = to_arrowTable(result)
>>> print(table.schema)
num: int64
text: string
>>> print(table.to_pandas())
   num   text
0    1  hello

Converte o resultado da consulta em um DataFrame do Pandas.

Esta função converte os resultados de consultas do chdb para um DataFrame do Pandas, primeiro convertendo-os em uma tabela PyArrow e depois em um DataFrame. Isso oferece recursos práticos de análise de dados com a API do Pandas.

Sintaxe

chdb.state.sqlitelike.to_df(r)

Parâmetros:

Retorna:

Gera

Veja também

• to_arrowTable() - Para conversão para o formato tabela PyArrow

Exemplos

>>> import chdb
>>> result = chdb.query("SELECT 1 as num, 'hello' as text", "Arrow")
>>> df = to_df(result)
>>> print(df)
   num   text
0    1  hello
>>> print(df.dtypes)
num      int64
text    object
dtype: object

Bases:

class chdb.dataframe.Table(*args: Any, **kwargs: Any)

O chDB fornece uma interface compatível com a Python DB-API 2.0 para conectividade com bancos de dados, permitindo usar o chDB com ferramentas e frameworks que esperam interfaces de banco de dados padrão.

A interface DB-API 2.0 do chDB inclui:

• Conexões: Gerenciamento de conexões com bancos de dados por meio de strings de conexão
• Cursores: Execução de consultas e recuperação de resultados
• Sistema de Tipos: Constantes de tipo e conversores compatíveis com a DB-API 2.0
• Tratamento de Erros: Hierarquia padrão de exceções de banco de dados
• Segurança de Threads: Segurança de threads de nível 1 (threads podem compartilhar módulos, mas não conexões)

A interface da API de banco de dados (DBAPI) 2.0 implementa as seguintes funções principais:

Inicializa uma nova conexão com o banco de dados.

Sintaxe

chdb.dbapi.connect(*args, **kwargs)

Parâmetros

Gerar

Obtém informações da versão do cliente.

Retorna a versão do cliente chDB como uma string para compatibilidade com o MySQLdb.

Sintaxe

chdb.dbapi.get_client_info()

Retorna

Retorna x como um tipo binário.

Esta função converte a entrada para o tipo bytes, para uso com campos binários de banco de dados, seguindo a especificação DB-API 2.0.

Sintaxe

chdb.dbapi.Binary(x)

Parâmetros

Retorno

Bases: object

Conexão compatível com DB-API 2.0 para o chDB.

Esta classe fornece uma interface DB-API padrão para se conectar a bancos de dados chDB e interagir com eles. Ela oferece suporte tanto a bancos de dados temporários quanto a bancos de dados em arquivo.

A conexão gerencia o mecanismo chDB subjacente e fornece métodos para executar consultas, gerenciar transações (operação sem efeito para ClickHouse) e criar cursores.

class chdb.dbapi.connections.Connection(path=None)

Parâmetros

Variáveis

Exemplos

>>> # Temporary database
>>> conn = Connection()
>>> cursor = conn.cursor()
>>> cursor.execute("SELECT 1")
>>> result = cursor.fetchall()
>>> conn.close()

>>> # File-based database
>>> conn = Connection('mydata.db')
>>> with conn.cursor() as cur:
...     cur.execute("CREATE TABLE users (id INT, name STRING) ENGINE = MergeTree() order by id")
...     cur.execute("INSERT INTO users VALUES (1, 'Alice')")
>>> conn.close()

>>> # Context manager usage
>>> with Connection() as cur:
...     cur.execute("SELECT version()")
...     version = cur.fetchone()

Fecha a conexão com o banco de dados.

Fecha a conexão subjacente com o chDB e marca esta conexão como fechada. Operações subsequentes nesta conexão resultarão em Error.

Sintaxe

close()

Lança

Faz o commit da transação atual.

Sintaxe

commit()

Cria um novo cursor para executar consultas.

Sintaxe

cursor(cursor=None)

Parâmetros

Retorna

Gera

Exemplo

>>> conn = Connection()
>>> cur = conn.cursor()
>>> cur.execute("SELECT 1")
>>> result = cur.fetchone()

Escapa um valor para incluí-lo com segurança em consultas SQL.

Sintaxe

escape(obj, mapping=None)

Parâmetros

Retorno

Exemplo

>>> conn = Connection()
>>> safe_value = conn.escape("O'Reilly")
>>> query = f"SELECT * FROM users WHERE name = {safe_value}"

Escapa um valor de texto para consultas SQL.

Sintaxe

escape_string(s)

Parâmetros

Retorna

Verifica se a conexão está aberta.

Retorna

Execute uma consulta SQL diretamente e retorne os resultados brutos.

Este método contorna a interface de cursor e executa consultas diretamente. Para o uso padrão da DB-API, prefira usar o método cursor().

Sintaxe

query(sql, fmt='CSV')

Parâmetros:

Retorna

Gera

Exemplo

>>> conn = Connection()
>>> result = conn.query("SELECT 1, 'hello'", "CSV")
>>> print(result)
"1,hello\n"

Obtém a resposta da última consulta.

Retorna

Desfaz a transação atual.

Sintaxe

rollback()

Bases: object

Cursor DB-API 2.0 para executar consultas e obter resultados.

O cursor fornece métodos para executar instruções SQL, gerenciar resultados de consultas e navegar por conjuntos de resultados. Ele oferece suporte à vinculação de parâmetros, operações em massa e segue as especificações da DB-API 2.0.

Não crie instâncias de Cursor diretamente. Em vez disso, use Connection.cursor().

class chdb.dbapi.cursors.Cursor(connection)

Exemplos

>>> conn = Connection()
>>> cur = conn.cursor()
>>> cur.execute("SELECT 1 as id, 'test' as name")
>>> result = cur.fetchone()
>>> print(result)  # (1, 'test')
>>> cur.close()

Executa um procedimento armazenado (implementação de placeholder).

Sintaxe

callproc(procname, args=())

Parâmetros

Retorno

Fecha o cursor e libera os recursos associados.

Após ser fechado, o cursor se torna inutilizável, e qualquer operação lançará uma exceção. Fechar um cursor consome todos os dados restantes e libera o cursor subjacente.

Sintaxe

close()

Executa uma consulta SQL com vinculação opcional de parâmetros.

Este método executa uma única instrução SQL com substituição opcional de parâmetros. Ele oferece suporte a vários estilos de marcadores de posição de parâmetros para maior flexibilidade.

Sintaxe

execute(query, args=None)

Parâmetros

Retorno

Estilos de parâmetro

Exemplos

>>> # Parâmetros com ?
>>> cur.execute("SELECT * FROM users WHERE id = ? AND age > ?", (123, 18))
>>>
>>> # Parâmetros nomeados
>>> cur.execute("SELECT * FROM users WHERE name = %(name)s", {'name': 'Alice'})
>>>
>>> # Sem parâmetros
>>> cur.execute("SELECT COUNT(*) FROM users")

Exceções

Executa uma consulta várias vezes com diferentes conjuntos de parâmetros.

Este método executa com eficiência a mesma consulta SQL várias vezes, com valores de parâmetros diferentes. É especialmente útil para operações de INSERT em massa.

Sintaxe

executemany(query, args)

Parâmetros

Retorno

Exemplos

>>> # insert em massa com parâmetros com ponto de interrogação
>>> users_data = [(1, 'Alice'), (2, 'Bob'), (3, 'Charlie')]
>>> cur.executemany("INSERT INTO users VALUES (?, ?)", users_data)
>>>
>>> # insert em massa com parâmetros nomeados
>>> users_data = [
...     {'id': 1, 'name': 'Alice'},
...     {'id': 2, 'name': 'Bob'}
... ]
>>> cur.executemany(
...     "INSERT INTO users VALUES (%(id)s, %(name)s)",
...     users_data
... )

Obtém todas as linhas restantes do resultado da consulta.

Sintaxe

fetchall()

Retorna

Gera

Exemplo

>>> cursor.execute("SELECT id, name FROM users")
>>> all_rows = cursor.fetchall()
>>> print(len(all_rows))  # Número total de linhas

Obtém várias linhas do resultado da consulta.

Sintaxe

fetchmany(size=1)

Parâmetros

Retorno

Exceções

Exemplo

>>> cursor.execute("SELECT id, name FROM users")
>>> rows = cursor.fetchmany(3)
>>> print(rows)  # [(1, 'Alice'), (2, 'Bob'), (3, 'Charlie')]

Obtém a próxima linha do resultado da consulta.

Sintaxe

fetchone()

Retorna

Gera

Exemplo

>>> cursor.execute("SELECT id, name FROM users LIMIT 3")
>>> row = cursor.fetchone()
>>> print(row)  # (1, 'Alice')
>>> row = cursor.fetchone()
>>> print(row)  # (2, 'Bob')

Tamanho máximo da instrução gerada por executemany().

O valor padrão é 1024000.

Retorna a consulta exata que seria enviada ao banco de dados.

Este método mostra a consulta SQL final após a substituição de parâmetros, o que é útil para depuração e geração de logs.

Sintaxe

mogrify(query, args=None)

Parâmetros

Retorno

Exemplo

>>> cur.mogrify("SELECT * FROM users WHERE id = ?", (123,))
"SELECT * FROM users WHERE id = 123"

Avança para o próximo conjunto de resultados (não suportado).

Sintaxe

nextset()

Retorno

Define os tamanhos de entrada dos parâmetros (implementação sem efeito).

Sintaxe

setinputsizes(*args)

Parâmetros

Define os tamanhos das colunas de saída (implementação sem efeito).

Sintaxe

setoutputsizes(*args)

Parâmetros

Classes de exceção para operações de banco de dados no chdb.

Este módulo fornece uma hierarquia completa de classes de exceção para tratar erros relacionados a banco de dados no chdb, seguindo a Especificação da API de Banco de Dados do Python v2.0.

A hierarquia de exceções está estruturada da seguinte forma:

StandardError
├── Warning
└── Error
    ├── InterfaceError
    └── DatabaseError
        ├── DataError
        ├── OperationalError
        ├── IntegrityError
        ├── InternalError
        ├── ProgrammingError
        └── NotSupportedError

Cada classe de exceção representa uma categoria específica de erros de banco de dados:

Veja também

• Especificação da API de Banco de Dados Python v2.0
• chdb.dbapi.connections - Gerenciamento de conexões com o banco de dados
• chdb.dbapi.cursors - Operações de cursor do banco de dados

Exemplos

>>> try:
...     cursor.execute("SELECT * FROM nonexistent_table")
... except ProgrammingError as e:
...     print(f"SQL Error: {e}")
...
SQL Error: Table 'nonexistent_table' doesn't exist

>>> try:
...     cursor.execute("INSERT INTO users (id) VALUES (1), (1)")
... except IntegrityError as e:
...     print(f"Constraint violation: {e}")
...
Constraint violation: Duplicate entry '1' for key 'PRIMARY'

Bases: DatabaseError

Exceção gerada para erros decorrentes de problemas nos dados processados.

Esta exceção é gerada quando operações de banco de dados falham devido a problemas com os dados em processamento, como:

• Operações de divisão por zero
• Valores numéricos fora do intervalo
• Valores de data/hora inválidos
• Erros de truncamento de string
• Falhas na conversão de tipo
• Formato de dados inválido para o tipo da coluna

Gera

Exemplos

>>> # Divisão por zero em SQL
>>> cursor.execute("SELECT 1/0")
DataError: Division by zero

>>> # Formato inválido de data
>>> cursor.execute("INSERT INTO table VALUES ('invalid-date')")
DataError: Invalid date format

Bases: Error

Exceção lançada para erros relacionados ao banco de dados.

Esta é a classe base para todos os erros relacionados ao banco de dados. Ela engloba todos os erros que ocorrem durante operações no banco de dados e que estão relacionados ao próprio banco de dados, e não à interface.

Cenários comuns incluem:

• Erros na execução de SQL
• Problemas de conectividade com o banco de dados
• Problemas relacionados a transações
• Violações de restrições específicas do banco de dados

Bases: StandardError

Exceção que é a classe base de todas as outras exceções de erro (exceto Warning).

Esta é a classe base de todas as exceções de erro no chdb, excluindo avisos. Ela serve como classe pai para todas as condições de erro de banco de dados que impedem a conclusão bem-sucedida das operações.

Ver também

• Warning - Para avisos não fatais que não impedem a conclusão da operação

Bases: DatabaseError

Exceção lançada quando a integridade relacional do banco de dados é comprometida.

Essa exceção é lançada quando operações no banco de dados violam restrições de integridade, incluindo:

• Violações de restrição de chave estrangeira
• Violações de chave primária ou de restrição de unicidade (chaves duplicadas)
• Violações de restrição CHECK
• Violações de restrição NOT NULL
• Violações de integridade referencial

Levanta

Exemplos

>>> # Chave primária duplicada
>>> cursor.execute("INSERT INTO users (id, name) VALUES (1, 'John')")
>>> cursor.execute("INSERT INTO users (id, name) VALUES (1, 'Jane')")
IntegrityError: Entrada duplicada '1' para a chave 'PRIMARY'

>>> # Violação de chave estrangeira
>>> cursor.execute("INSERT INTO orders (user_id) VALUES (999)")
IntegrityError: Cannot add or update a child row: foreign key constraint fails

Bases: Error

Exceção gerada para erros relacionados à interface do banco de dados, e não ao próprio banco de dados.

Essa exceção é gerada quando há problemas na implementação da interface do banco de dados, como:

• Parâmetros de conexão inválidos
• Uso incorreto da API (chamada de métodos em conexões fechadas)
• Erros de protocolo no nível da interface
• Falhas na importação ou na inicialização do módulo

Gera

Base: DatabaseError

Exceção gerada quando o banco de dados encontra um erro interno.

Esta exceção é gerada quando o sistema de banco de dados encontra erros internos que não são causados pela aplicação, como:

• Estado inválido do cursor (o cursor não é mais válido)
• Inconsistências no estado da transação (a transação está fora de sincronia)
• Problemas de corrupção no banco de dados
• Corrupção da estrutura interna de dados
• Erros de banco de dados em nível de sistema

Gera

Bases: DatabaseError

Exceção gerada quando um método ou a API do banco de dados não tem suporte.

Essa exceção é gerada quando a aplicação tenta usar recursos do banco de dados ou métodos da API que não têm suporte na configuração ou versão atual do banco de dados, como:

• Solicitar rollback() em conexões sem suporte a transações
• Usar recursos SQL avançados sem suporte na versão do banco de dados
• Chamar métodos não implementados pelo driver atual
• Tentar usar recursos do banco de dados desabilitados

Gera

Exemplos

>>> # Reversão de transação em conexão sem suporte a transações
>>> connection.rollback()
NotSupportedError: Transações não são suportadas

>>> # Usando sintaxe SQL sem suporte
>>> cursor.execute("SELECT * FROM table WITH (NOLOCK)")
NotSupportedError: WITH clause not supported in this database version

Bases: DatabaseError

Exceção gerada para erros relacionados à operação do banco de dados.

Esta exceção é gerada para erros que ocorrem durante a operação do banco de dados e que não estão necessariamente sob o controle do programador, incluindo:

• Desconexão inesperada do banco de dados
• Servidor do banco de dados não encontrado ou inacessível
• Falhas no processamento de transações
• Erros de alocação de memória durante o processamento
• Esgotamento de espaço em disco ou de recursos
• Erros internos do servidor do banco de dados
• Falhas de autenticação ou autorização

Levanta

Bases: DatabaseError

Exceção gerada para erros de programação em operações de banco de dados.

Essa exceção é gerada quando há erros de programação no uso do banco de dados pelo aplicativo, incluindo:

• Tabela ou coluna não encontrada
• A tabela ou o índice já existe no momento da criação
• Erros de sintaxe SQL em instruções
• Número incorreto de parâmetros especificados em instruções preparadas
• Operações SQL inválidas (por exemplo, DROP em objetos inexistentes)
• Uso incorreto de métodos da API de banco de dados

Gera

Exemplos

>>> # Tabela não encontrada
>>> cursor.execute("SELECT * FROM nonexistent_table")
ProgrammingError: Table 'nonexistent_table' doesn't exist

>>> # Erro de sintaxe SQL
>>> cursor.execute("SELCT * FROM users")
ProgrammingError: You have an error in your SQL syntax

>>> # Número incorreto de parâmetros
>>> cursor.execute("INSERT INTO users (name, age) VALUES (%s)", ('John',))
ProgrammingError: Column count doesn't match value count

Bases: Exception

Exceção relacionada a operações com o chdb.

Esta é a classe base para todas as exceções relacionadas ao chdb. Ela herda da classe Exception interna do Python e serve como raiz da hierarquia de exceções para operações de banco de dados.

Bases: StandardError

Exceção gerada para avisos importantes, como truncamento de dados durante a inserção etc.

Esta exceção é gerada quando a operação no banco de dados é concluída, mas com avisos importantes que devem ser levados ao conhecimento da aplicação. Cenários comuns incluem:

• Truncamento de dados durante a inserção
• Perda de precisão em conversões numéricas
• Avisos de conversão de conjunto de caracteres

str(object=’’) -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str

Cria um novo objeto string a partir do objeto fornecido. Se encoding ou errors for especificado, o objeto deverá expor um buffer de dados que será decodificado usando a codificação fornecida e o manipulador de erros. Caso contrário, retorna o resultado de object._\_str_\_() (se definido) ou repr(object).

• encoding usa ‘utf-8’ por padrão.
• errors usa ‘strict’ por padrão.

int([x]) -> integer
int(x, base=10) -> integer

Converte um número ou uma string em um inteiro, ou retorna 0 se nenhum argumento for fornecido. Se x for um número, retorna x._int_(). Para números de ponto flutuante, isso trunca em direção a zero.

Se x n'ão for um número ou se base for fornecida, x deverá ser uma instância de string, bytes ou bytearray que represente um literal inteiro na base informada. O literal pode ser precedido por ‘+’ ou ‘-’ e estar cercado por espaços em branco. A base padrão é 10. As bases válidas são 0 e 2-36. Base 0 significa interpretar a base a partir da string como um literal inteiro.

>>> int(‘0b100’, base=0)
4

str(object=’’) -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str

Crie um novo objeto string a partir do objeto fornecido. Se encoding ou errors for especificado, o objeto deverá expor um buffer de dados que será decodificado usando a codificação fornecida e o manipulador de erros. Caso contrário, retorna o resultado de object._str_() (se definido) ou repr(object). encoding tem como padrão ‘utf-8’. errors tem como padrão ‘strict’.

frozenset estendido para comparação de tipos da DB-API 2.0.

Esta classe estende frozenset para dar suporte à semântica de comparação de tipos da DB-API 2.0. Ela permite uma verificação de tipos flexível, em que itens individuais podem ser comparados com o conjunto usando operadores de igualdade e desigualdade.

Isso é usado para constantes de tipo como STRING, BINARY, NUMBER etc., permitindo comparações como “field_type == STRING”, em que field_type é um único valor de tipo.

Exemplos

>>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING])
>>> FIELD_TYPE.STRING == string_types  # Retorna True
>>> FIELD_TYPE.INT != string_types     # Retorna True
>>> FIELD_TYPE.BLOB in string_types    # Retorna False

frozenset estendido para comparação de tipos no DB-API 2.0.

Esta classe estende frozenset para dar suporte à semântica de comparação de tipos do DB-API 2.0. Ela permite uma verificação de tipos flexível, em que itens individuais podem ser comparados com o conjunto usando operadores de igualdade e de desigualdade.

Isso é usado para constantes de tipo como STRING, BINARY, NUMBER etc., permitindo comparações como “field_type == STRING”, em que field_type é um único valor de tipo.

Exemplos

>>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING])
>>> FIELD_TYPE.STRING == string_types  # Retorna true
>>> FIELD_TYPE.INT != string_types     # Retorna true
>>> FIELD_TYPE.BLOB in string_types    # Retorna false

frozenset estendido para comparação de tipos na DB-API 2.0.

Esta classe estende frozenset para oferecer suporte à semântica de comparação de tipos da DB-API 2.0. Ela permite uma verificação de tipos flexível, em que itens individuais podem ser comparados com o conjunto usando operadores de igualdade e desigualdade.

Isso é usado para constantes de tipo como STRING, BINARY, NUMBER etc., permitindo comparações como “field_type == STRING”, em que field_type é um único valor de tipo.

Exemplos

>>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING])
>>> FIELD_TYPE.STRING == string_types  # Retorna True
>>> FIELD_TYPE.INT != string_types     # Retorna True
>>> FIELD_TYPE.BLOB in string_types    # Retorna False

frozenset estendido para comparação de tipos na DB-API 2.0.

Esta classe estende frozenset para dar suporte à semântica de comparação de tipos da DB-API 2.0. Ela permite uma verificação de tipos mais flexível, em que itens individuais podem ser comparados com o conjunto usando operadores de igualdade e de desigualdade.

Isso é usado para constantes de tipo como STRING, BINARY, NUMBER etc., permitindo comparações como “field_type == STRING”, em que field_type é um único valor de tipo.

Exemplos

>>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING])
>>> FIELD_TYPE.STRING == string_types  # Retorna True
>>> FIELD_TYPE.INT != string_types     # Retorna True
>>> FIELD_TYPE.BLOB in string_types    # Retorna False

frozenset estendido para comparação de tipos da DB-API 2.0.

Esta classe estende frozenset para oferecer suporte à semântica de comparação de tipos da DB-API 2.0. Ela permite uma verificação de tipos flexível, em que itens individuais podem ser comparados com o conjunto usando operadores de igualdade e de desigualdade.

Isso é usado para constantes de tipo como STRING, BINARY, NUMBER etc., para permitir comparações como “field_type == STRING”, em que field_type é um único valor de tipo.

Exemplos

>>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING])
>>> FIELD_TYPE.STRING == string_types  # Retorna True
>>> FIELD_TYPE.INT != string_types     # Retorna True
>>> FIELD_TYPE.BLOB in string_types    # Retorna False

frozenset estendido para comparação de tipos da DB-API 2.0.

Esta classe estende frozenset para dar suporte à semântica de comparação de tipos da DB-API 2.0. Ela permite uma verificação de tipos flexível, na qual itens individuais podem ser comparados com o conjunto usando operadores de igualdade e desigualdade.

Isso é usado para constantes de tipo como STRING, BINARY, NUMBER etc., permitindo comparações como “field_type == STRING”, em que field_type é um único valor de tipo.

Exemplos

>>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING])
>>> FIELD_TYPE.STRING == string_types  # Retorna True
>>> FIELD_TYPE.INT != string_types     # Retorna True
>>> FIELD_TYPE.BLOB in string_types    # Retorna False

frozenset estendido para comparação de tipos na DB-API 2.0.

Esta classe estende frozenset para dar suporte à semântica de comparação de tipos da DB-API 2.0. Ela permite uma verificação de tipos flexível, em que itens individuais podem ser comparados com o conjunto usando operadores de igualdade e de desigualdade.

Isso é usado para constantes de tipo como STRING, BINARY, NUMBER etc., permitindo comparações como “field_type == STRING”, em que field_type é um único valor de tipo.

Exemplos

>>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING])
>>> FIELD_TYPE.STRING == string_types  # Retorna True
>>> FIELD_TYPE.INT != string_types     # Retorna True
>>> FIELD_TYPE.BLOB in string_types    # Retorna False

frozenset estendido para comparação de tipos da DB-API 2.0.

Esta classe estende frozenset para oferecer suporte à semântica de comparação de tipos da DB-API 2.0. Ela permite uma verificação de tipos flexível, na qual itens individuais podem ser comparados com o conjunto usando operadores de igualdade e desigualdade.

Isso é usado para constantes de tipo como STRING, BINARY, NUMBER etc., permitindo comparações como “field_type == STRING”, em que field_type é um único valor de tipo.

Exemplos

>>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING])
>>> FIELD_TYPE.STRING == string_types  # Returns True
>>> FIELD_TYPE.INT != string_types     # Returns True
>>> FIELD_TYPE.BLOB in string_types    # Returns False

Exemplos de uso

Exemplo de consulta básica:

import chdb.dbapi as dbapi

print("chdb driver version: {0}".format(dbapi.get_client_info()))

# Create connection and cursor
conn = dbapi.connect()
cur = conn.cursor()

# Execute query
cur.execute('SELECT version()')
print("description:", cur.description)
print("data:", cur.fetchone())

# Clean up
cur.close()
conn.close()

Trabalhando com dados:

import chdb.dbapi as dbapi

conn = dbapi.connect()
cur = conn.cursor()

# Create table
cur.execute("""
    CREATE TABLE employees (
        id UInt32,
        name String,
        department String,
        salary Decimal(10,2)
    ) ENGINE = Memory
""")

# Insert data
cur.execute("""
    INSERT INTO employees VALUES
    (1, 'Alice', 'Engineering', 75000.00),
    (2, 'Bob', 'Marketing', 65000.00),
    (3, 'Charlie', 'Engineering', 80000.00)
""")

# Query data
cur.execute("SELECT * FROM employees WHERE department = 'Engineering'")

# Fetch results
print("Column names:", [desc[0] for desc in cur.description])
for row in cur.fetchall():
    print(row)

conn.close()

Gerenciamento de conexões:

import chdb.dbapi as dbapi

# Temporary database (default)
conn1 = dbapi.connect()

# Persistent database file
conn2 = dbapi.connect("./my_database.chdb")

# Connection with parameters
conn3 = dbapi.connect("./my_database.chdb?log-level=debug&verbose")

# Read-only connection
conn4 = dbapi.connect("./my_database.chdb?mode=ro")

# Automatic connection cleanup
with dbapi.connect("test.chdb") as conn:
    cur = conn.cursor()
    cur.execute("SELECT count() FROM numbers(1000)")
    result = cur.fetchone()
    print(f"Count: {result[0]}")
    cur.close()

Melhores práticas

1. Gerenciamento de conexões: Sempre feche conexões e cursores ao concluir
2. Gerenciadores de contexto: Use instruções with para limpeza automática
3. Processamento em lote: Use fetchmany() para grandes conjuntos de resultados
4. Tratamento de erros: Envolva operações de banco de dados em blocos try-except
5. Vinculação de parâmetros: Use consultas parametrizadas sempre que possível
6. Gerenciamento de memória: Evite fetchall() para conjuntos de dados muito grandes

O chDB oferece suporte a UDFs nativas em Python executadas no mesmo processo, com argumentos tipados, inferência automática de tipos e tratamento configurável de NULL/exceções. Funções Python registradas como UDFs podem ser chamadas diretamente em consultas SQL.

Os exemplos abaixo usam o formato de saída CSV padrão. Comentários inline mostram os valores lógicos resultantes; a saída bruta imprime NULL como \N e aplica delimitação CSV a valores de string e data.

Registre uma função Python como uma função SQL do chDB.

Sintaxe

chdb.create_function(name, func, arg_types=None, return_type=None, *, on_null=None, on_error=None)

Parâmetros

Cada parâmetro de tipo (os elementos de arg_types e return_type) aceita:

• Uma constante ChdbType: INT64, STRING, FLOAT64 etc.
• Uma string de tipo do ClickHouse: "Int64", "String", "DateTime64(6)", "DateTime('UTC')" etc.
• Um tipo Python: int, float, str, bool, bytes, datetime.date, datetime.datetime — mapeado conforme o mapeamento automático de tipos

Registrar um nome já registrado gera um erro — UDFs não são substituídas silenciosamente. Para registrar novamente uma função, chame primeiro drop_function.

Exemplo

from chdb import create_function, drop_function, query
from chdb.sqltypes import INT64, STRING

create_function("strlen", len, arg_types=[STRING], return_type=INT64)
print(query("SELECT strlen('hello')"))  # 5

drop_function("strlen")

Remove uma UDF Python registrada anteriormente. Não faz nada se a função não estiver registrada, portanto pode ser chamada incondicionalmente com segurança.

Sintaxe

chdb.drop_function(name)

Parâmetros

Decorador para registrar uma função Python como função SQL do chDB. A função continua podendo ser chamada normalmente em Python e também fica disponível em consultas SQL pelo seu __name__.

Sintaxe

from chdb import func

@func(arg_types=None, return_type=None, *, on_null=None, on_error=None)
def my_function(...):
    ...

Parâmetros

Os mesmos de create_function (exceto name e func, que são derivados da função decorada).

Exemplos

from chdb import func, query
from chdb.sqltypes import INT64, STRING

# Explicit types
@func([INT64, INT64], INT64)
def add(a, b):
    return a + b

# Types inferred from annotations
@func()
def multiply(a: int, b: int) -> int:
    return a * b

# Explicit return_type, arg_types inferred from annotations
@func(return_type=STRING)
def greet(name: str):
    return f"Hello, {name}!"

print(query("SELECT add(12, 22)"))       # 34
print(query("SELECT multiply(3, 7)"))    # 21
print(query("SELECT greet('world')"))    # Hello, world!

Importe os tipos de chdb.sqltypes:

from chdb.sqltypes import (
    BOOL,
    INT8, INT16, INT32, INT64, INT128, INT256,
    UINT8, UINT16, UINT32, UINT64, UINT128, UINT256,
    FLOAT32, FLOAT64,
    STRING,
    DATE, DATE32, DATETIME, DATETIME64,
)

Quando os tipos são inferidos a partir de anotações Python, é usado o seguinte mapeamento:

Os tipos podem ser especificados de várias maneiras:

from chdb import create_function, func
from chdb.sqltypes import INT64

# 1. ChdbType constants
create_function("f1", lambda x: x, arg_types=[INT64], return_type=INT64)

# 2. ClickHouse type strings
create_function("f2", lambda x: x, arg_types=["Int64"], return_type="Int64")

# 3. Parameterized type strings
create_function("f3", lambda x: x, arg_types=["DateTime('UTC')"], return_type="DateTime('UTC')")

# 4. Python types — passed directly or used as annotations
create_function("f4", lambda x: x, arg_types=[int], return_type=int)

@func()
def f5(x: int) -> int:
    return x

Controle como os valores NULL são tratados usando o parâmetro on_null.

from chdb import func, query, NullHandling

# Default: NULL in → NULL out, function not called
@func(return_type="Int64")
def add_one(x: int) -> int:
    return x + 1

print(query("SELECT add_one(NULL)"))  # NULL

# Pass NULL as None
@func(return_type="Int64", on_null="pass")
def null_safe(x):
    return 0 if x is None else x + 1

print(query("SELECT null_safe(NULL)"))  # 0

Controle como as exceções são tratadas com o parâmetro on_error.

from chdb import func, query

# Default: exception propagates
@func(arg_types=["Int64", "Int64"], return_type="Int64")
def divide(a, b):
    return a // b

# print(query("SELECT divide(1, 0)"))  # Error: division by zero

# Ignore: exception → NULL
@func(arg_types=["Int64", "Int64"], return_type="Int64", on_error="ignore")
def safe_divide(a, b):
    return a // b

print(query("SELECT safe_divide(1, 0)"))   # NULL
print(query("SELECT safe_divide(10, 2)"))  # 5

As UDFs oferecem suporte completo aos tipos Date, Date32, DateTime e DateTime64 com reconhecimento de fuso horário.

from chdb import func, query
from datetime import datetime, timedelta, date

@func(arg_types=["DateTime('UTC')"], return_type="DateTime('UTC')")
def add_one_hour(dt):
    return dt + timedelta(hours=1)

@func()
def get_year(d: date) -> int:
    return d.year

print(query("SELECT add_one_hour(toDateTime('2024-01-01 12:00:00', 'UTC'))"))  # 2024-01-01 13:00:00
print(query("SELECT get_year(toDate('2024-06-15'))"))  # 2024

• Valores de Input DateTime/DateTime64 do ClickHouse são convertidos em objetos datetime do Python com informações de fuso horário
• Objetos datetime de Output do Python preservam as informações de fuso horário quando retornados ao ClickHouse
• O tipo DATETIME64 de chdb.sqltypes usa scale 6 (microssegundos) por padrão, equivalente a DateTime64(6)

Decorador para UDFs (funções definidas pelo usuário) em Python do chDB.

Sintaxe

chdb.udf.chdb_udf(return_type='String')

Parâmetros

Observações

1. A função deve ser sem estado. Apenas UDFs são compatíveis, não UDAFs.
2. O tipo de retorno padrão é String. O tipo de retorno deve ser um dos tipos de dados do ClickHouse.
3. A função deve aceitar argumentos do tipo String. Todos os argumentos são strings.
4. A função será chamada para cada linha de entrada.
5. A função deve ser uma função Python pura. Importe todos os módulos usados NA FUNÇÃO.
6. O interpretador Python usado é o mesmo utilizado para executar o script.

Exemplo

@chdb_udf()
def sum_udf(lhs, rhs):
    return int(lhs) + int(rhs)

@chdb_udf()
def func_use_json(arg):
    import json
    # ... use json module

Gera arquivos de configuração de UDF e scripts executáveis.

Esta função cria os arquivos necessários para uma função definida pelo usuário (UDF) no chDB:

1. Um script executável em Python que processa os dados de entrada
2. Um arquivo de configuração XML que registra a UDF no ClickHouse

Sintaxe

chdb.udf.generate_udf(func_name, args, return_type, udf_body)

Parâmetros

Funções utilitárias e auxiliares do chDB.

Este módulo contém várias funções utilitárias para trabalhar com o chDB, incluindo inferência de tipos de dados, auxiliares de conversão de dados e utilitários de depuração.

Converte uma lista de dicionários para o formato colunar.

Esta função recebe uma lista de dicionários e a converte em um dicionário no qual cada chave corresponde a uma coluna e cada valor é uma lista de valores dessa coluna. Valores ausentes nos dicionários são representados como None.

Sintaxe

chdb.utils.convert_to_columnar(items: List[Dict[str, Any]]) → Dict[str, List[Any]]

Parâmetros

Retorna

Exemplo

>>> items = [
...     {"name": "Alice", "age": 30, "city": "New York"},
...     {"name": "Bob", "age": 25},
...     {"name": "Charlie", "city": "San Francisco"}
... ]
>>> convert_to_columnar(items)
{
    'name': ['Alice', 'Bob', 'Charlie'],
    'age': [30, 25, None],
    'city': ['New York', None, 'San Francisco']
}

Achata um dicionário aninhado.

Esta função recebe um dicionário aninhado e o transforma em uma estrutura plana, concatenando as chaves aninhadas com um separador. Listas de dicionários são serializadas como strings JSON.

Sintaxe

chdb.utils.flatten_dict(d: Dict[str, Any], parent_key: str = '', sep: str = '_') → Dict[str, Any]

Parâmetros

Retorno

Exemplo

>>> nested_dict = {
...     "a": 1,
...     "b": {
...         "c": 2,
...         "d": {
...             "e": 3
...         }
...     },
...     "f": [4, 5, {"g": 6}],
...     "h": [{"i": 7}, {"j": 8}]
... }
>>> flatten_dict(nested_dict)
{
    'a': 1,
    'b_c': 2,
    'b_d_e': 3,
    'f_0': 4,
    'f_1': 5,
    'f_2_g': 6,
    'h': '[{"i": 7}, {"j": 8}]'
}

Infere o tipo de dado mais adequado para uma lista de valores.

Esta função analisa uma lista de valores e determina o tipo de dado mais apropriado para representar todos os valores da lista. Ela considera tipos inteiros, inteiros sem sinal, decimais e de ponto flutuante, e usa “string” por padrão se os valores não puderem ser representados por nenhum tipo numérico ou se todos os valores forem None.

Sintaxe

chdb.utils.infer_data_type(values: List[Any]) → str

Parâmetros

Retorna

Infere os tipos de dados de cada coluna em uma estrutura de dados colunar.

Esta função analisa os valores de cada coluna e infere o tipo de dado mais adequado para cada uma, com base em uma amostra dos dados.

Sintaxe

chdb.utils.infer_data_types`(column_data: Dict[str, List[Any]], n_rows: int = 10000) → List[tuple]

Parâmetros

Retorna

Bases: ABC

class chdb.rwabc.PyReader(data: Any)

Lê um número especificado de linhas das colunas fornecidas e retorna uma lista de objetos, em que cada objeto é uma sequência de valores de uma coluna.

abstractmethod (col_names: List[str], count: int) → List[Any]

Parâmetros

Retorno

Bases: ABC

class chdb.rwabc.PyWriter(col_names: List[str], types: List[type], data: Any)

Monta e retorna os dados finais a partir dos blocos. Deve ser implementado por subclasses.

abstractmethod finalize() → bytes

Retorno

Salva colunas de dados em blocos. Deve ser implementado pelas subclasses.

abstractmethod write(col_names: List[str], columns: List[List[Any]]) → None

Parâmetros

Bases: Exception

Classe base de exceção para erros relacionados ao chDB.

Essa exceção é gerada quando a execução de uma consulta no chDB falha ou encontra um erro. Ela herda da classe Exception padrão do Python e fornece informações de erro do mecanismo subjacente do ClickHouse.

A mensagem da exceção normalmente contém informações detalhadas sobre o erro do ClickHouse, incluindo erros de sintaxe, incompatibilidades de tipo, ausência de tabelas/colunas e outros problemas na execução de consultas.

Variáveis

Exemplos

>>> try:
...     result = chdb.query("SELECT * FROM non_existent_table")
... except chdb.ChdbError as e:
...     print(f"Query failed: {e}")
Query failed: Table 'non_existent_table' doesn't exist

>>> try:
...     result = chdb.query("SELECT invalid_syntax FROM")
... except chdb.ChdbError as e:
...     print(f"Syntax error: {e}")
Syntax error: Syntax error near 'FROM'

Sequência imutável embutida.

Se nenhum argumento for fornecido, o construtor retornará uma tupla vazia. Se iterable for especificado, a tupla será inicializada a partir dos itens de iterable.

Se o argumento for uma tupla, o valor retornado será o mesmo objeto.

str(object=’’) -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str