ClickHouseDest

class

class ClickHouseDest(
    tables: ClickHouseTableNamesSpec,
    if_table_exists: IfTableExistsSpec = 'append',
    schema_evolution: SchemaEvolutionSpec = 'strict',
    dest_cfg: DestCfgSpec | None = None,
)

Bases: Dest

Categories: destination

ClickHouse destination for @subscriber -- one output slot per table.

Examples

Write a table with the replace disposition -- the first run creates it, later runs drop and recreate it (row count stays):

@subscriber(
    destination=ClickHouseDest(
        tables=["cap_replace"],
        if_table_exists="replace",
    ),
    input_tables=["caps_input/cap_rows"],
)
def out_replace(rows: TableFrameSpec) -> TableFrameSpec:
    return rows

Append rows with a wider schema and let ClickHouse evolve the table -- schema_evolution="iceberg" adds the new column rather than failing on the mismatch ("strict" would reject it):

@subscriber(
    destination=ClickHouseDest(
        tables=["cap_evolve"],
        if_table_exists="append",
        schema_evolution="iceberg",
    ),
    input_tables=["caps_input/cap_evo_v2"],
)
def evolve(rows: TableFrameSpec) -> TableFrameSpec:
    return rows

Parameters

parameter

tablesClickHouseTableNamesSpec (list[str])

Target table names (non-empty), one write slot per entry. Each is a 1- or 2-part name (table or database.table); backtick-quote a part for special characters.

parameter

if_table_existsIfTableExistsSpec (Literal['append', 'replace'])

"append" (the default) adds rows; "replace" overwrites the table.

parameter

schema_evolutionSchemaEvolutionSpec (Literal['strict', 'iceberg'])

"strict" (the default) rejects schema changes; "iceberg" applies Iceberg-style schema deltas.

parameter

dest_cfgDestCfgSpec | None (Mapping[Literal['clickhouse.logging_level'], Any] | None)

Optional connector config; the only supported key is clickhouse.logging_level.

Methods

method

validate

def validate()

Cross-field validation: tables must be non-empty.

Called by the framework; raises ClickHouseValidateException.