Fonctions de requête de base
chdb.query(sql, output_format='CSV', path='', udf_path='')
| Paramètre | Type | Par défaut | Description |
|---|
sql | str | requis | Chaîne de requête SQL à exécuter |
output_format | str | "CSV" | Format de sortie des résultats. Formats pris en charge :
• "CSV" - valeurs séparées par des virgules
• "JSON" - format JSON
• "Arrow" - format Apache Arrow
• "Parquet" - format Parquet
• "DataFrame" - DataFrame pandas
• "ArrowTable" - PyArrow Table
• "Debug" - Active la journalisation détaillée |
path | str | "" | Chemin du fichier de la base de données. Par défaut, utilise une base de données en mémoire.
Peut être un chemin de fichier ou ":memory:" pour une base de données en mémoire |
udf_path | str | "" | Chemin vers le répertoire des fonctions définies par l’utilisateur |
| Type de retour | Condition |
|---|
str | Pour les formats texte comme CSV et JSON |
pd.DataFrame | Lorsque output_format est "DataFrame" ou "dataframe" |
pa.Table | Lorsque output_format est "ArrowTable" ou "arrowtable" |
| chdb result object | Pour les autres formats |
| Exception | Condition |
|---|
ChdbError | Si l’exécution de la requête SQL échoue |
ImportError | Si les dépendances requises pour les formats DataFrame/Arrow sont absentes |
>>> # 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")
>>> # Query with UDF
>>> result = chdb.query("SELECT my_udf('test')", udf_path="/path/to/udfs")
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 intégré. Elle prend en charge divers formats de sortie et peut fonctionner avec des bases de données en mémoire
ou sur fichier.
Syntaxe
chdb.sql(sql, output_format='CSV', path='', udf_path='')
| Paramètre | Type | Par défaut | Description |
|---|
sql | str | required | Chaîne de requête SQL à exécuter |
output_format | str | "CSV" | Format de sortie des résultats. Formats pris en charge :
• "CSV" - Valeurs séparées par des virgules
• "JSON" - Format JSON
• "Arrow" - Format Apache Arrow
• "Parquet" - Format Parquet
• "DataFrame" - DataFrame pandas
• "ArrowTable" - Table PyArrow
• "Debug" - Active la journalisation détaillée |
path | str | "" | Chemin du fichier de la base de données. Par défaut, utilise une base de données en mémoire.
Peut être un chemin de fichier ou ":memory:" pour une base de données en mémoire |
udf_path | str | "" | Chemin vers le répertoire des fonctions définies par l’utilisateur |
| Type de retour | Condition |
|---|
str | Pour les formats texte comme CSV et JSON |
pd.DataFrame | Lorsque output_format est "DataFrame" ou "dataframe" |
pa.Table | Lorsque output_format est "ArrowTable" ou "arrowtable" |
| chdb result object | Pour les autres formats |
| Exception | Condition |
|---|
ChdbError | Si l’exécution de la requête SQL échoue |
ImportError | Si les dépendances requises pour les formats DataFrame/Arrow sont absentes |
>>> # 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")
>>> # Query with UDF
>>> result = chdb.query("SELECT my_udf('test')", udf_path="/path/to/udfs")
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
Paramètres
| Paramètre | Description |
|---|
res | objet résultat d’une requête chDB contenant des données Arrow binaires |
| Type de retour | Description |
|---|
pa.Table | table PyArrow contenant les résultats de la requête |
| Type d’erreur | Description |
|---|
ImportError | Si pyarrow ou pandas ne sont pas installés |
>>> 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
Paramètres
| Paramètre | Description |
|---|
r | objet de résultat de requête chDB contenant des données Arrow au format binaire |
| Type de retour | Description |
|---|
pd.DataFrame | DataFrame pandas contenant les résultats de la requête |
| Exception | Condition |
|---|
ImportError | Si pyarrow ou pandas ne sont pas installés |
>>> result = chdb.query("SELECT 1 as id, 'hello' as msg", "Arrow")
>>> df = chdb.to_df(result)
>>> print(df)
id msg
0 1 hello
Gestion des connexions et des sessions
chdb.connect(connection_string: str = ':memory:') → Connection
| Paramètre | Type | Par défaut | Description |
|---|
connection_string | str | ":memory:" | Chaîne de connexion à la base de données. Voir les formats ci-dessous. |
| Format | Description |
|---|
":memory:" | Base de données en mémoire (par défaut) |
"test.db" | Fichier de base de données avec chemin relatif |
"file:test.db" | Identique à un chemin relatif |
"/path/to/test.db" | Fichier de base de données avec chemin absolu |
"file:/path/to/test.db" | Identique à un chemin absolu |
| Format | Description |
|---|
"file:test.db?param1=value1¶m2=value2" | Chemin relatif avec paramètres |
"file::memory:?verbose&log-level=test" | En mémoire avec paramètres |
"///path/to/test.db?param1=value1¶m2=value2" | Chemin absolu avec paramètres |
| Paramètre spécial | Devient | Description |
|---|
mode=ro | --readonly=1 | Mode en lecture seule |
verbose | (flag) | Active la journalisation détaillée |
log-level=test | (setting) | Définit le niveau de journalisation |
clickhouse local --help --verbose
Renvoie
| Type de retour | Description |
|---|
Connection | Objet de connexion à la base de données prenant en charge :
• La création de curseurs avec Connection.cursor()
• Les requêtes directes avec Connection.query()
• Les requêtes en streaming avec Connection.send_query()
• Le protocole de gestionnaire de contexte pour un nettoyage automatique |
| Exception | Condition |
|---|
RuntimeError | Si la connexion à la base de données échoue |
Une seule connexion par processus est prise en charge.
La création d’une nouvelle connexion fermera toute connexion existante.
>>> # In-memory 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
Connection - Classe de connexion à une base de donnéesCursor - 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.
classe chdb.session.Session
object
La session conserve l’état de la requête.
Si path vaut None, un répertoire temporaire sera créé et utilisé comme chemin de la base de données,
et ce répertoire temporaire sera supprimé à la fermeture de la session.
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)
| Chaîne de connexion | Description |
|---|
":memory:" | Base de données en mémoire |
"test.db" | Chemin relatif |
"file:test.db" | Identique à ci-dessus |
"/path/to/test.db" | Chemin absolu |
"file:/path/to/test.db" | Identique à ci-dessus |
"file:test.db?param1=value1¶m2=value2" | Chemin relatif avec paramètres de requête |
"file::memory:?verbose&log-level=test" | Base de données en mémoire avec paramètres de requête |
"///path/to/test.db?param1=value1¶m2=value2" | Chemin absolu avec paramètres de requête |
Gestion des arguments de la chaîne de connexionDans les chaînes de connexion contenant des paramètres de requête comme « file:test.db?param1=value1¶m2=value2 »,
des paramètres comme « param1=value1 » seront transmis au moteur ClickHouse comme arguments de démarrage.Pour plus de détails, consultez clickhouse local –help –verboseGestion de certains arguments spéciaux :
- « mode=ro » devient « –readonly=1 » pour ClickHouse (mode lecture seule)
Important
- Il ne peut y avoir qu’une seule session à la fois. Si vous souhaitez créer une nouvelle session, vous devez fermer la session existante.
- La création d’une nouvelle session fermera la session existante.
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
Cette méthode ne lèvera jamais d’exception ; vous pouvez donc l’appeler en toute sécurité dans des
blocs finally ou des destructeurs.
>>> session = Session("test.db")
>>> try:
... session.query("INVALID SQL")
... finally:
... session.cleanup() # Safe cleanup regardless of errors
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
Cette méthode est appelée automatiquement lorsque la session est utilisée comme gestionnaire de contexte
ou lorsque l’objet session est détruit.
ImportantToute tentative d’utiliser la session après l’appel à close() entraînera une erreur.
>>> 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ètre | Type | Par défaut | Description |
|---|
sql | str | obligatoire | Chaîne de requête SQL à exécuter |
fmt | str | "CSV" | Format de sortie des résultats. Formats disponibles :
• "CSV" - valeurs séparées par des virgules
• "JSON" - format JSON
• "TabSeparated" - valeurs séparées par des tabulations
• "Pretty" - format de tableau Pretty
• "JSONCompact" - format JSON compact
• "Arrow" - format Apache Arrow
• "Parquet" - format Parquet |
udf_path | str | "" | Chemin vers les fonctions définies par l’utilisateur. S’il n’est pas spécifié, le chemin UDF défini lors de l’initialisation de la session est utilisé |
format :
- Les formats texte (CSV, JSON, etc.) renvoient une valeur
str
- Les formats binaires (Arrow, Parquet) renvoient une valeur
bytes
Lève
| Exception | Condition |
|---|
RuntimeError | Si la session est fermée ou invalide |
ValueError | Si la requête SQL est mal formée |
Le format « Debug » n’est pas pris en charge et sera automatiquement converti
en « CSV », avec un avertissement.
Pour le débogage, utilisez plutôt les paramètres de la chaîne de connexion.
AvertissementCette méthode exécute la requête de manière synchrone et charge tous les résultats en
mémoire. Pour les jeux de résultats volumineux, envisagez d’utiliser send_query() pour
obtenir des résultats en streaming. >>> 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
send_query() - Pour exécuter des requêtes en fluxsql - 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ètre | Type | Par défaut | Description |
|---|
sql | str | obligatoire | Chaîne de requête SQL à exécuter |
fmt | str | "CSV" | Format de sortie des résultats. Formats disponibles :
• "CSV" - Valeurs séparées par des virgules
• "JSON" - Format JSON
• "TabSeparated" - Valeurs séparées par des tabulations
• "JSONCompact" - Format JSON compact
• "Arrow" - Format Apache Arrow
• "Parquet" - Format Parquet |
| Type de retour | Description |
|---|
StreamingResult | Un itérateur de résultats en streaming qui renvoie progressivement les résultats de la requête. L’itérateur peut être utilisé dans des boucles for ou converti en d’autres structures de données |
| Exception | Condition |
|---|
RuntimeError | Si la session est fermée ou non valide |
ValueError | Si la requête SQL est mal formée |
Le format “Debug” n’est pas pris en charge et sera automatiquement converti
en “CSV” avec un avertissement. Pour le débogage, utilisez plutôt des paramètres de chaîne de connexion.
L’objet StreamingResult renvoyé doit être consommé rapidement ou stocké de manière appropriée, car il maintient une connexion à la base de données.
>>> 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}")
query() - Pour exécuter des requêtes non streamingchdb.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ètre | Type | Par défaut | Description |
|---|
sql | str | required | Chaîne de requête SQL à exécuter |
fmt | str | "CSV" | Format de sortie des résultats. Formats disponibles :
• "CSV" - Valeurs séparées par des virgules
• "JSON" - Format JSON
• "TabSeparated" - Valeurs séparées par des tabulations
• "Pretty" - Format de tableau Pretty
• "JSONCompact" - Format JSON compact
• "Arrow" - Format Apache Arrow
• "Parquet" - Format Parquet |
udf_path | str | "" | Chemin vers les fonctions définies par l’utilisateur. S’il n’est pas spécifié, le chemin UDF défini lors de l’initialisation de la session est utilisé |
- Les formats texte (CSV, JSON, etc.) renvoient
str
- Les formats binaires (Arrow, Parquet) renvoient
bytes
Lève :
| Exception | Condition |
|---|
RuntimeError | Si la session est fermée ou non valide |
ValueError | Si la requête SQL est mal formée |
Le format « Debug » n’est pas pris en charge et sera automatiquement converti
en « CSV », avec un avertissement. Pour le débogage, utilisez plutôt les paramètres
de la chaîne de connexion.
AvertissementCette méthode exécute la requête de manière synchrone et charge tous les résultats en
mémoire.
Pour les jeux de résultats volumineux, envisagez d’utiliser send_query() pour obtenir des résultats en streaming. >>> 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
send_query() - Pour l’exécution d’une requête en streamingsql - 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).
Une seule connexion ouverte est autorisée par processus. Plusieurs appels avec la même
chaîne de connexion renverront le même objet de connexion.
Syntaxe
chdb.state.connect(connection_string: str = ':memory:') → Connection
| Paramètre | Type | Valeur par défaut | Description |
|---|
connection_string(str, optional) | str | ":memory:" | Chaîne de connexion à la base de données. Voir les formats ci-dessous. |
| Format | Description |
|---|
":memory:" | Base de données en mémoire (par défaut) |
"test.db" | Fichier de base de données avec chemin relatif |
"file:test.db" | Identique au chemin relatif |
"/path/to/test.db" | Fichier de base de données avec chemin absolu |
"file:/path/to/test.db" | Identique au chemin absolu |
| Format | Description |
|---|
"file:test.db?param1=value1¶m2=value2" | Chemin relatif avec paramètres |
"file::memory:?verbose&log-level=test" | En mémoire avec paramètres |
"///path/to/test.db?param1=value1¶m2=value2" | Chemin absolu avec paramètres |
| Paramètre spécial | Devient | Description |
|---|
mode=ro | --readonly=1 | Mode lecture seule |
verbose | (flag) | Active la journalisation détaillée |
log-level=test | (setting) | Définit le niveau de journalisation |
clickhouse local --help --verbose
Renvoie
| Type de retour | Description |
|---|
Connection | Objet de connexion à la base de données qui prend en charge :
• la création de curseurs avec Connection.cursor()
• les requêtes directes avec Connection.query()
• les requêtes en streaming avec Connection.send_query()
• le protocole du gestionnaire de contexte pour le nettoyage automatique |
| Exception | Condition |
|---|
RuntimeError | Si la connexion à la base de données échoue |
AvertissementUne seule connexion par processus est prise en charge.
La création d’une nouvelle connexion fermera toute connexion existante.
>>> # In-memory 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
Connection - Classe de connexion à la base de donnéesCursor - Curseur de base de données pour les opérations de DB-API 2.0
classe chdb.state.sqlitelike.Connection
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
Cette méthode est idempotente - elle peut être appelée plusieurs fois sans risque.
AvertissementToutes les requêtes en streaming en cours seront annulées lorsque la connexion
sera fermée. Assurez-vous que toutes les données importantes ont bien été traitées avant de la fermer.
>>> 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
Retourne
| Type de retour | Description |
|---|
Cursor | Un objet curseur pour les opérations sur la base de données |
La création d’un nouveau curseur remplacera tout curseur existant associé
à cette connexion. Une seule instance de curseur par connexion est prise en charge.
>>> 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'),)
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ètre | Type | Par défaut | Description |
|---|
query | str | obligatoire | Chaîne de requête SQL à exécuter |
format | str | "CSV" | Format de sortie des résultats. Formats pris en charge :
• "CSV" - Valeurs séparées par des virgules (chaîne)
• "JSON" - Format JSON (chaîne)
• "Arrow" - Format Apache Arrow (octets)
• "Dataframe" - Pandas DataFrame (nécessite pandas)
• "Arrowtable" - PyArrow Table (nécessite pyarrow) |
| Type de retour | Description |
|---|
str | Pour les formats texte (CSV, JSON) |
bytes | Pour le format Arrow |
pandas.DataFrame | Pour le format dataframe |
pyarrow.Table | Pour le format arrowtable |
| Exception | Condition |
|---|
RuntimeError | Si l’exécution de la requête échoue |
ImportError | Si les paquets requis pour le format ne sont pas installés |
AvertissementCette méthode charge l’ensemble du jeu de résultats en mémoire. Pour des
résultats volumineux, envisagez d’utiliser send_query() pour le streaming. >>> 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
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ètre | Type | Par défaut | Description |
|---|
query | str | obligatoire | chaîne de requête SQL à exécuter |
format | str | "CSV" | Format de sortie des résultats. Formats pris en charge :
• "CSV" - Valeurs séparées par des virgules
• "JSON" - Format JSON
• "Arrow" - Format Apache Arrow (active la méthode record_batch())
• "dataframe" - blocs de Pandas DataFrame
• "arrowtable" - blocs de tables PyArrow |
| Type de retour | Description |
|---|
StreamingResult | Un itérateur de résultats de requête en streaming qui prend en charge :
• le protocole d’itération (boucles for)
• le protocole de gestionnaire de contexte (instructions with)
• la récupération manuelle avec la méthode fetch()
• le streaming de PyArrow RecordBatch (format Arrow uniquement) |
| Exception | Condition |
|---|
RuntimeError | Si l’exécution de la requête échoue |
ImportError | Si les packages requis pour ce format ne sont pas installés |
Seul le format « Arrow » prend en charge la méthode record_batch() sur le StreamingResult renvoyé.
>>> 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}")
classe chdb.state.sqlitelike.StreamingResult
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
Retourne
| Type de retour | Description |
|---|
str | Pour les formats texte (CSV, JSON) |
bytes | Pour les formats binaires (Arrow, Parquet) |
None | Quand le flux de résultats est épuisé |
>>> 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
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
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ètre | Type | Par défaut | Description |
|---|
rows_per_batch | int | 1000000 | Nombre de lignes par lot |
| Type de retour | Description |
|---|
pa.RecordBatchReader | PyArrow RecordBatchReader pour itérer sur les lots |
Cette méthode n’est disponible que lorsque la requête en streaming a été lancée
avec format="Arrow". Son utilisation avec d’autres formats provoquera une erreur.
>>> 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")
Protocole des gestionnaires de contexte
>>> with conn.send_query("SELECT * FROM data") as stream:
... for chunk in stream:
... process(chunk)
>>> # Stream automatically closed
classe chdb.state.sqlitelike.Cursor
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
Cette méthode est idempotente - elle peut être appelée plusieurs fois sans risque.
Le curseur est également fermé automatiquement lorsque la connexion est fermée.
>>> 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
Retourne
| Type de retour | Description |
|---|
list | Liste de chaînes correspondant aux noms des colonnes, ou liste vide si aucune requête n’a été exécutée ou si la requête n’a renvoyé aucune colonne |
>>> cursor = conn.cursor()
>>> cursor.execute("SELECT id, name, email FROM users LIMIT 1")
>>> print(cursor.column_names())
['id', 'name', 'email']
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
Renvoie
| Type de retour | Description |
|---|
list | Liste de chaînes contenant des noms de types ClickHouse, ou liste vide si aucune requête n’a été exécutée ou si la requête n’a renvoyé aucune colonne |
>>> cursor = conn.cursor()
>>> cursor.execute("SELECT toInt32(1), toString('hello')")
>>> print(cursor.column_types())
['Int32', 'String']
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.
ClickHouse valide généralement les opérations automatiquement ; les validations explicites
ne sont donc, en règle générale, pas nécessaires. Cette méthode est fournie pour assurer la compatibilité
avec le flux de travail standard de DB-API 2.0.
>>> cursor = conn.cursor()
>>> cursor.execute("INSERT INTO test VALUES (1, 'data')")
>>> cursor.commit()
propriété description : list
| Type de retour | Description |
|---|
list | Liste de tuples à 7 éléments décrivant chaque colonne, ou liste vide si aucune requête SELECT n’a été exécutée |
Cette propriété suit la spécification DB-API 2.0 pour cursor.description.
Seuls les deux premiers éléments (name et type_code) contiennent des
données utiles dans cette implémentation.
>>> 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
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ètre | Type | Description |
|---|
query | str | chaîne de requête SQL à exécuter |
| Exception | Condition |
|---|
Exception | Si l’exécution de la requête échoue ou si l’analyse des résultats échoue |
Cette méthode suit les spécifications DB-API 2.0 pour cursor.execute().
Après l’exécution, utilisez fetchone(), fetchmany() ou fetchall() pour
récupérer les résultats.
La méthode convertit automatiquement les types de données ClickHouse en types
Python appropriés :
- Types Int/UInt → int
- Types Float → float
- String/FixedString → str
- DateTime → datetime.datetime
- Date → datetime.date
- Bool → bool
>>> 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'),)
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
Renvoie :
| Type de retour | Description |
|---|
tuple | Tuple contenant tous les tuples de lignes restants du jeu de résultats. Renvoie un tuple vide si aucune ligne n’est disponible |
AvertissementCette méthode charge toutes les lignes restantes en mémoire en une seule fois. Pour les jeux
de résultats volumineux, envisagez d’utiliser fetchmany() pour traiter les résultats
par lots. >>> 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}")
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ètre | Type | Par défaut | Description |
|---|
size | int | 1 | Nombre maximal de lignes à récupérer |
| Type de retour | Description |
|---|
tuple | Tuple contenant jusqu’à ‘size’ tuples de lignes. Peut contenir moins de lignes si le jeu de résultats est épuisé |
Cette méthode suit les spécifications de la DB-API 2.0. Elle renvoie
moins de ‘size’ lignes si le jeu de résultats est épuisé.
>>> 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)
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
| Type de retour | Description |
|---|
Optional[tuple] | Ligne suivante sous forme de tuple de valeurs de colonne, ou None s’il n’y a plus de lignes disponibles |
Cette méthode suit les spécifications DB-API 2.0. Les valeurs de colonne sont
automatiquement converties dans les types Python appropriés en fonction des
types de colonne ClickHouse.
>>> 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()
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ètre | Type | Description |
|---|
res | - | Objet résultat de requête de chdb contenant des données au format Arrow |
| Type de retour | Description |
|---|
pyarrow.Table | Table PyArrow contenant les résultats de la requête |
| Exception | Condition |
|---|
ImportError | Si les paquets pyarrow ou pandas ne sont pas installés |
Cette fonction nécessite que pyarrow et pandas soient installés.
Installez-les avec : pip install pyarrow pandas
AvertissementLes résultats vides renvoient une table PyArrow vide sans schéma.
>>> 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
chdb.state.sqlitelike.to_df
chdb.state.sqlitelike.to_df(r)
| Paramètre | Type | Description |
|---|
r | - | Objet résultat de la requête issu de chdb, contenant des données au format Arrow |
| Type de retour | Description |
|---|
pandas.DataFrame | DataFrame contenant les résultats de la requête avec les noms de colonnes et les types de données appropriés |
| Exception | Condition |
|---|
ImportError | Si les paquets pyarrow ou pandas ne sont pas installés |
Cette fonction utilise le multithreading pour convertir Arrow en Pandas
afin d’améliorer les performances sur de grands jeux de données.
>>> 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
Intégration avec DataFrame
classe chdb.dataframe.Table
class chdb.dataframe.Table(*args: Any, **kwargs: Any)
Interface DB-API 2.0 (DBAPI)
- 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ètre | Type | Par défaut | Description |
|---|
path | str | None | Chemin du fichier de la base de données. None pour une base de données en mémoire |
| Exception | Condition |
|---|
err.Error | Si la connexion ne peut pas être établie |
chdb.dbapi.get_client_info()
chdb.dbapi.get_client_info()
| Type de retour | Description |
|---|
str | Chaîne de version au format ‘major.minor.patch’ |
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
Paramètres
| Paramètre | Type | Description |
|---|
x | - | Données d’entrée à convertir au format binaire |
| Type de retour | Description |
|---|
bytes | Les données d’entrée converties en octets |
classe chdb.dbapi.connections.Connection(path=None)
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 en mémoire et basées sur des fichiers.
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ètre | Type | Par défaut | Description |
|---|
path | str | None | Chemin du fichier de la base de données. Si None, utilise une base de données en mémoire. Peut être un chemin de fichier comme ‘database.db’ ou None pour ‘:memory:’ |
| Variable | Type | Description |
|---|
encoding | str | Encodage des caractères pour les requêtes, par défaut ‘utf8’ |
open | bool | True si la connexion est ouverte, False si elle est fermée |
>>> # In-memory 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()
ClickHouse ne prend pas en charge les transactions traditionnelles ; les opérations commit() et rollback()
sont donc sans effet, mais elles sont fournies pour assurer la conformité à la DB-API.
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
Lève
| Exception | Condition |
|---|
err.Error | Si la connexion est déjà fermée |
Valide la transaction en cours.
Syntaxe
Il s’agit d’une opération sans effet pour chDB/ClickHouse, car ce dernier ne prend pas en charge les
transactions traditionnelles. Elle est fournie pour assurer la conformité à DB-API 2.0.
Créer un nouveau curseur pour exécuter des requêtes.
Syntaxe
Paramètres
| Paramètre | Type | Description |
|---|
cursor | - | Ignoré, fourni pour assurer la compatibilité |
| Type de retour | Description |
|---|
Cursor | Nouvel objet curseur pour cette connexion |
| Exception | Condition |
|---|
err.Error | Si la connexion est fermée |
>>> 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ètre | Type | Description |
|---|
obj | - | Valeur à échapper (chaîne, octets, nombre, etc.) |
mapping | - | Table de correspondance facultative des caractères pour l’échappement |
| Type de retour | Description |
|---|
| - | Version échappée de la valeur d’entrée, adaptée aux requêtes SQL |
>>> 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
Paramètres
| Paramètre | Type | Description |
|---|
s | str | Chaîne à échapper |
| Type de retour | Description |
|---|
str | Chaîne échappée pouvant être incluse sans risque dans du SQL |
Vérifie si la connexion est ouverte.
Renvoie
| Type de retour | Description |
|---|
bool | Vrai si la connexion est ouverte, Faux si elle est fermée |
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
Paramètres :
| Paramètre | Type | Par défaut | Description |
|---|
sql | str or bytes | required | Requête SQL à exécuter |
fmt | str | "CSV" | Format de sortie. Les formats pris en charge incluent “CSV”, “JSON”, “Arrow”, “Parquet”, etc. |
| Type de retour | Description |
|---|
| - | Résultat de la requête dans le format spécifié |
| Exception | Condition |
|---|
err.InterfaceError | Si la connexion est fermée ou si la requête échoue |
>>> conn = Connection()
>>> result = conn.query("SELECT 1, 'hello'", "CSV")
>>> print(result)
"1,hello\n"
Renvoie la réponse à la dernière requête.
Renvoie
| Type de retour | Description |
|---|
| - | La réponse brute du dernier appel à query() |
Cette propriété est mise à jour chaque fois que query() est appelée directement.
Elle ne reflète pas les requêtes exécutées via des curseurs.
Annule la transaction en cours.
Syntaxe
Il s’agit d’un no-op pour chDB/ClickHouse, car chDB/ClickHouse ne prend pas en charge les
transactions traditionnelles. Cette opération est fournie pour assurer la conformité à DB-API 2.0.
classe chdb.dbapi.cursors.Cursor
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)
| Variable | Type | Description |
|---|
description | tuple | Métadonnées des colonnes du dernier résultat de requête |
rowcount | int | Nombre de lignes affectées par la dernière requête (-1 si inconnu) |
arraysize | int | Nombre de lignes à récupérer en une seule fois par défaut (par défaut : 1) |
lastrowid | - | ID de la dernière ligne insérée (le cas échéant) |
max_stmt_length | int | Taille maximale d’une instruction pour executemany() (par défaut : 1024000) |
>>> 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ètre | Type | Description |
|---|
procname | str | Nom de la procédure stockée à exécuter |
args | sequence | Paramètres à passer à la procédure |
| Type de retour | Description |
|---|
sequence | Le paramètre args d’origine (non modifié) |
chDB/ClickHouse ne prend pas en charge les procédures stockées au sens traditionnel.
Cette méthode est fournie pour assurer la conformité à DB-API 2.0, mais n’effectue
aucune opération réelle. Utilisez execute() pour toutes les opérations SQL.
CompatibilitéIl s’agit d’une implémentation de substitution. Les fonctionnalités traditionnelles des procédures stockées,
comme les paramètres OUT/INOUT, plusieurs jeux de résultats et les variables
du serveur, ne sont pas prises en charge par le moteur ClickHouse sous-jacent.
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
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ètre | Type | Valeur par défaut | Description |
|---|
query | str | obligatoire | Requête SQL à exécuter |
args | tuple/list/dict | None | Paramètres à lier aux espaces réservés |
| Type de retour | Description |
|---|
int | Nombre de lignes affectées (-1 si inconnu) |
| Style | Exemple |
|---|
| Style point d’interrogation | "SELECT * FROM users WHERE id = ?" |
| Style nommé | "SELECT * FROM users WHERE name = %(name)s" |
| Style de format | "SELECT * FROM users WHERE age = %s" (ancien) |
>>> # 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")
| Exception | Condition |
|---|
ProgrammingError | Si le curseur est fermé ou si la requête est mal formée |
InterfaceError | Si une erreur de base de données survient pendant l’exécution |
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
Paramètres
| Paramètre | Type | Description |
|---|
query | str | Requête SQL à exécuter plusieurs fois |
args | séquence | Séquence de tuples/dicts/listes de paramètres pour chaque exécution |
| Type de retour | Description |
|---|
int | Nombre total de lignes affectées sur l’ensemble des exécutions |
>>> # 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
... )
Cette méthode améliore les performances des opérations INSERT et UPDATE sur plusieurs lignes
en optimisant l’exécution de la requête.
Récupère toutes les lignes restantes du résultat de la requête.
Syntaxe
Renvoie
| Type de retour | Description |
|---|
list | Liste de tuples représentant toutes les lignes restantes |
| Exception | Condition |
|---|
ProgrammingError | Si execute() n’a pas encore été appelé |
AvertissementCette méthode peut consommer beaucoup de mémoire avec des jeux de résultats volumineux.
Envisagez d’utiliser fetchmany() pour les grands jeux de résultats.
>>> 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
Paramètres
| Paramètre | Type | Par défaut | Description |
|---|
size | int | 1 | Nombre de lignes à récupérer. S’il n’est pas spécifié, cursor.arraysize est utilisé |
| Type de retour | Description |
|---|
list | Liste de tuples représentant les lignes récupérées |
| Exception | Condition |
|---|
ProgrammingError | Si execute() n’a pas été appelé au préalable |
>>> 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
Renvoie
| Type de retour | Description |
|---|
tuple or None | Ligne suivante sous forme de tuple, ou None s’il n’y a plus de lignes disponibles |
| Exception | Condition |
|---|
ProgrammingError | Si execute() n’a pas été appelé au préalable |
>>> cursor.execute("SELECT id, name FROM users LIMIT 3")
>>> row = cursor.fetchone()
>>> print(row) # (1, 'Alice')
>>> row = cursor.fetchone()
>>> print(row) # (2, 'Bob')
max_stmt_length = 1024000
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ètre | Type | Par défaut | Description |
|---|
query | str | required | Requête SQL avec des espaces réservés de paramètre |
args | tuple/list/dict | None | Paramètres de substitution |
| Type de retour | Description |
|---|
str | Requête SQL finale avec les paramètres substitués |
>>> cur.mogrify("SELECT * FROM users WHERE id = ?", (123,))
"SELECT * FROM users WHERE id = 123"
Cette méthode est conforme à l’extension de DB-API 2.0 utilisée par Psycopg.
Passe au jeu de résultats suivant (fonction non prise en charge).
Syntaxe
Renvoie
| Type de retour | Description |
|---|
None | Renvoie toujours None, car les jeux de résultats multiples ne sont pas pris en charge |
chDB/ClickHouse ne prend pas en charge plusieurs jeux de résultats pour une seule requête.
Cette méthode est fournie pour la conformité à DB-API 2.0, mais renvoie toujours None.
Définit la taille des entrées pour les paramètres (implémentation no-op).
Syntaxe
Paramètres
| Paramètre | Type | Description |
|---|
*args | - | Spécifications de taille des paramètres (ignorées) |
Cette méthode ne fait rien, mais elle est requise par la spécification DB-API 2.0.
chDB gère automatiquement la taille des paramètres en interne.
Définit la taille des colonnes de sortie (implémentation no-op).
Syntaxe
Paramètres
| Paramètre | Type | Description |
|---|
*args | - | Spécifications de taille des colonnes (ignorées) |
Cette méthode ne fait rien, mais elle est requise par la spécification DB-API 2.0.
chDB gère automatiquement en interne la taille des données de sortie.
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
| Exception | Description |
|---|
Warning | Avertissements non fatals lors des opérations de base de données |
InterfaceError | Problèmes liés à l’interface de la base de données elle-même |
DatabaseError | Classe de base pour toutes les erreurs liées à la base de données |
DataError | Problèmes de traitement des données (valeurs non valides, erreurs de type) |
OperationalError | Problèmes de fonctionnement de la base de données (connectivité, ressources) |
IntegrityError | Violations de contraintes (clés étrangères, unicité) |
InternalError | Erreurs internes de la base de données et corruption |
ProgrammingError | Erreurs de syntaxe SQL et mauvaise utilisation de l’API |
NotSupportedError | Fonctionnalités ou opérations non prises en charge |
Ces classes d’exception sont conformes à la spécification Python DB API 2.0
et assurent une gestion cohérente des erreurs dans les différentes opérations de base de données.
>>> 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'
exception chdb.dbapi.err.DataError
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
| Exception | Condition |
|---|
DataError | Lorsque la validation ou le traitement des données échoue |
>>> # 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
exception chdb.dbapi.err.DatabaseError
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
Elle sert de classe de base à des types d’erreurs de base de données plus spécifiques,
comme DataError, OperationalError, etc.
exception chdb.dbapi.err.Error
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.
Cette hiérarchie d’exceptions suit la spécification Python DB API 2.0.
Warning - Pour les avertissements non fatals qui n’empêchent pas l’exécution d’une opération jusqu’à son terme
exception chdb.dbapi.err.IntegrityError
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
| Exception | Condition |
|---|
IntegrityError | Lorsque les contraintes d’intégrité de la base de données sont violées |
>>> # 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
exception chdb.dbapi.err.InterfaceError
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
| Exception | Condition |
|---|
InterfaceError | Lorsque l’interface de la base de données rencontre des erreurs non liées aux opérations de base de données |
Ces erreurs sont généralement des erreurs de programmation ou des problèmes de configuration
qui peuvent être résolus en corrigeant le code client ou la configuration.
exception chdb.dbapi.err.InternalError
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
| Exception | Condition |
|---|
InternalError | Lorsque la base de données présente des incohérences internes |
AvertissementLes erreurs internes peuvent indiquer de graves problèmes de base de données qui requièrent
l’intervention d’un administrateur de base de données. Ces erreurs ne peuvent généralement pas
être résolues par une logique de nouvelle tentative au niveau de l’application.
Ces erreurs échappent généralement au contrôle de l’application
et peuvent nécessiter un redémarrage de la base de données ou des opérations de réparation.
exception chdb.dbapi.err.NotSupportedError
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
| Exception | Condition |
|---|
NotSupportedError | Lorsque des fonctionnalités non prises en charge sont utilisées |
>>> # 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
Consultez la documentation de la base de données et les fonctionnalités prises en charge par le pilote afin d’éviter
ces erreurs. Prévoyez, si possible, des mécanismes de repli appropriés.
exception chdb.dbapi.err.OperationalError
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
| Exception | Condition |
|---|
OperationalError | Lorsque les opérations sur la base de données échouent pour des raisons opérationnelles |
Ces erreurs sont généralement transitoires et peuvent être résolues en réessayant
l’opération ou en corrigeant des problèmes au niveau du système.
AvertissementCertaines erreurs opérationnelles peuvent indiquer de graves problèmes système
nécessitant une intervention administrative.
exception chdb.dbapi.err.ProgrammingError
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
| Exception | Condition |
|---|
ProgrammingError | Lorsque des instructions SQL ou l’utilisation de l’API comportent des erreurs |
>>> # 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
exception chdb.dbapi.err.StandardError
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.
Cette classe d’exception suit la spécification Python DB API 2.0
pour la gestion des exceptions de base de données.
exception chdb.dbapi.err.Warning
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
Ce comportement suit la spécification Python DB API 2.0 pour les exceptions d’avertissement.
chdb.dbapi.apilevel = '2.0'
str(object=’’) -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str
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’.
chdb.dbapi.threadsafety = 1
int([x]) -> integer
int(x, base=10) -> integer
>>> int(‘0b100’, base=0)
4
str(object=’’) -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str
chdb.dbapi.STRING = frozenset({247, 253, 254})
>>> 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
chdb.dbapi.BINARY = frozenset({249, 250, 251, 252})
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
chdb.dbapi.NUMBER = frozenset({0, 1, 3, 4, 5, 8, 9, 13})
>>> 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
chdb.dbapi.DATE = frozenset({10, 14})
>>> 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
chdb.dbapi.TIME = frozenset({11})
>>> 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
chdb.dbapi.TIMESTAMP = frozenset({7, 12})
>>> 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
chdb.dbapi.DATETIME = frozenset({7, 12})
>>> 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
chdb.dbapi.ROWID = frozenset({})
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
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()
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()
import chdb.dbapi as dbapi
# In-memory 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()
- Gestion des connexions : fermez toujours les connexions et les curseurs une fois vos opérations terminées
- Gestionnaires de contexte : utilisez des instructions
with pour libérer automatiquement les ressources
- Traitement par lots : utilisez
fetchmany() pour les jeux de résultats volumineux
- Gestion des erreurs : placez les opérations sur la base de données dans des blocs try-except
- Liaison de paramètres : utilisez des requêtes paramétrées lorsque c’est possible
- Gestion de la mémoire : évitez
fetchall() pour les jeux de données très volumineux
- L’interface DB-API 2.0 de chDB est compatible avec la plupart des outils de base de données Python
- L’interface offre une sécurité des threads de niveau 1 (les threads peuvent partager des modules, mais pas des connexions)
- Les chaînes de connexion prennent en charge les mêmes paramètres que les sessions chDB
- Toutes les exceptions standard de DB-API 2.0 sont prises en charge
Avertissement
- Fermez toujours les curseurs et les connexions pour éviter les fuites de ressources
- Les jeux de résultats volumineux doivent être traités par lots
- La syntaxe de liaison de paramètres suit le style
format : %s
Fonctions définies par l’utilisateur (UDF)
chdb.udf.chdb_udf(return_type='String')
| Paramètre | Type | Par défaut | Description |
|---|
return_type | str | "String" | Type de retour de la fonction. Doit être l’un des types de données ClickHouse |
- La fonction doit être sans état. Seules les UDF sont prises en charge, pas les UDAF.
- Le type de retour par défaut est String. Le type de retour doit être l’un des types de données ClickHouse.
- La fonction doit accepter des arguments de type String. Tous les arguments sont des chaînes de caractères.
- La fonction sera appelée pour chaque ligne d’entrée.
- La fonction doit être une fonction Python pure. Importez tous les modules utilisés DANS LA FONCTION.
- 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 :
- Un script exécutable Python qui traite les données d’entrée
- Un fichier de configuration XML qui enregistre l’UDF dans ClickHouse
Syntaxe
chdb.udf.generate_udf(func_name, args, return_type, udf_body)
| Paramètre | Type | Description |
|---|
func_name | str | Nom de la fonction UDF |
args | list | Liste des noms des arguments de la fonction |
return_type | str | Type de retour ClickHouse de la fonction |
udf_body | str | Corps du code source Python de la fonction UDF |
Cette fonction est généralement appelée par le décorateur @chdb_udf et ne
doit pas être appelée directement par les utilisateurs.
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.
chdb.utils.convert_to_columnar
chdb.utils.convert_to_columnar(items: List[Dict[str, Any]]) → Dict[str, List[Any]]
| Paramètre | Type | Description |
|---|
items | List[Dict[str, Any]] | Une liste de dictionnaires à convertir |
| Type de retour | Description |
|---|
Dict[str, List[Any]] | Un dictionnaire dont les clés sont les noms de colonnes et les valeurs des listes de valeurs de colonnes |
>>> 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ètre | Type | Par défaut | Description |
|---|
d | Dict[str, Any] | obligatoire | Le dictionnaire à aplatir |
parent_key | str | "" | La clé de base à ajouter en préfixe à chaque clé |
sep | str | "_" | Le séparateur à utiliser entre les clés concaténées |
| Type de retour | Description |
|---|
Dict[str, Any] | Un dictionnaire aplati |
>>> 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}]'
}
chdb.utils.infer_data_type
chdb.utils.infer_data_type(values: List[Any]) → str
| Paramètre | Type | Description |
|---|
values | List[Any] | Une liste de valeurs à analyser. Les valeurs peuvent être de n’importe quel type |
| Type de retour | Description |
|---|
str | Une chaîne représentant le type de données inféré. Les valeurs de retour possibles sont : “int8”, “int16”, “int32”, “int64”, “int128”, “int256”, “uint8”, “uint16”, “uint32”, “uint64”, “uint128”, “uint256”, “decimal128”, “decimal256”, “float32”, “float64” ou “string”. |
- Si toutes les valeurs de la liste sont None, la fonction renvoie “string”.
- Si l’une des valeurs de la liste est une chaîne, la fonction renvoie immédiatement “string”.
- La fonction suppose que les valeurs numériques peuvent être représentées sous forme d’entiers,
de nombres décimaux ou de nombres à virgule flottante selon leur plage et leur précision.
chdb.utils.infer_data_types
chdb.utils.infer_data_types`(column_data: Dict[str, List[Any]], n_rows: int = 10000) → List[tuple]
| Paramètre | Type | Défaut | Description |
|---|
column_data | Dict[str, List[Any]] | obligatoire | Un dictionnaire dans lequel les clés sont les noms des colonnes et les valeurs sont des listes de valeurs de colonnes |
n_rows | int | 10000 | Le nombre de lignes à échantillonner pour l’inférence de type |
| Type de retour | Description |
|---|
List[tuple] | Une liste de tuples contenant chacun un nom de colonne et le type de données inféré correspondant |
Classes de base abstraites
classe chdb.rwabc.PyReader(data: Any)`
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ètre | Type | Description |
|---|
col_names | List[str] | Liste des noms de colonnes à lire |
count | int | Nombre maximal de lignes à lire |
| Type de retour | Description |
|---|
List[Any] | Liste de séquences, une pour chaque colonne |
classe chdb.rwabc.PyWriter
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
| Type de retour | Description |
|---|
bytes | Les données finales sérialisées |
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ètre | Type | Description |
|---|
col_names | List[str] | Liste des noms de colonnes en cours d’écriture |
columns | List[List[Any]] | Liste des données de colonnes, chaque colonne étant représentée par une liste |
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
| Variable | Type | Description |
|---|
args | - | Tuple contenant le message d’erreur et tout argument supplémentaire |
>>> 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'
Cette exception est automatiquement levée par chdb.query() et les
fonctions associées lorsque le moteur ClickHouse sous-jacent signale une erreur.
Vous devez intercepter cette exception lors du traitement de requêtes
susceptibles d’échouer afin d’assurer une gestion appropriée des erreurs dans votre application.
chdb.chdb_version = ('3', '6', '0')
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.
chdb.engine_version = '25.5.2.1'
str(object=’’) -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str
- encoding vaut par défaut ‘utf-8’.
- errors vaut par défaut ‘strict’.
chdb.__version__ = '3.6.0'
str(object=’’) -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str
- encoding vaut par défaut ‘utf-8’.
- errors vaut par défaut ‘strict’.
