Référence de l’API Python de chDB

Exécute une requête SQL à l’aide du moteur chDB.

Il s’agit de la principale fonction de requête, qui exécute des instructions SQL à l’aide du moteur ClickHouse embarqué. Elle prend en charge divers formats de sortie et peut fonctionner avec des bases de données temporaires ou sur fichier.

Syntaxe

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

Paramètres

Renvoie

Renvoie le résultat de la requête dans le format spécifié :

Lève

Exemples

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

Exécute une requête SQL à l’aide du moteur chDB.

Il s’agit de la principale fonction de requête, qui exécute des instructions SQL à l’aide du moteur ClickHouse embarqué. Elle prend en charge divers formats de sortie et peut fonctionner avec des bases de données temporaires ou sur fichier.

Syntaxe

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

Paramètres

Renvoie

Renvoie le résultat de la requête dans le format spécifié :

Lève

Exemples

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

Convertit le résultat de la requête en PyArrow Table.

Convertit le résultat d’une requête chDB en PyArrow Table pour un traitement efficace des données au format colonnaire. Renvoie une table vide si le résultat est vide.

Syntaxe

chdb.to_arrowTable(res)

Paramètres

Renvoie

Lève

Exemple

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

Convertit le résultat d’une requête en DataFrame Pandas.

Convertit le résultat d’une requête chDB en DataFrame Pandas, en le convertissant d’abord en PyArrow Table, puis en DataFrame Pandas à l’aide du multithreading pour de meilleures performances.

Syntaxe

chdb.to_df(r)

Paramètres

Renvoie

Lève

Exemple

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

Les fonctions de session suivantes sont disponibles :

Crée une connexion au serveur d’arrière-plan de chDB.

Cette fonction établit une connexion au moteur de base de données chDB (ClickHouse). Chaque appel renvoie une connexion indépendante, et autant de connexions que nécessaire au même chemin de base de données peuvent être ouvertes simultanément.

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

Paramètres :

Formats de base

Avec paramètres de requête

Gestion des paramètres de requête

Les paramètres de requête sont transmis au moteur ClickHouse comme arguments de démarrage. Gestion spéciale des paramètres :

Pour obtenir la liste complète des paramètres, consultez clickhouse local --help --verbose

Renvoie

Lève

Exemples

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

Voir aussi

• Connection - Classe de connexion à une base de données
• Cursor - Curseur de base de données pour les opérations DB-API 2.0

Bases: Exception

Classe d’exception de base pour les erreurs liées à chDB.

Cette exception est levée lorsque l’exécution d’une requête chDB échoue ou rencontre une erreur. Elle hérite de la classe Python Exception standard et fournit des informations sur l’erreur provenant du moteur ClickHouse sous-jacent.

Bases : object

La session conserve l’état de la requête. Si path vaut None, la session utilise la base de données temporaire (:memory:) à l’échelle du processus, de sorte que toutes les sessions sans path voient les tables les unes des autres ; son répertoire temporaire n’est supprimé que lorsque la dernière session ou connexion de ce type est fermée. Vous pouvez également fournir un path pour créer une base de données à cet emplacement, où vos données seront conservées.

Vous pouvez aussi utiliser une chaîne de connexion pour transmettre le path et d’autres paramètres.

class chdb.session.Session(path=None)

Exemples

Nettoie les ressources de la session en gérant les exceptions.

Cette méthode tente de fermer la session tout en ignorant les exceptions susceptibles de survenir pendant le processus de nettoyage. Elle est particulièrement utile dans les scénarios de gestion des erreurs ou lorsque vous devez vous assurer que le nettoyage a bien lieu, quel que soit l’état de la session.

Syntaxe

cleanup()

Exemples

>>> session = Session("test.db")
>>> try:
...     session.query("INVALID SQL")
... finally:
...     session.cleanup()  # Safe cleanup regardless of errors

Voir aussi

• close() - Pour fermer explicitement la session avec propagation des erreurs

Ferme la session et libère les ressources.

Cette méthode ferme la connexion sous-jacente et réinitialise l’état global de la session. Après l’appel de cette méthode, la session n’est plus valide et ne peut pas être utilisée pour d’autres requêtes.

Syntaxe

close()

Exemples

>>> session = Session("test.db")
>>> session.query("SELECT 1")
>>> session.close()  # Explicitly close the session

Exécute une requête SQL et renvoie les résultats.

Cette méthode exécute une requête SQL sur la base de données de la session et renvoie les résultats au format spécifié. Elle prend en charge divers formats de sortie et conserve l’état de la session entre les requêtes.

Syntaxe

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

Paramètres

Renvoie

Renvoie les résultats de la requête dans le format spécifié. Le type de retour exact dépend du paramètre format :

• Les formats texte (CSV, JSON, etc.) renvoient une valeur str
• Les formats binaires (Arrow, Parquet) renvoient une valeur bytes

Lève

Exemples

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

Voir aussi

• send_query() - Pour l’exécution de requête en streaming
• sql - Alias de cette méthode

Exécute une requête SQL et renvoie un itérateur de résultats en streaming.

Cette méthode exécute une requête SQL sur la base de données de la session et renvoie un objet de résultat en streaming qui vous permet de parcourir les résultats sans tout charger en mémoire d’un seul coup. Cela est particulièrement utile pour les grands jeux de résultats.

Syntaxe

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

Paramètres

Renvoie

Exceptions levées

Exemples

