Referencia de la API de Python para chDB

Ejecuta una consulta SQL con el motor de chDB.

Esta es la función principal de consulta, que ejecuta sentencias SQL con el motor ClickHouse integrado. Admite varios formatos de salida y puede trabajar con bases de datos temporales o basadas en archivos.

Sintaxis

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

Parámetros

Devuelve

Devuelve el resultado de la consulta en el formato especificado:

Lanza

Ejemplos

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

Ejecuta una consulta SQL con el motor de chDB.

Esta es la función principal para consultas, que ejecuta sentencias SQL mediante el motor ClickHouse integrado. Admite varios formatos de salida y puede trabajar con bases de datos temporales o basadas en archivos.

Sintaxis

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

Parámetros

Devuelve

Devuelve el resultado de la consulta en el formato especificado:

Lanza

Ejemplos

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

Convierte el resultado de la consulta en una tabla de PyArrow.

Convierte el resultado de una consulta de chDB en una tabla de PyArrow para procesar datos de forma eficiente en formato columnar. Devuelve una tabla vacía si el resultado está vacío.

Sintaxis

chdb.to_arrowTable(res)

Parámetros

Devuelve

Lanza

Ejemplo

>>> 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

Convierte el resultado de la consulta en un DataFrame de pandas.

Convierte el resultado de una consulta de chDB en un DataFrame de pandas convirtiéndolo primero en una tabla de PyArrow y luego en pandas mediante multihilo para mejorar el rendimiento.

Sintaxis

chdb.to_df(r)

Parámetros

Devuelve

Excepciones

Ejemplo

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

Las siguientes funciones de sesión están disponibles:

Crea una conexión con el servidor en segundo plano de chDB.

Esta función establece una conexión con el motor de base de datos chDB (ClickHouse). Cada llamada devuelve una conexión independiente, y puede haber abiertas al mismo tiempo cualquier cantidad de conexiones a la misma ruta de base de datos.

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

Parámetros:

Formatos básicos

Con parámetros de consulta

Gestión de parámetros de consulta

Los parámetros de consulta se pasan al motor de ClickHouse como argumentos de inicio. Gestión especial de parámetros:

Para ver la lista completa de parámetros, consulta clickhouse local --help --verbose

Devuelve

Lanza

Ejemplos

>>> # 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

Véase también

• Connection - Clase de conexión a la base de datos
• Cursor - Cursor de la base de datos para operaciones de DB-API 2.0

Bases: Exception

Clase base de excepción para los errores relacionados con chDB.

Esta excepción se produce cuando falla la ejecución de una consulta de chDB o se encuentra un error. Hereda de la clase estándar Exception de Python y proporciona información sobre errores del motor subyacente de ClickHouse.

Bases: object

La sesión mantendrá el estado de la consulta. Si path es None, la sesión usa la base de datos temporal (:memory:) compartida por todo el proceso, por lo que todas las sesiones sin ruta pueden ver las tablas de las demás; su directorio temporal solo se elimina cuando se cierra la última sesión o conexión de este tipo. También puede pasar una ruta para crear una base de datos en esa ubicación, donde se conservarán sus datos.

También puede usar una cadena de conexión para pasar la ruta y otros parámetros.

class chdb.session.Session(path=None)

Ejemplos

Limpia los recursos de la sesión con control de excepciones.

Este método intenta cerrar la sesión mientras suprime cualquier excepción que pueda producirse durante el proceso de limpieza. Resulta especialmente útil en escenarios de manejo de errores o cuando necesitas garantizar que la limpieza se realice independientemente del estado de la sesión.

Sintaxis

cleanup()

Ejemplos

>>> session = Session("test.db")
>>> try:
...     session.query("INVALID SQL")
... finally:
...     session.cleanup()  # Limpieza segura independientemente de los errores

Véase también

• close() - Para cerrar la sesión explícitamente con propagación de errores

Cierra la sesión y libera los recursos.

Este método cierra la conexión subyacente y restablece el estado global de la sesión. Después de llamar a este método, la sesión deja de ser válida y no puede usarse para más consultas.

Sintaxis

close()

Ejemplos

>>> session = Session("test.db")
>>> session.query("SELECT 1")
>>> session.close()  # Cerrar la sesión de forma explícita

Ejecuta una consulta SQL y devuelve los resultados.

Este método ejecuta una consulta SQL sobre la base de datos de la sesión y devuelve los resultados en el formato especificado. El método admite varios formatos de salida y mantiene el estado de la sesión entre consultas.

Sintaxis

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

Parámetros

Devuelve

Devuelve los resultados de la consulta en el formato especificado. El tipo de retorno exacto depende del parámetro de formato:

• Los formatos de cadena (CSV, JSON, etc.) devuelven str
• Los formatos binarios (Arrow, Parquet) devuelven bytes

Genera

Ejemplos

>>> 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

Véase también

• send_query() - Para ejecutar consultas en streaming
• sql - Alias de este método

Ejecuta una consulta SQL y devuelve un iterador de resultados en streaming.

Este método ejecuta una consulta SQL en la base de datos de la sesión y devuelve un objeto de resultados en streaming que permite iterar sobre los resultados sin cargarlo todo en memoria de una sola vez. Esto es especialmente útil para grandes conjuntos de resultados.

Sintaxis

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

Parámetros

Devuelve

Lanza

Ejemplos

