Insertion avancée

ClickHouse Connect exécute les insertions au format Native, c’est-à-dire les méthodes insert et insert_df, dans un InsertContext. Les méthodes insert_arrow, insert_df_arrow et raw_insert envoient directement leurs payloads et n’en utilisent pas. L’InsertContext inclut toutes les valeurs transmises comme arguments à la méthode client insert. De plus, lors de la création initiale d’un InsertContext, ClickHouse Connect récupère les types de données des colonnes à insérer, nécessaires à des insertions efficaces au format Native. En réutilisant l’InsertContext pour plusieurs insertions, cette « pré-requête » est évitée, ce qui rend les insertions plus rapides et plus efficaces.

Il est possible d’obtenir un InsertContext à l’aide de la méthode client create_insert_context. Cette méthode prend les mêmes arguments que la fonction insert, à l’exception de context lui-même. Notez que seule la propriété data des InsertContext doit être modifiée en vue d’une réutilisation. Cela correspond à son objectif : fournir un objet réutilisable pour des insertions répétées de nouvelles données dans la même table.

test_data = [[13, "v1", "v2"], [79, "v3", "v4"]]
ic = client.create_insert_context(table="test_table", data=test_data)
client.insert(context=ic)
assert client.command("SELECT count() FROM test_table") == 2

new_data = [[101, "v5", "v6"], [113, "v7", "v8"]]
ic.data = new_data
client.insert(context=ic)
qr = client.query("SELECT * FROM test_table ORDER BY key DESC")
assert qr.row_count == 4
assert qr.first_row[0] == 113

InsertContexts incluent un état mutable mis à jour pendant le processus d’insertion ; ils ne sont donc pas thread-safe.

Les formats d'écriture sont implémentés pour un nombre limité de types. Dans la plupart des cas, ClickHouse Connect détermine automatiquement le format d'écriture approprié pour une colonne à partir de sa première valeur de données non nulle. Par exemple, lorsque la première valeur d'une colonne DateTime est un entier, le client la traite comme un nombre de secondes depuis l'époque Unix.

Il n'est généralement pas nécessaire de remplacer un format d'écriture, mais les méthodes de clickhouse_connect.datatypes.format permettent d'en définir un globalement. Les wrappers de conteneur tels que Array, Nullable et LowCardinality conservent le comportement de mise en forme du type d'élément.

ClickHouse Connect fournit des méthodes d’insertion spécialisées pour les formats de données courants :

• insert_df – Insère un Pandas DataFrame comme données Native orientées colonnes. Il prend également en charge des noms/types de colonnes explicites ou un InsertContext réutilisable.
• insert_arrow – Insère une PyArrow Table à l’aide du format d’entrée Arrow de ClickHouse.
• insert_df_arrow – Insère un Pandas DataFrame adossé à Arrow ou un Polars DataFrame. Les colonnes Pandas doivent toutes utiliser des Dtype adossés à Arrow.

Les trois méthodes acceptent database, settings et les transport_settings HTTP par requête.

import clickhouse_connect
import pandas as pd

client = clickhouse_connect.get_client()

df = pd.DataFrame({
    "id": [13, 79],
    "name": ["user_1", "user_2"],
    "age": [25, 30],
})

client.insert_df("users", df)

import clickhouse_connect
import pyarrow as pa

client = clickhouse_connect.get_client()

arrow_table = pa.table({
    "id": [13, 79],
    "name": ["user_1", "user_2"],
    "age": [25, 30],
})

client.insert_arrow("users", arrow_table)

import clickhouse_connect
import pandas as pd

client = clickhouse_connect.get_client()

# Convert to Arrow-backed dtypes for better performance
df = pd.DataFrame({
    "id": [13, 79],
    "name": ["user_1", "user_2"],
    "age": [25, 30],
}).convert_dtypes(dtype_backend="pyarrow")

client.insert_df_arrow("users", df)

create_table_from_arrow_schema génère une instruction CREATE TABLE à partir de champs scalaires Arrow courants. La correspondance couvre les entiers signés et non signés, les valeurs à virgule flottante, les booléens, les chaînes, les dates et les horodatages. Elle crée intentionnellement des colonnes ClickHouse non Nullable et lève une exception TypeError pour les types Arrow non pris en charge. Passez en revue le DDL généré avant de l’exécuter.

import clickhouse_connect
import pyarrow as pa

from clickhouse_connect.driver.ddl import create_table_from_arrow_schema

client = clickhouse_connect.get_client()
schema = pa.schema(
    [
        ("id", pa.uint32()),
        ("name", pa.string()),
        ("event_time", pa.timestamp("ms", tz="UTC")),
    ]
)
ddl = create_table_from_arrow_schema(
    table_name="arrow_events",
    schema=schema,
    engine="MergeTree",
    engine_params={"ORDER BY": "id"},
)
client.command(ddl)

Lors de l’insertion d’objets Python datetime dans des colonnes DateTime ou DateTime64, ClickHouse Connect les convertit en valeurs d’époque Unix.

Les objets avec informations de fuseau horaire préservent l’instant représenté. Il n’est pas nécessaire que le fuseau horaire source corresponde à celui déclaré sur la colonne ClickHouse.

from datetime import datetime, timezone
from zoneinfo import ZoneInfo

client.command("CREATE TABLE events (event_time DateTime) ENGINE Memory")

data = [
    [datetime(2023, 6, 15, 10, 30, tzinfo=timezone.utc)],
    [datetime(2023, 6, 15, 10, 30, tzinfo=ZoneInfo("America/Denver"))],
    [datetime(2023, 6, 15, 10, 30, tzinfo=ZoneInfo("Asia/Tokyo"))],
]