>>> session = Session("test.db")
>>> session.query("CREATE TABLE big_table (id INT, data String) ENGINE = MergeTree() order by id")
>>>
>>> # Insert large dataset
>>> for i in range(1000):
...     session.query(f"INSERT INTO big_table VALUES ({i}, 'data_{i}')")
>>>
>>> # Stream results to avoid memory issues
>>> streaming_result = session.send_query("SELECT * FROM big_table ORDER BY id")
>>> for chunk in streaming_result:
...     print(f"Processing chunk: {len(chunk)} bytes")
...     # Process chunk without loading entire result set

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

Voir aussi

• query() - Pour exécuter des requêtes non streaming
• chdb.state.sqlitelike.StreamingResult - Itérateur de résultats en streaming

Exécute une requête SQL et renvoie les résultats.

Cette méthode exécute une requête SQL sur la base de données de la session et renvoie les résultats au format spécifié. Elle prend en charge différents formats de sortie et conserve l’état de la session entre les requêtes.

Syntaxe

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

Paramètres

Retourne

Retourne les résultats de la requête dans le format spécifié. Le type de retour exact dépend du paramètre de format :

• Les formats texte (CSV, JSON, etc.) renvoient str
• Les formats binaires (Arrow, Parquet) renvoient bytes

Lève :

Exemples

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

Voir aussi

• send_query() - Pour l'exécution d'une requête en streaming
• sql - Alias de cette méthode

Crée une Connection vers le serveur d’arrière-plan de chDB.

Cette fonction établit une connexion avec le moteur de base de données chDB (ClickHouse). Chaque appel renvoie une connexion indépendante, et plusieurs connexions vers le même chemin de base de données peuvent être ouvertes simultanément.

Syntaxe

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

Paramètres

Formats de base

Formats de chaîne de connexion pris en charge :

Avec paramètres de requête

Gestion des paramètres de requête

Les paramètres de requête sont transmis au moteur ClickHouse comme arguments de démarrage. Gestion spéciale des paramètres :

Pour obtenir la liste complète des paramètres, consultez clickhouse local --help --verbose

Renvoie

Lève

Exemples

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

Voir aussi

• Connection - Classe de connexion à la base de données
• Cursor - Curseur de base de données pour les opérations de DB-API 2.0

Bases : object

Syntaxe

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

Ferme la connexion et libère les ressources.

Cette méthode ferme la connexion à la base de données et libère toutes les ressources associées, y compris les curseurs actifs. Après l’appel de cette méthode, la connexion devient invalide et ne peut plus être utilisée pour d’autres opérations.

Syntaxe

close() → None

Exemples

>>> conn = connect("test.db")
>>> # Use connection for queries
>>> conn.query("CREATE TABLE test (id INT) ENGINE = Memory")
>>> # Close when done
>>> conn.close()

>>> # Using with context manager (automatic cleanup)
>>> with connect("test.db") as conn:
...     conn.query("SELECT 1")
...     # Connection automatically closed

Crée un objet Cursor pour exécuter des requêtes.

Cette méthode crée un curseur de base de données qui fournit l’interface DB-API 2.0 standard pour exécuter des requêtes et récupérer les résultats. Le curseur permet de contrôler finement l’exécution des requêtes et la récupération des résultats.

Syntaxe

cursor() → Cursor

Retourne

Exemples

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

Voir aussi

• Cursor - Implémentation d’un curseur de base de données

Exécute une requête SQL et renvoie l’intégralité des résultats.

Cette méthode exécute une requête SQL de manière synchrone et renvoie l’ensemble des résultats. Elle prend en charge différents formats de sortie et applique automatiquement un post-traitement propre à chaque format.

Syntaxe

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

Paramètres :

Renvoie

Lève

Exemples

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

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

Voir aussi

• send_query() - Pour exécuter des requêtes en streaming

Exécute une requête SQL et renvoie un itérateur de résultats en continu.

Cette méthode exécute une requête SQL et renvoie un objet StreamingResult qui vous permet de parcourir les résultats sans tout charger en mémoire d’un seul coup. C’est idéal pour traiter de grands jeux de résultats.

Syntaxe

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

Paramètres

Retourne

Lève

Exemples

>>> conn = connect(":memory:")
>>>
>>> # Basic streaming
>>> stream = conn.send_query("SELECT number FROM numbers(1000)")
>>> for chunk in stream:
...     print(f"Processing chunk: {len(chunk)} bytes")

>>> # Using context manager for cleanup
>>> with conn.send_query("SELECT * FROM large_table") as stream:
...     chunk = stream.fetch()
...     while chunk:
...         process_data(chunk)
...         chunk = stream.fetch()

>>> # Arrow format with RecordBatch streaming
>>> 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}")

Voir aussi

• query() - Pour l'exécution de requêtes sans streaming
• StreamingResult - Itérateur de résultats en streaming

Bases : object

Itérateur de résultats en streaming pour traiter de grands résultats de requête.

Cette classe fournit une interface d’itérateur pour exploiter des résultats de requête en streaming sans charger l’ensemble du jeu de résultats en mémoire. Elle prend en charge divers formats de sortie et fournit des méthodes pour récupérer manuellement les résultats ainsi que pour le streaming de RecordBatch PyArrow.

class chdb.state.sqlitelike.StreamingResult

Récupère le fragment suivant des résultats en streaming.

Cette méthode récupère le prochain fragment de données disponible dans le résultat de la requête en streaming. Le format des données renvoyées dépend du format spécifié lors du lancement de la requête en streaming.

Syntaxe

fetch() → Any

Retourne

Exemples

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

Annule la requête en streaming et libère les ressources.

Cette méthode annule toute requête en streaming en cours et libère les ressources associées. Elle doit être appelée lorsque vous souhaitez arrêter le traitement des résultats avant que le flux ne soit entièrement consommé.

Syntaxe

cancel() → None

Exemples