>>> session = Session("test.db")
>>> session.query("CREATE TABLE big_table (id INT, data String) ENGINE = MergeTree() order by id")
>>>
>>> # Insertar conjunto de datos grande
>>> for i in range(1000):
...     session.query(f"INSERT INTO big_table VALUES ({i}, 'data_{i}')")
>>>
>>> # Transmitir resultados para evitar problemas de memoria
>>> streaming_result = session.send_query("SELECT * FROM big_table ORDER BY id")
>>> for chunk in streaming_result:
...     print(f"Processing chunk: {len(chunk)} bytes")
...     # Procesar fragmento sin cargar el conjunto de resultados completo

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

Véase también

• query() - Para ejecutar consultas sin streaming
• chdb.state.sqlitelike.StreamingResult - Iterador de resultados en streaming

Ejecuta una consulta SQL y devuelve los resultados.

Este método ejecuta una consulta SQL contra la base de datos de la sesión y devuelve los resultados en el formato especificado. Admite varios formatos de salida y mantiene el estado de la sesión entre consultas.

Sintaxis

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

Parámetros

Devuelve

Devuelve los resultados de la consulta en el formato especificado. El tipo de retorno exacto depende del parámetro de formato:

• Los formatos de cadena (CSV, JSON, etc.) devuelven str
• Los formatos binarios (Arrow, Parquet) devuelven bytes

Genera:

Ejemplos

>>> 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

Véase también

• send_query() - Para ejecutar consultas en streaming
• sql - Alias para este método

Crea una Connection con el servidor en segundo plano de chDB.

Esta función establece una conexión con el motor de base de datos de chDB (ClickHouse). Cada llamada devuelve una conexión independiente, y puede haber abiertas al mismo tiempo cualquier número de conexiones a la misma ruta de base de datos.

Sintaxis

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

Parámetros

Formatos básicos

Formatos de cadena de conexión admitidos:

Con parámetros de consulta

Manejo de parámetros de consulta

Los parámetros de consulta se pasan al motor de ClickHouse como argumentos de inicio. Manejo especial de parámetros:

Para ver la lista completa de parámetros, consulte clickhouse local --help --verbose

Devuelve

Lanza

Ejemplos

>>> # 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

Véase también

• Connection - Clase de conexión a la base de datos
• Cursor - Cursor de base de datos para operaciones de DB-API 2.0

Bases: object

Sintaxis

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

Cierra la conexión y libera los recursos.

Este método cierra la conexión a la base de datos y libera todos los recursos asociados, incluidos los cursores activos. Después de llamar a este método, la conexión deja de ser válida y no puede usarse para realizar más operaciones.

Sintaxis

close() → None

Ejemplos

>>> conn = connect("test.db")
>>> # Usar la conexión para consultas
>>> conn.query("CREATE TABLE test (id INT) ENGINE = Memory")
>>> # Cerrar al terminar
>>> conn.close()

>>> # Usando el gestor de contexto (limpieza automática)
>>> with connect("test.db") as conn:
...     conn.query("SELECT 1")
...     # Conexión cerrada automáticamente

Crea un objeto Cursor para ejecutar consultas.

Este método crea un cursor de base de datos que proporciona la interfaz estándar de DB-API 2.0 para ejecutar consultas y obtener resultados. El cursor permite un control detallado sobre la ejecución de consultas y la obtención de resultados.

Sintaxis

cursor() → Cursor

Devuelve

Ejemplos

>>> 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'),)

Véase también

• Cursor - Implementación de cursor de base de datos

Ejecuta una consulta SQL y devuelve todos los resultados.

Este método ejecuta una consulta SQL de forma síncrona y devuelve el conjunto completo de resultados. Admite varios formatos de salida y aplica automáticamente el posprocesamiento específico de cada formato.

Sintaxis

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

Parámetros:

Devuelve

Genera

Ejemplos

>>> 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

Véase también

• send_query() - Para ejecutar consultas en streaming

Ejecuta una consulta SQL y devuelve un iterador de resultados en streaming.

Este método ejecuta una consulta SQL y devuelve un objeto StreamingResult que le permite iterar por los resultados sin cargarlo todo en memoria de una sola vez. Esto es ideal para procesar grandes conjuntos de resultados.

Sintaxis

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

Parámetros

Devuelve

Genera

Ejemplos

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

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

>>> # Formato Arrow con 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}")

Véase también

• query() - Para ejecutar consultas sin streaming
• StreamingResult - Iterador de resultados en streaming

Bases: object

Iterador de resultados en streaming para procesar resultados de consultas de gran tamaño.

Esta clase proporciona una interfaz de iterador para transmitir resultados de consultas sin cargar todo el conjunto de resultados en memoria. Admite varios formatos de salida y proporciona métodos para la recuperación manual de resultados y la transmisión de RecordBatch de PyArrow.

class chdb.state.sqlitelike.StreamingResult

Obtiene el siguiente fragmento de resultados en streaming.

Este método recupera el siguiente fragmento de datos disponible del resultado de la consulta en streaming. El formato de los datos devueltos depende del formato especificado al iniciar la consulta en streaming.

Sintaxis

fetch() → Any

Valores devueltos

Ejemplos

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

Cancela la consulta en streaming y libera los recursos.

Este método cancela cualquier consulta en streaming en curso y libera los recursos asociados. Debe llamarse cuando se quiera dejar de procesar los resultados antes de que se agote el flujo.

Sintaxis

cancel() → None

Ejemplos

>>> stream = conn.send_query("SELECT * FROM very_large_table")
>>> for i, chunk in enumerate(stream):
...     if i >= 10:  # Procesa solo los primeros 10 fragmentos
...         stream.cancel()
...         break
...     process_data(chunk)

