pathwaycom/pathway · error · ValueError

output_table_type='snapshot' requires the primary_key parame

Error message

output_table_type='snapshot' requires the primary_key parameter: pass the column(s) that identify each row so the connector can maintain the current snapshot keyed by them.

What it means

Error "output_table_type='snapshot' requires the primary_key parameter: pass the column(s) that identify each row so the connector can maintain the current snapshot keyed by them." thrown in pathwaycom/pathway.

Source

Thrown at python/pathway/io/clickhouse/__init__.py:246

    _check_entitlements("clickhouse")

    is_snapshot_mode = output_table_type == SNAPSHOT_OUTPUT_TABLE_TYPE

    column_names = set(table.schema.column_names())
    metadata_columns = (
        {"version", "is_deleted"} if is_snapshot_mode else {"time", "diff"}
    )
    reserved = metadata_columns & column_names
    if reserved:
        raise ValueError(
            f"Column name(s) {sorted(reserved)!r} collide with the reserved "
            f"{sorted(metadata_columns)!r} metadata columns appended by "
            "pw.io.clickhouse.write. Rename the column(s) in your schema before writing."
        )
    key_field_names: list[str] | None = None
    if is_snapshot_mode:
        if primary_key is None or not list(primary_key):
            raise ValueError(
                "output_table_type='snapshot' requires the primary_key parameter: "
                "pass the column(s) that identify each row so the connector can "
                "maintain the current snapshot keyed by them."
            )
        key_field_names = [column.name for column in primary_key]
    elif primary_key is not None:
        raise ValueError(
            "The primary_key parameter is only used with output_table_type='snapshot'; "
            "remove it or set output_table_type='snapshot'."
        )

    data_storage = api.DataStorage(
        storage_type="clickhouse",
        connection_string=connection_string,
        table_name=table_name,
        max_batch_size=max_batch_size,
        table_writer_init_mode=init_mode_from_str(init_mode),
        snapshot_maintenance_on_output=is_snapshot_mode,

View on GitHub (pinned to fa2f74a464)

Solutions

1. Pass primary_key=[...] with the identifying columns when output_table_type='snapshot'.

Example fix

pw.io.clickhouse.write(t, ..., output_table_type='snapshot', primary_key=[t.k])

When it happens

Trigger: Thrown at python/pathway/io/clickhouse/__init__.py:246 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of pathwaycom/pathway@fa2f74a464 (2026-08-15). Data as JSON: /api/errors/c11b67e6c8acb84c. Report an issue: GitHub.