>>> stream = conn.send_query("SELECT * FROM very_large_table")
>>> for i, chunk in enumerate(stream):
...     if i >= 10:  # Only process first 10 chunks
...         stream.cancel()
...         break
...     process_data(chunk)

Ferme le résultat en streaming et libère les ressources.

Alias de cancel(). Ferme l’itérateur du résultat en streaming et libère les ressources associées.

Syntaxe

close() → None

Crée un PyArrow RecordBatchReader pour un traitement par lots efficace.

Cette méthode crée un PyArrow RecordBatchReader qui permet d’itérer efficacement sur les résultats de la requête au format Arrow. C’est la manière la plus efficace de traiter de grands jeux de résultats avec PyArrow.

Syntaxe

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

Paramètres

Valeur de retour

Exemples

>>> 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 prend en charge le protocole des itérateurs de Python, ce qui permet de l’utiliser directement dans des boucles for :

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

StreamingResult prend en charge le protocole des gestionnaires de contexte pour le nettoyage automatique des ressources :

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

Bases : object

class chdb.state.sqlitelike.Cursor(connection)

Fermer le curseur et libérer les ressources.

Cette méthode ferme le curseur et libère toutes les ressources associées. Après l’appel de cette méthode, le curseur devient invalide et ne peut plus être utilisé pour d’autres opérations.

Syntaxe

close() → None

Exemples

>>> cursor = conn.cursor()
>>> cursor.execute("SELECT 1")
>>> result = cursor.fetchone()
>>> cursor.close()  # Cleanup cursor resources

Renvoie la liste des noms de colonnes de la dernière requête exécutée.

Cette méthode renvoie les noms de colonnes de la requête SELECT exécutée le plus récemment. Les noms sont renvoyés dans le même ordre que dans le jeu de résultats.

Syntaxe

column_names() → list

Retourne

Exemples

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

Voir aussi

• column_types() - Obtenir des informations sur les types de colonne
• description - Description de colonne de la DB-API 2.0

Renvoie une liste des types de colonnes de la dernière requête exécutée.

Cette méthode renvoie les noms des types de colonnes ClickHouse de la requête SELECT exécutée le plus récemment. Les types sont renvoyés dans le même ordre que dans le jeu de résultats.

Syntaxe

column_types() → list

Renvoie

Exemples

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

Voir aussi

• column_names() - Obtenir des informations sur les noms des colonnes
• description - Description des colonnes DB-API 2.0

Valide toute transaction en attente.

Cette méthode valide toute transaction de base de données en attente. Dans ClickHouse, la plupart des opérations sont validées automatiquement, mais cette méthode est fournie pour assurer la compatibilité avec DB-API 2.0.

Syntaxe

commit() → None

Exemples

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

Renvoie la description des colonnes conformément à la spécification DB-API 2.0.

Cette propriété renvoie une liste de tuples à 7 éléments décrivant chaque colonne du jeu de résultats de la dernière requête SELECT exécutée. Chaque tuple contient : (name, type_code, display_size, internal_size, precision, scale, null_ok)

Actuellement, seuls name et type_code sont fournis, les autres champs étant définis sur None.

Renvoie

Exemples

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

Voir aussi

• column_names() - Obtenir uniquement les noms de colonnes
• column_types() - Obtenir uniquement les types de colonnes

Exécute une requête SQL et prépare les résultats pour pouvoir les récupérer.

Cette méthode exécute une requête SQL et prépare les résultats pour leur récupération à l’aide des méthodes fetch. Elle gère l’analyse des données de résultat et la conversion automatique vers les types de données ClickHouse.

Syntaxe

execute(query: str) → None

Paramètres :

Lève

Exemples

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

Voir aussi

• fetchone() - Récupère une seule ligne
• fetchmany() - Récupère plusieurs lignes
• fetchall() - Récupère toutes les lignes restantes

Récupère toutes les lignes restantes du résultat de la requête.

Cette méthode récupère toutes les lignes restantes de l’ensemble de résultats de la requête à partir de la position actuelle du curseur. Elle renvoie un tuple de tuples de lignes, avec la conversion appropriée des types Python.

Syntaxe

fetchall() → tuple

Renvoie :

Exemples

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

Voir aussi

• fetchone() - Récupérer une seule ligne
• fetchmany() - Récupérer plusieurs lignes par lots

Récupère plusieurs lignes du résultat de la requête.

Cette méthode récupère jusqu'à « size » lignes de l'ensemble de résultats de la requête en cours. Elle renvoie un tuple de tuples, chaque ligne contenant des valeurs de colonne avec la conversion appropriée vers le type Python.

Syntaxe

fetchmany(size: int = 1) → tuple

Paramètres

Renvoie

Exemples

>>> cursor = conn.cursor()
>>> cursor.execute("SELECT * FROM large_table")
>>>
>>> # Process results in batches
>>> while True:
...     batch = cursor.fetchmany(100)  # Fetch 100 rows at a time
...     if not batch:
...         break
...     process_batch(batch)

Voir aussi

• fetchone() - Récupérer une seule ligne
• fetchall() - Récupérer toutes les lignes restantes

Récupère la ligne suivante dans le résultat de la requête.

Cette méthode récupère la prochaine ligne disponible dans le jeu de résultats de la requête en cours. Elle renvoie un tuple contenant les valeurs des colonnes, avec la conversion appropriée vers les types Python.

Syntaxe

fetchone() → tuple | None

Renvoie :

Exemples

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

Voir aussi

• fetchmany() - Récupérer plusieurs lignes
• fetchall() - Récupérer toutes les lignes restantes

Convertit le résultat de la requête en table PyArrow.

Cette fonction convertit les résultats des requêtes chdb au format de table PyArrow, offrant un accès efficace aux données en format colonnaire ainsi qu'une interopérabilité avec d'autres bibliothèques de traitement de données.