Cierra el resultado en streaming y libera los recursos.

Alias de cancel(). Cierra el iterador del resultado en streaming y libera los recursos asociados.

Sintaxis

close() → None

Crea un PyArrow RecordBatchReader para procesar lotes de forma eficiente.

Este método crea un PyArrow RecordBatchReader que permite iterar de forma eficiente sobre los resultados de la consulta en formato Arrow. Esta es la forma más eficiente de procesar conjuntos de resultados grandes al usar PyArrow.

Sintaxis

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

Parámetros

Devuelve

Ejemplos

>>> 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 es compatible con el protocolo de iteración de Python, lo que permite usarlo directamente en bucles for:

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

StreamingResult admite el protocolo del gestor de contexto para la liberación automática de recursos:

>>> with conn.send_query("SELECT * FROM data") as stream:
...     for chunk in stream:
...         process(chunk)
>>> # Stream cerrado automáticamente

Bases: object

class chdb.state.sqlitelike.Cursor(connection)

Cierra el cursor y libera los recursos.

Este método cierra el cursor y libera cualquier recurso asociado. Después de llamar a este método, el cursor queda invalidado y no puede usarse en operaciones posteriores.

Sintaxis

close() → None

Ejemplos

>>> cursor = conn.cursor()
>>> cursor.execute("SELECT 1")
>>> result = cursor.fetchone()
>>> cursor.close()  # Liberar recursos del cursor

Devuelve una lista de nombres de columnas de la última consulta ejecutada.

Este método devuelve los nombres de las columnas de la consulta SELECT ejecutada más recientemente. Los nombres se devuelven en el mismo orden en que aparecen en el conjunto de resultados.

Sintaxis

column_names() → list

Devuelve

Ejemplos

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

Véase también

• column_types() - Obtiene información sobre el tipo de columna
• description - Descripción de columna de la DB-API 2.0

Devuelve una lista de los tipos de las columnas de la última consulta ejecutada.

Este método devuelve los nombres de tipo de las columnas de ClickHouse de la consulta SELECT ejecutada más recientemente. Los tipos se devuelven en el mismo orden en que aparecen en el conjunto de resultados.

Sintaxis

column_types() → list

Devuelve

Ejemplos

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

Véase también

• column_names() - Obtiene información sobre los nombres de las columnas
• description - descripción de columnas de DB-API 2.0

Hace commit de cualquier transacción pendiente.

Este método hace commit de cualquier transacción pendiente de la base de datos. En ClickHouse, la mayoría de las operaciones se confirman automáticamente, pero este método se proporciona por compatibilidad con DB-API 2.0.

Sintaxis

commit() → None

Ejemplos

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

Devuelve la descripción de las columnas según la especificación DB-API 2.0.

Esta propiedad devuelve una lista de tuplas de 7 elementos que describen cada columna del conjunto de resultados de la última consulta SELECT ejecutada. Cada tupla contiene: (name, type_code, display_size, internal_size, precision, scale, null_ok)

Actualmente, solo se proporcionan name y type_code; los demás campos se establecen en None.

Devuelve

Ejemplos

>>> 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

Véase también

• column_names() - Obtener solo los nombres de las columnas
• column_types() - Obtener solo los tipos de las columnas

Ejecuta una consulta SQL y prepara los resultados para su obtención.

Este método ejecuta una consulta SQL y deja los resultados listos para su obtención mediante los métodos fetch. Se encarga del análisis de los datos de resultados y de la conversión automática de tipos de datos de ClickHouse.

Sintaxis

execute(query: str) → None

Parámetros:

Excepciones

Ejemplos

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

Véase también

• fetchone() - Recuperar una sola fila
• fetchmany() - Recuperar varias filas
• fetchall() - Recuperar todas las filas restantes

Obtiene todas las filas restantes del resultado de la consulta.

Este método obtiene todas las filas restantes del conjunto de resultados de la consulta actual a partir de la posición actual del cursor. Devuelve una tupla de tuplas de filas con la conversión adecuada de tipos de Python.

Sintaxis

fetchall() → tuple

Devuelve:

Ejemplos

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

Véase también

• fetchone() - Obtener una fila
• fetchmany() - Obtener varias filas en lotes

Obtiene varias filas del resultado de la consulta.

Este método recupera hasta ‘size’ filas del conjunto de resultados de la consulta actual. Devuelve una tupla de tuplas, donde cada fila contiene valores de columna con la conversión adecuada al tipo de Python.

Sintaxis

fetchmany(size: int = 1) → tuple

Parámetros

Devuelve

Ejemplos

>>> cursor = conn.cursor()
>>> cursor.execute("SELECT * FROM large_table")
>>>
>>> # Procesar resultados en lotes
>>> while True:
...     batch = cursor.fetchmany(100)  # Obtener 100 filas a la vez
...     if not batch:
...         break
...     process_batch(batch)

Véase también

• fetchone() - Obtiene una sola fila
• fetchall() - Obtiene todas las filas restantes

Obtiene la siguiente fila del resultado de la consulta.

Este método recupera la siguiente fila disponible del conjunto de resultados de la consulta actual. Devuelve una tupla que contiene los valores de las columnas con la conversión al tipo de Python correspondiente.

Sintaxis

fetchone() → tuple | None

Devuelve:

Ejemplos

>>> 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()

Véase también

• fetchmany() - Obtener varias filas
• fetchall() - Obtener todas las filas restantes

