Inserción avanzada

ClickHouse Connect ejecuta las inserciones en Native format, los métodos insert e insert_df, dentro de un InsertContext. Los métodos insert_arrow, insert_df_arrow y raw_insert envían sus payloads directamente y no usan ninguno. El InsertContext incluye todos los valores enviados como argumentos al método insert del cliente. Además, cuando se crea un InsertContext, ClickHouse Connect recupera los tipos de datos de las columnas de inserción necesarios para realizar inserciones eficientes en Native format. Al reutilizar el InsertContext para varias inserciones, se evita esta "consulta previa" y las inserciones se ejecutan de forma más rápida y eficiente.

Se puede obtener un InsertContext mediante el método create_insert_context del cliente. El método acepta los mismos argumentos que la función insert, excepto context en sí. Tenga en cuenta que, para reutilizarlo, solo debe modificarse la propiedad data de los InsertContext. Esto concuerda con su propósito: proporcionar un objeto reutilizable para inserciones repetidas de datos nuevos en la misma tabla.

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 incluyen un estado mutable que se actualiza durante el proceso de inserción, así que no es seguro usarlos desde varios hilos.

Los formatos de escritura están implementados para un número limitado de tipos. En la mayoría de los casos, ClickHouse Connect determina automáticamente el formato de escritura correcto para una columna a partir de su primer valor de datos no nulo. Por ejemplo, cuando el primer valor de una columna DateTime es un entero, el Client lo trata como un segundo desde la época.

Normalmente no es necesario aplicar una sobrescritura a un formato de escritura, pero los métodos de clickhouse_connect.datatypes.format pueden establecer uno de forma global. Las envolturas de contenedor, como Array, Nullable y LowCardinality, conservan el comportamiento de formato del tipo de elemento.

ClickHouse Connect proporciona métodos especializados de inserción para formatos de datos habituales:

• insert_df – Inserta un DataFrame de Pandas como datos Native orientados a columnas. También admite nombres y tipos de columna explícitos o un InsertContext reutilizable.
• insert_arrow – Inserta una tabla de PyArrow usando el formato de entrada Arrow de ClickHouse.
• insert_df_arrow – Inserta un DataFrame de Pandas respaldado por Arrow o un DataFrame de Polars. Todas las columnas de Pandas deben usar dtypes basados en Arrow.

Los tres métodos aceptan database, settings y transport_settings HTTP por solicitud.

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 genera una instrucción CREATE TABLE a partir de campos escalares comunes de Arrow. La correspondencia abarca enteros con y sin signo, valores de coma flotante, booleanos, cadenas, fechas y marcas de tiempo. Crea intencionadamente columnas de ClickHouse que no admiten NULL y genera TypeError para tipos de Arrow no compatibles, así que revise el DDL generado antes de ejecutarlo.

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)

Al insertar objetos datetime de Python en columnas DateTime o DateTime64, ClickHouse Connect los convierte en valores de época.

Los objetos con zona horaria conservan el instante representado. La zona horaria de origen no tiene que coincidir con la zona horaria declarada en la columna de 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]

La configuración global naive_datetime_insert controla la inserción de objetos nativos de Python con valores datetime sin zona horaria. También se aplica a las cadenas ISO sin zona horaria aceptadas por las columnas DateTime64.

• "local" es el valor predeterminado en 1.x. Python interpreta el valor en la zona horaria del proceso al llamar a .timestamp(). Esto conserva el comportamiento existente.
• "server" interpreta el valor como hora local en la zona horaria declarada por la columna DateTime o DateTime64. Si la columna no tiene zona horaria, utiliza la zona horaria del servidor indicada cuando se conectó el Client.

Configure la opción antes de realizar una inserción. Se lee al serializar cada columna de inserción nativa que contiene objetos datetime de Python o cadenas ISO DateTime64, por lo que el cambio se aplica a los Clients existentes y a los contextos de inserción reutilizables.

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

Con "server", ClickHouse Connect asigna el tzinfo de destino antes de convertir el valor a una época. Para las zonas horarias IANA, sigue las reglas de la biblioteca estándar para las transiciones de horario de verano. En una superposición de otoño se usa el valor fold de datetime. El valor predeterminado fold=0 selecciona el desplazamiento anterior a la transición, mientras que fold=1 selecciona el posterior. En un salto de primavera se usa la misma selección de desplazamiento, y no se rechaza ni se normaliza.

Las horas de reloj inexistentes durante un salto de primavera pueden no conservarse en un recorrido de ida y vuelta mediante un parámetro de consulta en modo de reloj, ya que el análisis de texto de ClickHouse puede seleccionar un desplazamiento diferente. Use un datetime con zona horaria o una hora de reloj válida cuando el instante sea importante.

La opción solo se aplica a inserciones nativas de objetos Python de valores datetime y cadenas ISO sin zona horaria aceptadas por DateTime64. Las columnas de NumPy y Pandas con dtype datetime64 sin zona horaria conservan su conversión actual de hora de reloj UTC.

Para representar un instante específico independientemente de cualquiera de los modos, asigne la zona horaria deseada o proporcione explícitamente un entero de época.

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

Los parámetros de consulta datetime sin zona horaria usan la configuración independiente naive_datetime_binding. De forma predeterminada, el modo "wall" envía los campos de hora local sin conversión a la hora local del host. Consulte la sección Argumento Parameters.

Las columnas de ClickHouse pueden declarar metadatos de zona horaria, por ejemplo DateTime('America/Denver') o DateTime64(3, 'Asia/Tokyo'). Estos metadatos controlan cómo se presentan los valores al consultarlos.

Al insertar un valor con zona horaria, ClickHouse Connect conserva el instante representado. Para un valor sin zona horaria, la configuración naive_datetime_insert controla si se usa la zona horaria del proceso o la de la columna. Al consultar, el resultado usa la zona horaria de la columna, a menos que se proporcione una sobrescritura por columna con el argumento column_tzs. El argumento query_tz no sobrescribe la zona horaria declarada de la columna.

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 carga un archivo local en una tabla existente por streaming y delega el análisis en ClickHouse.

La configuración del formato de entrada, como input_format_allow_errors_ratio y input_format_allow_errors_num, puede pasarse mediante 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,
    },
)

Para un AsyncClient, usa await con insert_file_async y los mismos argumentos:

from clickhouse_connect.driver.tools import insert_file_async

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

La función auxiliar async lee el archivo en un hilo de trabajo antes de hacer await de raw_insert, por lo que el contenido del archivo se mantiene en memoria.