Syntaxe

chdb.state.sqlitelike.to_arrowTable(res)

Paramètres :

Renvoie

Génère

Exemples

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

Convertit le résultat de la requête en Pandas DataFrame.

Cette fonction convertit les résultats de query chdb au format Pandas DataFrame en les transformant d'abord en table PyArrow, puis en DataFrame. Elle offre ainsi des capacités pratiques d'analyse de données avec l'API Pandas.

Syntaxe

chdb.state.sqlitelike.to_df(r)

Paramètres :

Renvoie :

Lève

Voir aussi

• to_arrowTable() - Pour la conversion au format table PyArrow

Exemples

>>> 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 fournit une interface Python compatible avec DB-API 2.0 pour se connecter à des bases de données, ce qui vous permet d’utiliser chDB avec des outils et des frameworks qui s’appuient sur des interfaces de base de données standard.

L’interface chDB DB-API 2.0 comprend :

• Connexions : gestion des connexions aux bases de données via des chaînes de connexion
• Curseurs : exécution des requêtes et récupération des résultats
• Système de types : constantes de type et convertisseurs conformes à DB-API 2.0
• Gestion des erreurs : hiérarchie standard des exceptions de base de données
• Sécurité des threads : niveau 1 de sécurité des threads (les threads peuvent partager des modules, mais pas des connexions)

L’interface DB-API 2.0 (DBAPI) implémente les principales fonctions suivantes :

Initialise une nouvelle connexion à une base de données.

Syntaxe

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

Paramètres

Exceptions levées

Récupère les informations de version du client.

Renvoie la version du client chDB sous forme de chaîne de caractères, pour assurer la compatibilité avec MySQLdb.

Syntaxe

chdb.dbapi.get_client_info()

Renvoie

Renvoie x sous forme de type binaire.

Cette fonction convertit l’entrée en type bytes afin de l’utiliser avec des champs binaires de la base de données, conformément à la spécification DB-API 2.0.

Syntaxe

chdb.dbapi.Binary(x)

Paramètres

Retourne

Bases : object

Connexion à la base de données chDB conforme à DB-API 2.0.

Cette classe fournit une interface DB-API standard permettant de se connecter aux bases de données chDB et d’interagir avec elles. Elle prend en charge les bases de données temporaires et sur fichier.

La connexion gère le moteur chDB sous-jacent et fournit des méthodes pour exécuter des requêtes, gérer les transactions (sans effet pour ClickHouse) et créer des curseurs.

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

Paramètres

Variables

Exemples

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

Ferme la connexion à la base de données.

Ferme la connexion chDB sous-jacente et marque cette connexion comme fermée. Les opérations ultérieures sur cette connexion généreront une erreur.

Syntaxe

close()

Lève

Valide la transaction en cours.

Syntaxe

commit()

Créer un nouveau curseur pour exécuter des requêtes.

Syntaxe

cursor(cursor=None)

Paramètres

Retourne

Lève

Exemple

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

Échapper une valeur pour l’inclure en toute sécurité dans des requêtes SQL.

Syntaxe

escape(obj, mapping=None)

Paramètres

Retourne

Exemple

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

Échappe une chaîne de caractères pour les requêtes SQL.

Syntaxe

escape_string(s)

Paramètres

Renvoie

Vérifie si la connexion est ouverte.

Renvoie

Exécute directement une requête SQL et renvoie les résultats bruts.

Cette méthode contourne l’interface de curseur et exécute les requêtes directement. Pour une utilisation standard de la DB-API, privilégiez la méthode cursor().

Syntaxe

query(sql, fmt='CSV')

Paramètres :

Renvoie

Lève

Exemple

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

Renvoie la réponse à la dernière requête.

Renvoie

Annule la transaction en cours.

Syntaxe

rollback()

Bases : object

Curseur DB-API 2.0 permettant d’exécuter des requêtes et de récupérer les résultats.

Le curseur fournit des méthodes pour exécuter des instructions SQL, gérer les résultats des requêtes, et naviguer dans les jeux de résultats. Il prend en charge la liaison de paramètres, les opérations en lot, et respecte les spécifications DB-API 2.0.

Ne créez pas directement d’instances de Cursor. Utilisez plutôt Connection.cursor().

class chdb.dbapi.cursors.Cursor(connection)

Exemples

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

Exécute une procédure stockée (implémentation factice).

Syntaxe

callproc(procname, args=())

Paramètres

Retourne

Ferme le curseur et libère les ressources associées.

Après sa fermeture, le curseur devient inutilisable et toute opération provoquera une exception. La fermeture d’un curseur lit toutes les données restantes et libère le curseur sous-jacent.

Syntaxe

close()

Exécute une requête SQL avec liaison facultative de paramètres.

Cette méthode exécute une seule instruction SQL avec substitution facultative de paramètres. Elle prend en charge plusieurs formats d’espaces réservés pour les paramètres, pour plus de souplesse.

Syntaxe

execute(query, args=None)

Paramètres

Valeur de retour

Styles de paramètres

Exemples

>>> # Question mark parameters
>>> cur.execute("SELECT * FROM users WHERE id = ? AND age > ?", (123, 18))
>>>
>>> # Named parameters
>>> cur.execute("SELECT * FROM users WHERE name = %(name)s", {'name': 'Alice'})
>>>
>>> # No parameters
>>> cur.execute("SELECT COUNT(*) FROM users")

Lève

Exécute une requête plusieurs fois avec différents jeux de paramètres.

Cette méthode exécute efficacement la même requête SQL à plusieurs reprises avec des valeurs de paramètres différentes. Elle est particulièrement utile pour les opérations INSERT en lot.