Convierte el resultado de la consulta en una tabla de PyArrow.

Esta función convierte los resultados de las consultas de chdb al formato de tabla de PyArrow, que proporciona acceso eficiente a datos en formato columnar e interoperabilidad con otras bibliotecas de procesamiento de datos.

Sintaxis

chdb.state.sqlitelike.to_arrowTable(res)

Parámetros:

Devuelve

Genera

Ejemplos

>>> 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

Convierte el resultado de la consulta en un DataFrame de Pandas.

Esta función convierte los resultados de las consultas de chdb en un DataFrame de Pandas, convirtiéndolos primero en una tabla de PyArrow y luego en un DataFrame. Esto proporciona funcionalidades prácticas de análisis de datos con la API de Pandas.

Sintaxis

chdb.state.sqlitelike.to_df(r)

Parámetros:

Devuelve:

Lanza

Véase también

• to_arrowTable() - Para convertir al formato tabla de PyArrow

Ejemplos

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

chDB proporciona una interfaz compatible con Python DB-API 2.0 para conectarse a bases de datos, lo que le permite usar chDB con herramientas y frameworks que requieren interfaces de bases de datos estándar.

La interfaz DB-API 2.0 de chDB incluye:

• Conexiones: Gestión de conexiones de bases de datos mediante cadenas de conexión
• Cursores: Ejecución de consultas y recuperación de resultados
• Sistema de tipos: Constantes de tipo y conversores compatibles con DB-API 2.0
• Gestión de errores: Jerarquía estándar de excepciones de bases de datos
• Seguridad de hilos: Seguridad de hilos de nivel 1 (los hilos pueden compartir módulos, pero no conexiones)

La interfaz DBAPI 2.0 (API de bases de datos) implementa las siguientes funciones principales:

Inicializa una nueva conexión a la base de datos.

Sintaxis

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

Parámetros

Lanza

Obtiene información sobre la versión del cliente.

Devuelve la versión del cliente chDB como una cadena para mantener la compatibilidad con MySQLdb.

Sintaxis

chdb.dbapi.get_client_info()

Devuelve

Devuelve x como tipo binario.

Esta función convierte la entrada al tipo bytes para usarla con campos binarios de la base de datos, de acuerdo con la especificación DB-API 2.0.

Sintaxis

chdb.dbapi.Binary(x)

Parámetros

Devuelve

Bases: object

Conexión compatible con DB-API 2.0 a la base de datos chDB.

Esta clase proporciona una interfaz estándar de DB-API para conectarse a bases de datos chDB e interactuar con ellas. Admite tanto bases de datos temporales como bases de datos basadas en archivos.

La conexión administra el engine de chDB subyacente y proporciona métodos para ejecutar consultas, gestionar transacciones (sin efecto en ClickHouse) y crear cursores.

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

Parámetros

Variables

Ejemplos

>>> # 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()

Cierra la conexión a la base de datos.

Cierra la conexión subyacente de chDB y marca esta conexión como cerrada. Las operaciones posteriores en esta conexión producirán un Error.

Sintaxis

close()

Lanza

Realiza commit de la transacción actual.

Sintaxis

commit()

Crea un nuevo cursor para ejecutar consultas.

Sintaxis

cursor(cursor=None)

Parámetros

Devuelve

Genera

Ejemplo

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

Escapa un valor para incluirlo de forma segura en consultas SQL.

Sintaxis

escape(obj, mapping=None)

Parámetros

Devuelve

Ejemplo

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

Escapa una cadena para consultas SQL.

Sintaxis

escape_string(s)

Parámetros

Devuelve

Comprueba si la conexión está abierta.

Devuelve

Ejecuta una consulta SQL directamente y devuelve resultados sin procesar.

Este método omite la interfaz de cursor y ejecuta las consultas directamente. Para el uso estándar de DB-API, se recomienda usar el método cursor().

Sintaxis

query(sql, fmt='CSV')

Parámetros:

Devuelve

Genera

Ejemplo

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

Obtiene la respuesta de la última consulta.

Devuelve

Deshace la transacción actual.

Sintaxis

rollback()

Bases: object

Cursor de DB-API 2.0 para ejecutar consultas y obtener resultados.

El cursor proporciona métodos para ejecutar sentencias SQL, gestionar los resultados de las consultas y desplazarse por los conjuntos de resultados. Admite el enlace de parámetros, operaciones masivas y sigue las especificaciones de DB-API 2.0.

No cree instancias de Cursor directamente. Use Connection.cursor() en su lugar.

class chdb.dbapi.cursors.Cursor(connection)

Ejemplos

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

Ejecuta un procedimiento almacenado (implementación provisional).

Sintaxis

callproc(procname, args=())

Parámetros

Devuelve

Cierra el cursor y libera los recursos asociados.

Después de cerrarlo, el cursor ya no se puede usar y cualquier operación generará una excepción. Al cerrar un cursor, se consumen todos los datos restantes y se libera el cursor subyacente.

Sintaxis

close()

Ejecuta una consulta SQL con enlace opcional de parámetros.

Este método ejecuta una sola sentencia SQL con sustitución opcional de parámetros. Admite varios estilos de marcadores de posición para parámetros, lo que aporta flexibilidad.

Sintaxis

execute(query, args=None)

Parámetros

Devuelve

Estilos de parámetros

Ejemplos

