Inserção avançada

O ClickHouse Connect executa inserções no formato Native, pelos métodos insert e insert_df, em um InsertContext. Os métodos insert_arrow, insert_df_arrow e raw_insert enviam seus payloads diretamente e não usam um InsertContext. O InsertContext inclui todos os valores enviados como argumentos para o método insert do cliente. Além disso, quando um InsertContext é criado pela primeira vez, o ClickHouse Connect recupera os tipos de dados das colunas de inserção necessários para inserções eficientes no formato Native. Ao reutilizar o InsertContext em várias inserções, essa "pré-consulta" é evitada, e as inserções são executadas com mais rapidez e eficiência.

Um InsertContext pode ser obtido usando o método create_insert_context do cliente. O método recebe os mesmos argumentos que a função insert, exceto o próprio context. Observe que, para reutilização, apenas a propriedade data dos InsertContexts deve ser modificada. Isso está de acordo com seu propósito de fornecer um objeto reutilizável para inserções repetidas de novos dados na mesma tabela.

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 incluem estado mutável que é atualizado durante o processo de insert, portanto não são thread-safe.

Os formatos de escrita são implementados para um número limitado de tipos. Na maioria dos casos, o ClickHouse Connect determina automaticamente o formato de escrita correto para uma coluna com base no primeiro valor de dados não nulo. Por exemplo, quando o primeiro valor de uma coluna DateTime é um inteiro, o cliente o trata como um segundo desde a epoch.

Normalmente, não é necessário substituir um formato de escrita, mas os métodos em clickhouse_connect.datatypes.format podem definir um globalmente. Wrappers de contêiner, como Array, Nullable e LowCardinality, preservam o comportamento de formatação do tipo do elemento.

O ClickHouse Connect fornece métodos de inserção especializados para formatos de dados comuns:

• insert_df – Insere um DataFrame do Pandas como dados Native orientados a colunas. Também oferece suporte a nomes/tipos de coluna explícitos ou a um InsertContext reutilizável.
• insert_arrow – Insere uma tabela PyArrow usando o formato de entrada Arrow do ClickHouse.
• insert_df_arrow – Insere um DataFrame do Pandas com Arrow como backend ou um DataFrame do Polars. Todas as colunas do Pandas devem usar backends dtype baseados em Arrow.

Todos os três métodos aceitam database, settings e transport_settings de HTTP por solicitação.

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 gera uma instrução CREATE TABLE a partir de campos escalares comuns do Arrow. O mapeamento abrange inteiros com e sem sinal, valores de ponto flutuante, booleanos, strings, datas e timestamps. Ele cria intencionalmente colunas do ClickHouse que não permitem NULL e gera TypeError para tipos do Arrow sem suporte, portanto revise o DDL gerado antes de executá-lo.

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)

Ao inserir objetos datetime do Python em colunas DateTime ou DateTime64, o ClickHouse Connect os converte em valores de epoch.

Objetos com fuso horário preservam o instante representado. O fuso horário de origem não precisa coincidir com o fuso horário definido na coluna do 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]

A configuração global naive_datetime_insert controla inserções nativas de objetos Python com valores datetime sem fuso horário. Ela também se aplica a strings ISO sem fuso horário aceitas por colunas DateTime64.

• "local" é o padrão na versão 1.x. O Python interpreta o valor no fuso horário do processo quando .timestamp() é chamado. Isso preserva o comportamento atual.
• "server" interpreta o valor como hora do relógio no fuso horário declarado pela coluna DateTime ou DateTime64. Se a coluna não tiver fuso horário, usa o fuso horário do servidor informado quando o cliente se conectou.

Defina a opção antes de uma inserção. Ela é lida quando cada coluna de inserção nativa que contém objetos datetime do Python ou strings ISO DateTime64 é serializada; portanto, a alteração se aplica a clientes existentes e contextos de inserção reutilizáveis.

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

Com "server", o ClickHouse Connect associa o tzinfo de destino antes de converter o valor em epoch. Para fusos horários IANA, segue as regras da biblioteca padrão para transições de horário de verão. Uma sobreposição no outono usa o valor fold do datetime. Por padrão, fold=0 seleciona o deslocamento anterior à transição, enquanto fold=1 seleciona o deslocamento posterior. Uma lacuna na primavera usa a mesma seleção de deslocamento e não é rejeitada nem normalizada.

Horários de relógio inexistentes na lacuna da primavera podem não ser preservados em uma conversão de ida e volta por meio de um parâmetro de consulta no modo de relógio, pois a análise de texto do ClickHouse pode selecionar um deslocamento diferente. Use um datetime com fuso horário ou um horário de relógio válido quando o instante for importante.

A opção se aplica apenas a inserções nativas de objetos Python datetime e strings ISO sem fuso horário aceitas por DateTime64. Colunas NumPy e Pandas com dtype datetime64 sem fuso horário mantêm a conversão existente de horário de relógio em UTC.

Para representar um instante específico independentemente de qualquer modo, associe o fuso horário desejado ou forneça explicitamente um inteiro epoch.

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

Parâmetros de consulta datetime sem fuso horário usam a configuração separada naive_datetime_binding. O modo padrão "wall" envia os campos de data e hora sem conversão para o horário local do host. Consulte a seção argumento Parameters.

As colunas do ClickHouse podem declarar metadados de fuso horário, por exemplo DateTime('America/Denver') ou DateTime64(3, 'Asia/Tokyo'). Esses metadados controlam como os valores são apresentados quando são consultados.

Ao inserir um valor com fuso horário, o ClickHouse Connect preserva o instante representado. Para um valor sem fuso horário, a configuração naive_datetime_insert controla se é usado o fuso horário do processo ou o da coluna. Ao consultar, o resultado usa o fuso horário da coluna, a menos que seja fornecido um override por coluna com o argumento column_tzs. O argumento query_tz não substitui o fuso horário declarado de uma coluna.

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 transmite um arquivo local para uma tabela existente em fluxo e delega o parsing ao ClickHouse.

Configurações de formato de entrada, como input_format_allow_errors_ratio e input_format_allow_errors_num, podem ser passadas por meio de 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 um AsyncClient, use await com insert_file_async e os mesmos argumentos:

from clickhouse_connect.driver.tools import insert_file_async

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

O helper assíncrono lê o arquivo em uma thread de trabalho antes de aguardar o raw_insert, portanto o conteúdo do arquivo permanece na memória.