Syntaxe

executemany(query, args)

Paramètres

Renvoie

Exemples

>>> # Bulk insert with question mark parameters
>>> users_data = [(1, 'Alice'), (2, 'Bob'), (3, 'Charlie')]
>>> cur.executemany("INSERT INTO users VALUES (?, ?)", users_data)
>>>
>>> # Bulk insert with named parameters
>>> users_data = [
...     {'id': 1, 'name': 'Alice'},
...     {'id': 2, 'name': 'Bob'}
... ]
>>> cur.executemany(
...     "INSERT INTO users VALUES (%(id)s, %(name)s)",
...     users_data
... )

Récupère toutes les lignes restantes du résultat de la requête.

Syntaxe

fetchall()

Renvoie

Lève

Exemple

>>> cursor.execute("SELECT id, name FROM users")
>>> all_rows = cursor.fetchall()
>>> print(len(all_rows))  # Number of total rows

Récupère plusieurs lignes dans le résultat de la requête.

Syntaxe

fetchmany(size=1)

Paramètres

Retourne

Lève

Exemple

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

Récupère la ligne suivante du résultat de la requête.

Syntaxe

fetchone()

Renvoie

Lève

Exemple

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

Taille maximale de l’instruction que executemany() génère.

La valeur par défaut est 1024000.

Renvoie la chaîne de requête exacte qui serait envoyée à la base de données.

Cette méthode affiche la requête SQL finale après substitution des paramètres, ce qui est utile pour le débogage et la journalisation.

Syntaxe

mogrify(query, args=None)

Paramètres

Retourne

Exemple

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

Passe au jeu de résultats suivant (fonction non prise en charge).

Syntaxe

nextset()

Renvoie

Définit la taille des entrées pour les paramètres (implémentation no-op).

Syntaxe

setinputsizes(*args)

Paramètres

Définit la taille des colonnes de sortie (implémentation no-op).

Syntaxe

setoutputsizes(*args)

Paramètres

Classes d’exception pour les opérations de base de données de chdb.

Ce module fournit une hiérarchie complète de classes d’exception pour la gestion des erreurs liées aux bases de données dans chdb, conformément à la spécification Python Database API v2.0.

La hiérarchie des exceptions est structurée comme suit :

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

Chaque classe d’exception représente une catégorie spécifique d’erreurs de base de données :

Voir aussi

• Spécification Python Database API v2.0
• chdb.dbapi.connections - Gestion des connexions à la base de données
• chdb.dbapi.cursors - Opérations sur les curseurs de base de données

Exemples

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

Exception levée pour les erreurs dues à des problèmes liés aux données traitées.

Cette exception est levée lorsque des opérations de base de données échouent en raison de problèmes affectant les données en cours de traitement, par exemple :

• Division par zéro
• Valeurs numériques hors plage
• Valeurs de date/heure non valides
• Erreurs de troncature de chaîne
• Échecs de conversion de type
• Format de données non valide pour le type de colonne

Exceptions levées

Exemples

>>> # Division by zero in SQL
>>> cursor.execute("SELECT 1/0")
DataError: Division by zero

>>> # Invalid date format
>>> cursor.execute("INSERT INTO table VALUES ('invalid-date')")
DataError: Invalid date format

Bases : Error

Exception levée en cas d’erreurs liées à la base de données.

Il s’agit de la classe de base de toutes les erreurs liées à la base de données. Elle couvre toutes les erreurs survenant lors d’opérations sur la base de données et qui concernent la base de données elle-même plutôt que l’interface.

Les cas courants incluent :

• Erreurs d’exécution SQL
• Problèmes de connectivité à la base de données
• Problèmes liés aux transactions
• Violations de contraintes propres à la base de données

Bases : StandardError

Exception qui constitue la classe de base de toutes les autres exceptions d’erreur (à l’exclusion de Warning).

Il s’agit de la classe de base de toutes les exceptions d’erreur dans chdb, à l’exclusion des avertissements. Elle sert de classe parente à toutes les erreurs de base de données qui empêchent l’exécution correcte des opérations.

Voir aussi

• Warning - Pour les avertissements non fatals qui n’empêchent pas l’exécution d’une opération jusqu’à son terme

Bases: DatabaseError

Exception levée lorsque l'intégrité relationnelle de la base de données est compromise.

Cette exception est levée lorsque des opérations sur la base de données enfreignent des contraintes d'intégrité, notamment :

• Violations de contraintes de clé étrangère
• Violations de clé primaire ou de contrainte d'unicité (clés dupliquées)
• Violations de contraintes CHECK
• Violations de contraintes NOT NULL
• Violations de l'intégrité référentielle

Levée

Exemples

>>> # Duplicate primary key
>>> 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'

>>> # Foreign key violation
>>> cursor.execute("INSERT INTO orders (user_id) VALUES (999)")
IntegrityError: Cannot add or update a child row: foreign key constraint fails

Bases : Error

Exception levée pour les erreurs liées à l’interface de la base de données plutôt qu’à la base de données elle-même.

Cette exception est levée en cas de problèmes dans l’implémentation de l’interface de la base de données, par exemple :

• Paramètres de connexion non valides
• Mauvaise utilisation de l’API (appel de méthodes sur des connexions fermées)
• Erreurs de protocole au niveau de l’interface
• Échecs d’importation ou d’initialisation du module

Levées

Bases : DatabaseError

Exception levée lorsque la base de données rencontre une erreur interne.

Cette exception est levée lorsque le système de base de données rencontre des erreurs internes qui ne sont pas dues à l'application, par exemple :