>>> # Parámetros con signo de interrogación
>>> cur.execute("SELECT * FROM users WHERE id = ? AND age > ?", (123, 18))
>>>
>>> # Parámetros con nombre
>>> cur.execute("SELECT * FROM users WHERE name = %(name)s", {'name': 'Alice'})
>>>
>>> # Sin parámetros
>>> cur.execute("SELECT COUNT(*) FROM users")

Excepciones

Ejecuta una consulta varias veces con distintos conjuntos de parámetros.

Este método ejecuta de forma eficiente la misma consulta SQL varias veces con distintos valores de parámetros. Resulta especialmente útil para operaciones de INSERT masivas.

Sintaxis

executemany(query, args)

Parámetros

Devuelve

Ejemplos

>>> # Inserción masiva con parámetros de signo de interrogación
>>> users_data = [(1, 'Alice'), (2, 'Bob'), (3, 'Charlie')]
>>> cur.executemany("INSERT INTO users VALUES (?, ?)", users_data)
>>>
>>> # Inserción masiva con parámetros con nombre
>>> users_data = [
...     {'id': 1, 'name': 'Alice'},
...     {'id': 2, 'name': 'Bob'}
... ]
>>> cur.executemany(
...     "INSERT INTO users VALUES (%(id)s, %(name)s)",
...     users_data
... )

Obtiene todas las filas restantes del resultado de la consulta.

Sintaxis

fetchall()

Devuelve

Lanza

Ejemplo

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

Devuelve varias filas del resultado de la consulta.

Sintaxis

fetchmany(size=1)

Parámetros

Devuelve

Lanza

Ejemplo

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

Obtiene la siguiente fila del resultado de la consulta.

Sintaxis

fetchone()

Devuelve

Lanza

Ejemplo

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

Tamaño máximo de la sentencia generada por executemany().

El valor predeterminado es 1024000.

Devuelve la cadena de consulta exacta que se enviaría a la base de datos.

Este método muestra la consulta SQL final tras la sustitución de parámetros, lo que resulta útil para tareas de depuración y registro.

Sintaxis

mogrify(query, args=None)

Parámetros

Devuelve

Ejemplo

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

Pasa al siguiente conjunto de resultados (no se admite).

Sintaxis

nextset()

Devuelve

Establece los tamaños de entrada de los parámetros (sin efecto).

Sintaxis

setinputsizes(*args)

Parámetros

Establece los tamaños de las columnas de salida (implementación sin efecto).

Sintaxis

setoutputsizes(*args)

Parámetros

Clases de excepción para las operaciones de base de datos en chdb.

Este módulo proporciona una jerarquía completa de clases de excepción para manejar errores relacionados con la base de datos en chdb, siguiendo la especificación v2.0 de la Python Database API.

La jerarquía de excepciones está estructurada de la siguiente manera:

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

Cada clase de excepción representa una categoría específica de errores de base de datos:

Véase también

• Python Database API Specification v2.0
• chdb.dbapi.connections - Gestión de conexiones de base de datos
• chdb.dbapi.cursors - Operaciones del cursor de base de datos

Ejemplos

>>> 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

Excepción que se produce por errores debidos a problemas con los datos procesados.

Esta excepción se genera cuando las operaciones de la base de datos fallan debido a problemas con los datos que se están procesando, como por ejemplo:

• Operaciones de división por cero
• Valores numéricos fuera de rango
• Valores de fecha/hora no válidos
• Errores por truncamiento de cadenas
• Errores de conversión de tipos
• Formato de datos no válido para el tipo de columna

Lanza

Ejemplos

>>> # División por cero en SQL
>>> cursor.execute("SELECT 1/0")
DataError: Division by zero

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

Bases: Error

Excepción generada para errores relacionados con la base de datos.

Esta es la clase base para todos los errores relacionados con la base de datos. Abarca todos los errores que se producen durante las operaciones de base de datos y están relacionados con la propia base de datos, en lugar de con la interfaz.

Los casos habituales incluyen:

• Errores de ejecución de SQL
• Problemas de conectividad con la base de datos
• Problemas relacionados con transacciones
• Infracciones de restricciones específicas de la base de datos

Bases: StandardError

Excepción que es la clase base de todas las demás excepciones de error (no Warning).

Esta es la clase base de todas las excepciones de error en chdb, excluidas las advertencias. Sirve como clase padre de todas las condiciones de error de la base de datos que impiden la correcta finalización de las operaciones.

Véase también

• Warning - Para advertencias no fatales que no impiden la finalización de la operación

Bases: DatabaseError

Excepción que se produce cuando la integridad relacional de la base de datos se ve afectada.

Esta excepción se produce cuando las operaciones de la base de datos infringen restricciones de integridad, entre ellas:

• Infracciones de restricciones de clave foránea
• Infracciones de clave primaria o de restricción de unicidad (claves duplicadas)
• Infracciones de restricciones CHECK
• Infracciones de restricciones NOT NULL
• Infracciones de integridad referencial

Genera

Ejemplos

>>> # Clave primaria duplicada
>>> cursor.execute("INSERT INTO users (id, name) VALUES (1, 'John')")
>>> cursor.execute("INSERT INTO users (id, name) VALUES (1, 'Jane')")
IntegrityError: Duplicate entry '1' for key 'PRIMARY'

>>> # Violación de clave foránea
>>> cursor.execute("INSERT INTO orders (user_id) VALUES (999)")
IntegrityError: Cannot add or update a child row: foreign key constraint fails

Bases: Error

Excepción que se genera por errores relacionados con la interfaz de la base de datos, y no con la propia base de datos.