client.insert("events", data, column_names=["event_time"])
results = client.query(
    "SELECT event_time FROM events ORDER BY event_time",
    query_tz="UTC",
    tz_mode="aware",
)
assert [row[0].hour for row in results.result_rows] == [1, 10, 16]

Le paramètre global naive_datetime_insert contrôle l'insertion d'objets Python natifs contenant des valeurs datetime sans fuseau horaire. Il s'applique également aux chaînes ISO sans fuseau horaire acceptées par les colonnes DateTime64.

• "local" est la valeur par défaut dans la version 1.x. Python interprète la valeur dans le fuseau horaire du processus lors de l'appel à .timestamp(). Cela préserve le comportement existant.
• "server" interprète la valeur comme une heure locale dans le fuseau horaire déclaré par la colonne DateTime ou DateTime64. Si la colonne n'a pas de fuseau horaire, le fuseau horaire du serveur communiqué lors de la connexion du client est utilisé.

Définissez l'option avant une insertion. Elle est lue lors de la sérialisation de chaque colonne d'insertion native contenant des objets Python datetime ou des chaînes ISO DateTime64 ; la modification s'applique donc aux clients existants et aux contextes d'insertion réutilisables.

from datetime import datetime

from clickhouse_connect import common

common.set_setting("naive_datetime_insert", "server")

naive_time = datetime(2023, 6, 15, 10, 30)
client.insert("events", [[naive_time]], column_names=["event_time"])

Avec "server", ClickHouse Connect associe le tzinfo cible avant de convertir la valeur en époque Unix. Pour les fuseaux horaires IANA, il suit les règles de la bibliothèque standard pour les transitions vers ou depuis l’heure d’été. En cas de chevauchement à l’automne, la valeur fold du datetime est utilisée. Par défaut, fold=0 sélectionne le décalage avant la transition, tandis que fold=1 sélectionne celui après la transition. En cas de lacune au printemps, la même sélection de décalage est utilisée, sans rejet ni normalisation.

Les heures locales inexistantes lors d’une lacune printanière peuvent ne pas effectuer d’aller-retour via un paramètre de requête en mode wall, car l’analyse de texte de ClickHouse peut sélectionner un décalage différent. Utilisez un datetime avec fuseau horaire ou une heure locale valide lorsque l’instant est important.

L’option s’applique uniquement aux insertions natives d’objets Python datetime et aux chaînes ISO sans fuseau horaire acceptées par DateTime64. Les colonnes NumPy et Pandas de type datetime64 sans fuseau horaire conservent leur conversion existante des heures locales UTC.

Pour représenter un instant précis indépendamment de l’un ou l’autre mode, associez le fuseau horaire souhaité ou fournissez explicitement un entier époque Unix.

from datetime import datetime, timezone

utc_time = datetime(2023, 6, 15, 10, 30, tzinfo=timezone.utc)
client.insert("events", [[utc_time]], column_names=["event_time"])

naive_time = datetime(2023, 6, 15, 10, 30)
epoch_timestamp = int(naive_time.replace(tzinfo=timezone.utc).timestamp())
client.insert("events", [[epoch_timestamp]], column_names=["event_time"])

Les paramètres de requête datetime sans fuseau horaire utilisent le paramètre distinct naive_datetime_binding. Son mode par défaut, "wall", envoie les champs tels quels, sans conversion vers le fuseau horaire local de l'hôte. Consultez la section Argument Parameters.

Les colonnes ClickHouse peuvent déclarer des métadonnées de fuseau horaire, par exemple DateTime('America/Denver') ou DateTime64(3, 'Asia/Tokyo'). Ces métadonnées déterminent la manière dont les valeurs sont affichées lors de l’exécution d’une requête.

Lors de l’insertion d’une valeur avec fuseau horaire, ClickHouse Connect préserve l’instant représenté. Pour une valeur sans fuseau horaire, le paramètre naive_datetime_insert détermine si le fuseau horaire du processus ou celui de la colonne est utilisé. Lors d’une requête, le résultat utilise le fuseau horaire de la colonne, sauf si une substitution par colonne est fournie via l’argument column_tzs. L’argument query_tz ne remplace pas le fuseau horaire déclaré pour une colonne.

from datetime import datetime
from zoneinfo import ZoneInfo

client.command(
    "CREATE TABLE events_with_timezone "
    "(event_time DateTime('America/Los_Angeles')) "
    "ENGINE Memory"
)

data = datetime(2023, 6, 15, 10, 30, tzinfo=ZoneInfo("America/New_York"))
client.insert("events_with_timezone", [[data]], column_names=["event_time"])

result = client.query("SELECT event_time FROM events_with_timezone")
returned = result.first_row[0]
assert returned.hour == 7
assert returned.tzinfo == ZoneInfo("America/Los_Angeles")

clickhouse_connect.driver.tools.insert_file transmet en flux un fichier local vers une table existante et confie l’analyse à ClickHouse.

Les paramètres du format d’entrée, tels que input_format_allow_errors_ratio et input_format_allow_errors_num, peuvent être transmis via settings.

import clickhouse_connect

from clickhouse_connect.driver.tools import insert_file

client = clickhouse_connect.get_client()
insert_file(
    client,
    "example_table",
    "my_data.csv",
    settings={
        "input_format_allow_errors_ratio": 0.2,
        "input_format_allow_errors_num": 5,
    },
)

Pour un AsyncClient, utilisez await avec insert_file_async en passant les mêmes arguments :

from clickhouse_connect.driver.tools import insert_file_async

await insert_file_async(async_client, "example_table", "my_data.csv")

L'utilitaire asynchrone lit le fichier dans un thread worker avant d'attendre raw_insert, de sorte que le contenu du fichier reste en mémoire.