• État de curseur invalide (le curseur n'est plus valide)
• Incohérences dans l'état de la transaction (la transaction n'est plus synchronisée)
• Problèmes de corruption de la base de données
• Corruption de la structure de données interne
• Erreurs de base de données au niveau du système

Lève

Bases: DatabaseError

Exception levée lorsqu'une méthode ou l'API de base de données n'est pas prise en charge.

Cette exception est levée lorsque l'application tente d'utiliser des fonctionnalités de la base de données ou des méthodes d'API qui ne sont pas prises en charge par la configuration ou la version actuelles de la base de données, par exemple :

• Appel de rollback() sur des connexions qui ne prennent pas en charge les transactions
• Utilisation de fonctionnalités SQL avancées non prises en charge par la version de la base de données
• Appel de méthodes non implémentées par le driver actuel
• Tentative d'utiliser des fonctionnalités de la base de données désactivées

Lève

Exemples

>>> # Transaction rollback on non-transactional connection
>>> connection.rollback()
NotSupportedError: Transactions are not supported

>>> # Using unsupported SQL syntax
>>> cursor.execute("SELECT * FROM table WITH (NOLOCK)")
NotSupportedError: WITH clause not supported in this database version

Bases : DatabaseError

Exception levée pour les erreurs liées au fonctionnement de la base de données.

Cette exception est levée pour les erreurs qui surviennent lors du fonctionnement de la base de données et ne relèvent pas nécessairement du contrôle du développeur, notamment :

• Déconnexion inattendue de la base de données
• Serveur de base de données introuvable ou inaccessible
• Échecs du traitement des transactions
• Erreurs d’allocation de mémoire pendant le traitement
• Espace disque insuffisant ou épuisement des ressources
• Erreurs internes du serveur de base de données
• Échecs d’authentification ou d’autorisation

Lève

Bases : DatabaseError

Exception levée en cas d’erreurs de programmation dans les opérations sur la base de données.

Cette exception est levée lorsque l’utilisation de la base de données par l’application comporte des erreurs de programmation, notamment :

• Table ou colonne introuvable
• La table ou l’index existe déjà au moment de la création
• Erreurs de syntaxe SQL dans les instructions
• Nombre incorrect de paramètres spécifiés dans les instructions préparées
• Opérations SQL non valides (par ex., DROP sur des objets inexistants)
• Utilisation incorrecte des méthodes de l’API de base de données

Lève

Exemples

>>> # Table not found
>>> cursor.execute("SELECT * FROM nonexistent_table")
ProgrammingError: Table 'nonexistent_table' doesn't exist

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

>>> # Wrong parameter count
>>> cursor.execute("INSERT INTO users (name, age) VALUES (%s)", ('John',))
ProgrammingError: Column count doesn't match value count

Bases : Exception

Exception liée aux opérations avec chdb.

Il s'agit de la classe de base de toutes les exceptions liées à chdb. Elle hérite de la classe intégrée Exception de Python et constitue la racine de la hiérarchie des exceptions pour les opérations sur les bases de données.

Bases : StandardError

Exception levée pour signaler des avertissements importants, comme une troncature de données lors de l'insertion.

Cette exception est levée lorsque l'opération sur la base de données s'achève, mais s'accompagne d'avertissements importants qui doivent être portés à l'attention de l'application. Les cas courants incluent :

• Troncature de données lors de l'insertion
• Perte de précision lors de conversions numériques
• Avertissements liés à la conversion du jeu de caractères

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

Crée un nouvel objet de type chaîne à partir de l’objet donné. Si encoding ou errors est spécifié, l’objet doit alors exposer un tampon de données qui sera décodé à l’aide de l’encodage et du gestionnaire d’erreurs indiqués. Sinon, renvoie le résultat de object._\_str_\_() (s’il est défini) ou de repr(object).

• encoding vaut par défaut ‘utf-8’.
• errors vaut par défaut ‘strict’.

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

Convertit un nombre ou une chaîne en entier, ou renvoie 0 si aucun argument n’est fourni. Si x est un nombre, renvoie x._int_(). Pour les nombres à virgule flottante, la troncature se fait vers zéro.

Si x n’est pas un nombre ou si base est fourni, x doit être une chaîne, des bytes ou une instance de bytearray représentant un littéral entier dans la base indiquée. Le littéral peut être précédé de ‘+’ ou de ‘-’ et entouré d’espaces. La base par défaut est 10. Les bases valides sont 0 et 2-36. La base 0 signifie que la base est déduite de la chaîne comme pour un littéral entier.

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

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

Crée un nouvel objet de type chaîne à partir de l’objet donné. Si encoding ou errors est spécifié, l’objet doit alors exposer un buffer de données qui sera décodé à l’aide de l’encodage indiqué et du gestionnaire d’erreurs. Sinon, renvoie le résultat de object._str_() (s’il est défini) ou repr(object). encoding vaut par défaut ‘utf-8’. errors vaut par défaut ‘strict’.

frozenset étendu pour la comparaison de types DB-API 2.0.

Cette classe étend frozenset afin de prendre en charge la sémantique de comparaison des types de DB-API 2.0. Elle permet une vérification de type souple, dans lequel des éléments individuels peuvent être comparés à l’ensemble à l’aide des opérateurs d’égalité et d’inégalité.

Elle est utilisée pour des constantes de type telles que STRING, BINARY, NUMBER, etc., afin de permettre des comparaisons comme « field_type == STRING », où field_type est une valeur de type unique.

Exemples

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

frozenset étendu pour la comparaison des types DB-API 2.0.

Cette classe étend frozenset pour prendre en charge la sémantique de comparaison des types de DB-API 2.0. Elle permet une vérification de type souple, où des éléments individuels peuvent être comparés à l’ensemble à l’aide des opérateurs d’égalité et d’inégalité.