Esta excepción se genera cuando hay problemas con la implementación de la interfaz de la base de datos, como:

• Parámetros de conexión no válidos
• Uso incorrecto de la API (llamadas a métodos en conexiones cerradas)
• Errores de protocolo a nivel de interfaz
• Fallos al importar o inicializar el módulo

Genera

Bases: DatabaseError

Excepción que se lanza cuando la base de datos encuentra un error interno.

Esta excepción se produce cuando el sistema de base de datos detecta errores internos que no han sido causados por la aplicación, como por ejemplo:

• Estado de cursor no válido (el cursor ya no es válido)
• Inconsistencias en el estado de la transacción (la transacción está desincronizada)
• Problemas de corrupción de la base de datos
• Corrupción de la estructura interna de datos
• Errores de base de datos a nivel del sistema

Lanza

Bases: DatabaseError

Excepción que se produce cuando no se admite un método o una API de base de datos.

Esta excepción se produce cuando la aplicación intenta usar funciones de la base de datos o métodos de la API que no son compatibles con la configuración o la versión actuales de la base de datos, por ejemplo:

• Solicitar rollback() en conexiones sin compatibilidad con transacciones
• Usar funciones avanzadas de SQL no compatibles con la versión de la base de datos
• Llamar a métodos no implementados por el controlador actual
• Intentar usar funciones de la base de datos deshabilitadas

Genera

Ejemplos

>>> # Reversión de transacción en una conexión no transaccional
>>> connection.rollback()
NotSupportedError: Transactions are not supported

>>> # Uso de sintaxis SQL no compatible
>>> cursor.execute("SELECT * FROM table WITH (NOLOCK)")
NotSupportedError: WITH clause not supported in this database version

Bases: DatabaseError

Excepción que se produce ante errores relacionados con el funcionamiento de la base de datos.

Esta excepción se produce por errores que ocurren durante el funcionamiento de la base de datos y que no están necesariamente bajo el control del programador, entre ellos:

• Desconexión inesperada de la base de datos
• Servidor de base de datos no encontrado o inaccesible
• Fallos en el procesamiento de transacciones
• Errores de asignación de memoria durante el procesamiento
• Falta de espacio en disco o agotamiento de recursos
• Errores internos del servidor de base de datos
• Fallos de autenticación o autorización

Lanza

Bases: DatabaseError

Excepción que se produce por errores de programación en operaciones de base de datos.

Esta excepción se produce cuando hay errores de programación en el uso que hace la aplicación de la base de datos, entre ellos:

• Tabla o columna no encontrada
• La tabla o el índice ya existen al intentar crearlos
• Errores de sintaxis SQL en sentencias
• Número incorrecto de parámetros especificados en sentencias preparadas
• Operaciones SQL no válidas (p. ej., DROP sobre objetos inexistentes)
• Uso incorrecto de métodos de la API de base de datos

Lanza

Ejemplos

>>> # Tabla no encontrada
>>> cursor.execute("SELECT * FROM nonexistent_table")
ProgrammingError: Table 'nonexistent_table' doesn't exist

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

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

Bases: Exception

Excepción relacionada con las operaciones en chdb.

Esta es la clase base para todas las excepciones relacionadas con chdb. Hereda de la clase Exception integrada de Python y actúa como raíz de la jerarquía de excepciones para las operaciones de base de datos.

Bases: StandardError

Excepción que se genera para advertencias importantes, como truncamientos de datos durante la inserción, etc.

Esta excepción se genera cuando la operación de base de datos se completa, pero con advertencias importantes que deben señalarse a la aplicación. Entre los casos más comunes se incluyen:

• Truncamiento de datos durante la inserción
• Pérdida de precisión en conversiones numéricas
• Advertencias de conversión de conjunto de caracteres

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

Crea un nuevo objeto de cadena a partir del objeto dado. Si se especifican encoding o errors, el objeto debe exponer un búfer de datos que se decodificará con la codificación indicada y el gestor de errores correspondiente. De lo contrario, devuelve el resultado de object._\_str_\_() (si está definido) o de repr(object).

• encoding tiene como valor predeterminado ‘utf-8’.
• errors tiene como valor predeterminado ‘strict’.

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

Convierte un número o una cadena en un entero, o devuelve 0 si no se proporciona ningún argumento. Si x es un número, devuelve x._int_(). En los números de coma flotante, esto trunca hacia cero.

Si x no es un número o si se proporciona base, entonces x debe ser una cadena, bytes o una instancia de bytearray que represente un literal entero en la base indicada. El literal puede ir precedido de ‘+’ o ‘-’ y estar rodeado de espacios en blanco. La base predeterminada es 10. Las bases válidas son 0 y 2-36. La base 0 significa interpretar la base a partir de la cadena, como en un literal entero.

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

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

Crea un nuevo objeto de cadena a partir del objeto dado. Si se especifica encoding o errors, el objeto debe exponer un búfer de datos que se decodificará usando la codificación indicada y el manejador de errores. De lo contrario, devuelve el resultado de object._str_() (si está definido) o repr(object). El valor predeterminado de encoding es ‘utf-8’. El valor predeterminado de errors es ‘strict’.

frozenset ampliado para la comparación de tipos de DB-API 2.0.

Esta clase amplía frozenset para admitir la semántica de comparación de tipos de DB-API 2.0. Permite una verificación de tipos flexible en la que los elementos individuales pueden compararse con el conjunto mediante operadores tanto de igualdad como de desigualdad.

