httk.store.db.clickhouse

ClickHouse-specific SQLAlchemy decoration and KeeperMap primitives.

The rest of httk.store.db deliberately deals in generic SQLAlchemy objects. This module is the adapter boundary for ClickHouse’s physical types, MergeTree sorting keys, system catalogue, and KeeperMap metadata protocol.

Exceptions

ClickHouseUnsupportedQueryError

A ClickHouse query is outside the shipped correlated-query profile.

Functions

null_safe_difference(left, right)	The ClickHouse S9 comparator (true precisely when values differ).
null_order_rank(column, nulls, *, dialect_name)	Return a deterministic NULL/NaN rank for one result-order expression.
load_parquet_stages(store, manifests)	Create and stream every Parquet shard into local ClickHouse stage tables.
swap_finalizer_map(finalizer, table, candidate)	Atomically replace a finalizer map and update its bookkeeping.
validate_bulk_tables(connection, tables)	Validate ClickHouse's non-enforcing physical and logical constraints.
verify_bulk_integrity(connection, tables)	Run the SQLAlchemy-metadata-derived logical constraints ClickHouse cannot enforce.
keeper_metadata_path(database_uuid)	Return the KeeperMap path scoped by the ClickHouse database UUID.
keeper_database_uuid(connection)	Return the stable UUID assigned to the current ClickHouse database.
decorate_table(table, *[, database, database_uuid])	Return a decorated private clone; the source table is never modified.
verify_clickhouse_connection(connection)	Verify version and the NULL-producing outer-join setting on one connection.
install_connection_guards(engine)	Install pool checkout verification and return the first server version.
acquire_lease(connection, owner)	Strictly acquire the store lease and return its complete JSON value.
verify_lease(connection, lease_value)	Verify that the current KeeperMap lease still contains lease_value.
release_lease(connection, lease_value)	Idempotently delete only the exact lease value owned by this writer.
write_ingest_marker(connection, lease_value)	Strictly insert the token-carrying bulk-ingest marker.
clear_ingest_marker(connection, marker_value)	Idempotently clear only the exact marker value from this ingest.
ensure_bootstrap_table(engine)	Require and validate the deployment-created KeeperMap bootstrap table.
bootstrap_fence(connection)	Hold the strict UUID-keyed bootstrap fence across one complete operation.
stamp_store_metadata(connection, metadata_table, rows, *)	Strictly stamp metadata, acquiring the bootstrap fence unless already held.
validate_metadata_table(connection)	Validate the physical KeeperMap metadata table before any metadata read.
actual_schema_objects(connection)	Read the current database's application objects from ClickHouse's catalogue.
actual_columns(connection, table_name)	Return a ClickHouse system.columns name/type mapping for one table.

Module Contents

exception httk.store.db.clickhouse.ClickHouseUnsupportedQueryError

Bases: httk.store.query.UnsupportedQueryError

A ClickHouse query is outside the shipped correlated-query profile.

httk.store.db.clickhouse.null_safe_difference(left, right)

The ClickHouse S9 comparator (true precisely when values differ).

httk.store.db.clickhouse.null_order_rank(column, nulls, *, dialect_name)

Return a deterministic NULL/NaN rank for one result-order expression.

httk.store.db.clickhouse.load_parquet_stages(store, manifests)

Create and stream every Parquet shard into local ClickHouse stage tables.

Every shard is verified by its before/after row count. This makes a transport retry or a response lost after send observable before the next shard is admitted.

httk.store.db.clickhouse.swap_finalizer_map(finalizer, table, candidate)

Atomically replace a finalizer map and update its bookkeeping.

ClickHouse has no transactional UPDATE protocol for this use. The candidate is checked for the same stage key cardinality, renamed over the old name in one RENAME statement, and the retired relation is dropped. Keeping the public map name stable means every already-constructed query continues to address the current map.

httk.store.db.clickhouse.validate_bulk_tables(connection, tables)

Validate ClickHouse’s non-enforcing physical and logical constraints.

httk.store.db.clickhouse.verify_bulk_integrity(connection, tables)

Run the SQLAlchemy-metadata-derived logical constraints ClickHouse cannot enforce.

httk.store.db.clickhouse.keeper_metadata_path(database_uuid)

Return the KeeperMap path scoped by the ClickHouse database UUID.

httk.store.db.clickhouse.keeper_database_uuid(connection)

Return the stable UUID assigned to the current ClickHouse database.

httk.store.db.clickhouse.decorate_table(table, *, database='default', database_uuid=None)

Return a decorated private clone; the source table is never modified.

httk.store.db.clickhouse.verify_clickhouse_connection(connection)

Verify version and the NULL-producing outer-join setting on one connection.

httk.store.db.clickhouse.install_connection_guards(engine)

Install pool checkout verification and return the first server version.

httk.store.db.clickhouse.acquire_lease(connection, owner)

Strictly acquire the store lease and return its complete JSON value.

httk.store.db.clickhouse.verify_lease(connection, lease_value)

Verify that the current KeeperMap lease still contains lease_value.

httk.store.db.clickhouse.release_lease(connection, lease_value)

Idempotently delete only the exact lease value owned by this writer.

httk.store.db.clickhouse.write_ingest_marker(connection, lease_value)

Strictly insert the token-carrying bulk-ingest marker.

httk.store.db.clickhouse.clear_ingest_marker(connection, marker_value)

Idempotently clear only the exact marker value from this ingest.

httk.store.db.clickhouse.ensure_bootstrap_table(engine)

Require and validate the deployment-created KeeperMap bootstrap table.

httk.store.db.clickhouse.bootstrap_fence(connection)

Hold the strict UUID-keyed bootstrap fence across one complete operation.

httk.store.db.clickhouse.stamp_store_metadata(connection, metadata_table, rows, *, fence_held=False)

Strictly stamp metadata, acquiring the bootstrap fence unless already held.

httk.store.db.clickhouse.validate_metadata_table(connection)

Validate the physical KeeperMap metadata table before any metadata read.

httk.store.db.clickhouse.actual_schema_objects(connection)

Read the current database’s application objects from ClickHouse’s catalogue.

httk.store.db.clickhouse.actual_columns(connection, table_name)

Return a ClickHouse system.columns name/type mapping for one table.