Cette classe est utilisée pour des constantes de type comme STRING, BINARY, NUMBER, etc., afin de permettre des comparaisons comme « field_type == STRING », où field_type est une valeur de type unique.

Exemples

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

frozenset étendu pour la comparaison de types DB-API 2.0.

Cette classe étend frozenset pour prendre en charge la sémantique de comparaison de types de DB-API 2.0. Elle permet une vérification de type flexible, dans laquelle des éléments individuels peuvent être comparés à l’ensemble à l’aide des opérateurs d’égalité et d’inégalité.

Ceci est utilisé pour des constantes de type comme STRING, BINARY, NUMBER, etc., afin de permettre des comparaisons comme “field_type == STRING”, où field_type est une valeur de type unique.

Exemples

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

frozenset étendu pour la comparaison des types DB-API 2.0.

Cette classe étend frozenset pour prendre en charge la sémantique de comparaison des types de DB-API 2.0. Elle permet une vérification de type souple, où des éléments individuels peuvent être comparés à l’ensemble à l’aide des opérateurs d’égalité et d’inégalité.

Il est utilisé pour des constantes de type comme STRING, BINARY, NUMBER, etc., afin de permettre des comparaisons comme « field_type == STRING », où field_type est une valeur de type unique.

Exemples

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

frozenset étendu pour la comparaison de types dans la DB-API 2.0.

Cette classe étend frozenset pour prendre en charge la sémantique de comparaison des types de la DB-API 2.0. Elle permet une vérification de type souple, où des éléments individuels peuvent être comparés à l'ensemble à l'aide des opérateurs d'égalité et d'inégalité.

Cette classe est utilisée pour des constantes de type comme STRING, BINARY, NUMBER, etc., afin de permettre des comparaisons telles que « field_type == STRING », où field_type est une valeur de type unique.

Exemples

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

frozenset étendu pour la comparaison de types DB-API 2.0.

Cette classe étend frozenset pour prendre en charge la sémantique de comparaison des types de DB-API 2.0. Elle permet une vérification de type plus souple, dans laquelle des éléments individuels peuvent être comparés à l’ensemble à l’aide des opérateurs d’égalité et d’inégalité.

Cette classe est utilisée pour des constantes de type comme STRING, BINARY, NUMBER, etc., afin de permettre des comparaisons comme « field_type == STRING », où field_type est une valeur de type unique.

Exemples

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

frozenset étendu pour la comparaison de types DB-API 2.0.

Cette classe étend frozenset pour prendre en charge la sémantique de comparaison des types de DB-API 2.0. Elle permet une vérification de type souple, où des éléments individuels peuvent être comparés à l’ensemble à l’aide des opérateurs d’égalité et d’inégalité.

Ce mécanisme est utilisé pour des constantes de type comme STRING, BINARY, NUMBER, etc., afin de permettre des comparaisons telles que « field_type == STRING », où field_type est une valeur de type unique.

Exemples

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

frozenset étendu pour la comparaison de types DB-API 2.0.

Cette classe étend frozenset pour prendre en charge la sémantique de comparaison des types de DB-API 2.0. Elle permet une vérification souple des types, où des éléments individuels peuvent être comparés à l’ensemble à l’aide des opérateurs d’égalité et d’inégalité.

Elle est utilisée pour des constantes de type telles que STRING, BINARY, NUMBER, etc., afin de permettre des comparaisons comme « field_type == STRING », où field_type est une valeur de type unique.

Exemples

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

Exemples d'utilisation

Exemple de requête de base :

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

Manipuler les données :

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

Gestion des connexions :

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

Bonnes pratiques

1. Gestion des connexions : fermez toujours les connexions et les curseurs une fois vos opérations terminées
2. Gestionnaires de contexte : utilisez des instructions with pour libérer automatiquement les ressources
3. Traitement par lots : utilisez fetchmany() pour les jeux de résultats volumineux
4. Gestion des erreurs : placez les opérations sur la base de données dans des blocs try-except
5. Liaison de paramètres : utilisez des requêtes paramétrées lorsque c’est possible
6. Gestion de la mémoire : évitez fetchall() pour les jeux de données très volumineux

chDB prend en charge les UDF Python natives qui s’exécutent dans le processus, avec des arguments typés, une inférence de type automatique et une gestion configurable des valeurs NULL et des exceptions. Les fonctions Python enregistrées comme UDF peuvent être appelées directement depuis des requêtes SQL.

Les exemples ci-dessous utilisent le format de sortie CSV par défaut. Les commentaires intégrés indiquent les valeurs de résultat logiques ; la sortie brute affiche NULL sous la forme \N et applique les règles de mise entre guillemets du format CSV aux valeurs de chaîne et de date.

Enregistre une fonction Python en tant que fonction SQL chDB.

Syntaxe

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

Paramètres

Chaque paramètre de type (éléments de arg_types et return_type) accepte :

• Une constante ChdbType : INT64, STRING, FLOAT64, etc.
• Une chaîne de type ClickHouse : "Int64", "String", "DateTime64(6)", "DateTime('UTC')", etc.
• Un type Python : int, float, str, bool, bytes, datetime.date, datetime.datetime — mappé conformément au mappage automatique des types

L’enregistrement d’un nom déjà enregistré génère une erreur : les UDFs ne sont pas remplacées silencieusement. Appelez d’abord drop_function pour réenregistrer une fonction.

Exemple

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

Supprime une UDF Python enregistrée précédemment. Ne fait rien si la fonction n’est pas enregistrée ; il est donc possible de l’appeler sans condition.

Syntaxe

chdb.drop_function(name)

Paramètres