Se utiliza para constantes de tipo como STRING, BINARY, NUMBER, etc., lo que permite comparaciones como “field_type == STRING”, donde field_type es un único valor de tipo.

Ejemplos

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

frozenset ampliado para la comparación de tipos de DB-API 2.0.

Esta clase amplía frozenset para admitir la semántica de comparación de tipos de DB-API 2.0. Permite una verificación de tipos flexible en la que los elementos individuales pueden compararse con el conjunto mediante operadores tanto de igualdad como de desigualdad.

Se utiliza para constantes de tipo como STRING, BINARY, NUMBER, etc., lo que permite comparaciones como “field_type == STRING”, donde field_type es un único valor de tipo.

Ejemplos

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

frozenset ampliado para la comparación de tipos de DB-API 2.0.

Esta clase amplía frozenset para admitir la semántica de comparación de tipos de DB-API 2.0. Permite una verificación de tipos flexible en la que los elementos individuales pueden compararse con el conjunto mediante operadores de igualdad y desigualdad.

Se utiliza para constantes de tipo como STRING, BINARY, NUMBER, etc., lo que permite comparaciones como “field_type == STRING”, donde field_type es un único valor de tipo.

Ejemplos

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

frozenset ampliado para la comparación de tipos de DB-API 2.0.

Esta clase amplía frozenset para admitir la semántica de comparación de tipos de DB-API 2.0. Permite una verificación de tipos flexible en la que los elementos individuales pueden compararse con el conjunto mediante operadores de igualdad y desigualdad.

Se usa para constantes de tipo como STRING, BINARY, NUMBER, etc., para permitir comparaciones como “field_type == STRING”, donde field_type es un único valor de tipo.

Ejemplos

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

frozenset ampliado para la comparación de tipos de DB-API 2.0.

Esta clase amplía frozenset para admitir la semántica de comparación de tipos de DB-API 2.0. Permite una verificación de tipos flexible, en la que los elementos individuales pueden compararse con el conjunto mediante operadores de igualdad y desigualdad.

Se usa para constantes de tipo como STRING, BINARY, NUMBER, etc., lo que permite comparaciones como “field_type == STRING”, donde field_type es un único valor de tipo.

Ejemplos

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

frozenset ampliado para la comparación de tipos de DB-API 2.0.

Esta clase amplía frozenset para admitir la semántica de comparación de tipos de DB-API 2.0. Permite una verificación de tipos flexible, en la que los elementos individuales pueden compararse con el conjunto mediante operadores de igualdad y desigualdad.

Se utiliza para constantes de tipo como STRING, BINARY, NUMBER, etc., lo que permite comparaciones como “field_type == STRING”, donde field_type es un único valor de tipo.

Ejemplos

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

frozenset ampliado para la comparación de tipos de DB-API 2.0.

Esta clase amplía frozenset para admitir la semántica de comparación de tipos de DB-API 2.0. Permite una verificación de tipos flexible en la que los elementos individuales pueden compararse con el conjunto mediante operadores de igualdad y de desigualdad.

Se usa para constantes de tipo como STRING, BINARY, NUMBER, etc., para permitir comparaciones como “field_type == STRING”, donde field_type es un único valor de tipo.

Ejemplos

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

frozenset ampliado para la comparación de tipos en DB-API 2.0.

Esta clase amplía frozenset para admitir la semántica de comparación de tipos de DB-API 2.0. Permite una verificación de tipos flexible en la que los elementos individuales pueden compararse con el conjunto mediante operadores de igualdad y de desigualdad.

Se utiliza para constantes de tipo como STRING, BINARY, NUMBER, etc., lo que permite comparaciones como “field_type == STRING”, donde field_type es un único valor de tipo.

Ejemplos

>>> 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

Ejemplos de uso

Ejemplo 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()

Trabajar con datos:

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()

Gestión de conexiones:

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()

Buenas prácticas

1. Gestión de conexiones: Cierre siempre las conexiones y los cursores al terminar
2. Administradores de contexto: Use bloques with para una limpieza automática
3. Procesamiento por lotes: Use fetchmany() para conjuntos de resultados grandes
4. Manejo de errores: Encapsule las operaciones de base de datos en bloques try-except
5. Vinculación de parámetros: Use consultas parametrizadas siempre que sea posible
6. Gestión de memoria: Evite fetchall() con conjuntos de datos muy grandes

chDB admite UDF nativas de Python que se ejecutan en el mismo proceso, con argumentos tipados, inferencia automática de tipos y manejo configurable de NULL y excepciones. Las funciones de Python registradas como UDF pueden invocarse directamente desde consultas SQL.

Los ejemplos siguientes usan el formato de salida CSV predeterminado. Los comentarios en línea muestran los valores lógicos de los resultados; la salida sin procesar representa NULL como \N y aplica comillas de CSV a los valores de cadena y fecha.

Registra una función de Python como función SQL de chDB.

Sintaxis

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

Parámetros

Cada parámetro de tipo (los elementos de arg_types y return_type) acepta:

• Una constante ChdbType: INT64, STRING, FLOAT64, etc.
• Una cadena de tipo de ClickHouse: "Int64", "String", "DateTime64(6)", "DateTime('UTC')", etc.
• Un tipo de Python: int, float, str, bool, bytes, datetime.date, datetime.datetime — asignado según la correspondencia automática de tipos

Registrar un nombre ya registrado genera un error; las UDFs no se reemplazan silenciosamente. Llame primero a drop_function para volver a registrar una función.