Décorateur permettant d’enregistrer une fonction Python comme fonction SQL chDB. La fonction reste appelable comme une fonction Python ordinaire tout en étant disponible dans les requêtes SQL sous son __name__.

Syntaxe

from chdb import func

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

Paramètres

Les mêmes que pour create_function (à l’exception de name et func, qui sont dérivés de la fonction décorée).

Examples

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!

Importez les types depuis 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,
)

Lorsque les types sont déduits des annotations Python, le mappage suivant est utilisé :

Les types peuvent être définis de plusieurs façons :

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

Contrôlez le traitement des valeurs NULL à l’aide du paramètre 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

Contrôlez la gestion des exceptions à l’aide du paramètre 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

Les UDF prennent pleinement en charge les types Date, Date32, DateTime et DateTime64 avec prise en compte des fuseaux horaires.

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

• Les valeurs ClickHouse DateTime/DateTime64 fournies en entrée sont converties en objets Python datetime contenant les informations de fuseau horaire
• Les objets Python datetime renvoyés à ClickHouse conservent leurs informations de fuseau horaire
• Le type DATETIME64 de chdb.sqltypes utilise par défaut une échelle de 6 (microsecondes), ce qui équivaut à DateTime64(6)

Décorateur pour les UDF Python de chDB (fonctions définies par l’utilisateur).

Syntaxe

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

Paramètres

Notes

1. La fonction doit être sans état. Seules les UDF sont prises en charge, pas les UDAF.
2. Le type de retour par défaut est String. Le type de retour doit être l’un des types de données ClickHouse.
3. La fonction doit accepter des arguments de type String. Tous les arguments sont des chaînes de caractères.
4. La fonction sera appelée pour chaque ligne d’entrée.
5. La fonction doit être une fonction Python pure. Importez tous les modules utilisés DANS LA FONCTION.
6. L’interpréteur Python utilisé est le même que celui utilisé pour exécuter le script.

Exemple

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

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

Génère les fichiers de configuration UDF et les scripts exécutables.

Cette fonction crée les fichiers nécessaires pour une fonction définie par l'utilisateur (UDF) dans chDB :

1. Un script exécutable Python qui traite les données d'entrée
2. Un fichier de configuration XML qui enregistre l'UDF dans ClickHouse

Syntaxe

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

Paramètres

Fonctions utilitaires et fonctions d'assistance pour chDB.

Ce module contient diverses fonctions utilitaires pour travailler avec chDB, notamment l'inférence de types de données, des fonctions d'assistance pour la conversion de données et des utilitaires de débogage.

Convertit une liste de dictionnaires en format colonnaire.

Cette fonction prend une liste de dictionnaires et la convertit en un dictionnaire où chaque clé correspond à une colonne et chaque valeur à une liste de valeurs de cette colonne. Les valeurs manquantes dans les dictionnaires sont représentées par None.

Syntaxe

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

Paramètres

Retourne

Exemple

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

Aplatit un dictionnaire imbriqué.

Cette fonction prend un dictionnaire imbriqué et l'aplatit en concaténant les clés imbriquées à l'aide d'un séparateur. Les listes de dictionnaires sont sérialisées en chaînes JSON.

Syntaxe

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

Paramètres

Valeur de retour

Exemple

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

Détermine le type de données le plus adapté pour une liste de valeurs.

Cette fonction examine une liste de valeurs et détermine le type de données le plus approprié pour représenter toutes les valeurs de la liste. Elle prend en compte les types integer, unsigned integer, decimal et float, et utilise par défaut « string » si les valeurs ne peuvent être représentées par aucun type numérique ou si toutes les valeurs sont None.

Syntaxe

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

Paramètres

Valeur de retour

Infère les types de données de chaque colonne d'une structure de données colonnaire.

Cette fonction analyse les valeurs de chaque colonne et infère, à partir d'un échantillon des données, le type de données le plus approprié pour chaque colonne.

Syntaxe

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

Paramètres

Renvoie

Bases : ABC

class chdb.rwabc.PyReader(data: Any)

Lit un nombre spécifié de lignes dans les colonnes données et renvoie une liste d’objets, où chaque objet correspond à une séquence de valeurs pour une colonne.

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

Paramètres

Retourne

Bases : ABC

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

Assemble et renvoie les données finales issues des blocs. Doit être implémentée par les sous-classes.

abstractmethod finalize() → bytes

Retourne

Enregistre les colonnes de données dans des blocs. Doit être implémentée par les sous-classes.

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

Paramètres

Bases : Exception

Classe d’exception de base pour les erreurs liées à chDB.

Cette exception est levée lorsque l’exécution d’une requête chDB échoue ou se heurte à une erreur. Elle hérite de la classe standard Exception de Python et fournit des informations d’erreur issues du moteur ClickHouse sous-jacent.

Le message d’exception contient généralement des informations détaillées provenant de ClickHouse, notamment des erreurs de syntaxe, des incompatibilités de type, des tables/colonnes manquantes et d’autres problèmes d’exécution de requêtes.

Variables

Exemples

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

Séquence immuable intégrée.

Si aucun argument n’est fourni, le constructeur renvoie un tuple vide. Si iterable est spécifié, le tuple est initialisé à partir de ses éléments.

Si l’argument est un tuple, la valeur renvoyée est le même objet.

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

Crée un nouvel objet chaîne de caractères à partir de l’objet donné. Si encoding ou errors est spécifié, l’objet doit alors exposer un buffer de données qui sera décodé à l’aide de l’encodage indiqué et du gestionnaire d’erreurs donné. Sinon, renvoie le résultat de object._str_() (s’il est défini) ou repr(object).

• encoding vaut par défaut ‘utf-8’.
• errors vaut par défaut ‘strict’.