Ejemplo

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

Elimina una UDF de Python registrada previamente. No hace nada si la función no está registrada, por lo que se puede llamar sin condiciones.

Sintaxis

chdb.drop_function(name)

Parámetros

Decorador para registrar una función de Python como función SQL de chDB. La función sigue pudiendo llamarse como una función de Python normal y, al mismo tiempo, está disponible en consultas SQL con su __name__.

Sintaxis

from chdb import func

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

Parámetros

Los mismos que create_function, excepto name y func, que se derivan de la función decorada.

Ejemplos

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!

Importa los tipos desde 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,
)

Cuando los tipos se infieren a partir de anotaciones de Python, se utiliza la siguiente correspondencia:

Los tipos se pueden especificar de varias formas:

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

Controla cómo se tratan los valores NULL mediante el 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

Controla cómo se gestionan las excepciones con el 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

Las UDF admiten plenamente los tipos Date, Date32, DateTime y DateTime64 con compatibilidad con zonas horarias.

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

• Los valores DateTime/DateTime64 de entrada de ClickHouse se convierten en objetos datetime de Python con información de zona horaria
• Los objetos datetime de Python de salida conservan la información de zona horaria al devolverse a ClickHouse
• El tipo DATETIME64 de chdb.sqltypes usa de forma predeterminada la escala 6 (microsegundos), equivalente a DateTime64(6)

Decorador para UDF (función definida por el usuario) de Python en chDB.

Sintaxis

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

Parámetros

Notas

1. La función debe ser sin estado. Solo se admiten UDFs, no UDAFs.
2. El tipo de retorno predeterminado es String. El tipo de retorno debe ser uno de los tipos de datos de ClickHouse.
3. La función debe aceptar argumentos de tipo String. Todos los argumentos son cadenas.
4. La función se llamará para cada línea de entrada.
5. La función debe ser una función de Python pura. Importe todos los módulos utilizados EN LA FUNCIÓN.
6. El intérprete de Python utilizado es el mismo que se usa para ejecutar el script.

Ejemplo

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

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

Genera archivos de configuración de UDF y scripts ejecutables.

Esta función crea los archivos necesarios para una función definida por el usuario (UDF) en chDB:

1. Un script ejecutable en Python que procesa los datos de entrada
2. Un archivo de configuración XML que registra la UDF en ClickHouse

Sintaxis

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

Parámetros

Funciones utilitarias y herramientas auxiliares para chDB.

Este módulo contiene varias funciones utilitarias para trabajar con chDB, incluidas la inferencia de tipos de datos, las herramientas de conversión de datos y las utilidades de depuración.

Convierte una lista de diccionarios a un formato columnar.

Esta función toma una lista de diccionarios y la transforma en un diccionario en el que cada clave corresponde a una columna y cada valor es una lista de valores de esa columna. Los valores ausentes en los diccionarios se representan como None.

Sintaxis

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

Parámetros

Devuelve

Ejemplo

>>> 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']
}

Aplana un diccionario anidado.

Esta función toma un diccionario anidado y lo aplana, concatenando las claves anidadas con un separador. Las listas de diccionarios se serializan como cadenas JSON.

Sintaxis

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

Parámetros

Devuelve

Ejemplo

>>> 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}]'
}

Infiere el tipo de dato más adecuado para una lista de valores.

Esta función examina una lista de valores y determina el tipo de dato más apropiado para representar todos los valores de la lista. Tiene en cuenta tipos enteros, enteros sin signo, decimales y de coma flotante, y usa “string” de forma predeterminada si los valores no pueden representarse con ningún tipo numérico o si todos los valores son None.

Sintaxis

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

Parámetros

Devuelve

Infiere los tipos de datos de cada columna en una estructura de datos columnar.

Esta función analiza los valores de cada columna e infiere el tipo de dato más adecuado para cada una, a partir de una muestra de los datos.

Sintaxis

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

Parámetros

Devuelve

Bases: ABC

class chdb.rwabc.PyReader(data: Any)

Lee un número determinado de filas de las columnas dadas y devuelve una lista de objetos, donde cada objeto es una secuencia de valores correspondiente a una columna.

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

Parámetros

Returns

Bases: ABC

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

Reúne y devuelve los datos finales a partir de bloques. Debe ser implementado por las subclases.

abstractmethod finalize() → bytes

Devuelve

Guarda columnas de datos en bloques. Las subclases deben implementarlo.

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

Parámetros

Bases: Exception

Clase base de excepción para errores relacionados con chDB.

Esta excepción se produce cuando falla la ejecución de una consulta de chDB o se produce un error. Hereda de la clase Exception estándar de Python y proporciona información sobre el error del motor de ClickHouse subyacente.

El mensaje de la excepción suele contener información detallada del error de ClickHouse, incluidos errores de sintaxis, incompatibilidades de tipos, ausencia de tablas o columnas y otros problemas de ejecución de consultas.

Variables

Ejemplos

>>> 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'

Secuencia inmutable incorporada.

Si no se proporciona ningún argumento, el constructor devuelve una tupla vacía. Si se especifica iterable, la tupla se inicializa a partir de sus elementos.

Si el argumento es una tupla, el valor devuelto es el mismo objeto.

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

Crea un nuevo objeto de cadena a partir del objeto dado. Si se especifican encoding o errors, el objeto debe exponer un búfer de datos que se decodificará con la codificación y el gestor de errores indicados. De lo contrario, devuelve el resultado de object._str_() (si está definido) o repr(object).