Glossary

C

chdb

Embedded ClickHouse engine that runs in-process. No server needed — pip install aaiclick includes it. Used when AAICLICK_CH_URL starts with chdb://.

ColumnInfo

Schema definition for a single column: ClickHouse type string (e.g. "Int64", "Array(String)") plus nullable flag.

Computed

NamedTuple with type and expression fields, used with with_columns() to add SQL expression columns to a View. Import from aaiclick.data.models.

D

data_context()

Async context manager that manages Object lifecycle. Creates a ClickHouse client, tracks Objects via weakrefs, and marks them stale on exit. Entry point for all data operations.

DataResult

Return type of Object.data() — a union of scalar values, lists, and dicts depending on the Object's fieldtype.

F

Fieldtype

Metadata tag ('s', 'a', 'd') stored as a YAML comment on each column. Indicates whether the Object holds a scalar, array, or dict.

G

GroupByQuery

Returned by obj.group_by("key"). Supports aggregation (.sum(), .mean(), etc.) and .having() filters. Returns a dict Object.

L

LazyOperator

Subclass of Object returned by every binary dunder on an Object (a + b, a == b, a & b, etc.). Captures the operation plan (lhs, rhs, operator, precomputed result schema) and defers the ClickHouse CREATE TABLE + INSERT INTO ... SELECT until the LazyOperator is awaited. .as_(name, scope=...) controls the result table name and lifetime. See Object API → Lazy Operator Results.

M

MergeTree

Default ClickHouse table engine for persistent objects. Stores data on disk with efficient columnar compression. Temporary objects use Memory engine by default.

O

Object

Python wrapper for a ClickHouse table. Each Object instance corresponds to one table. Supports operator overloading (+, -, *, .mean(), .group_by()) that creates new tables with results. Becomes stale when its data_context() exits.

open_object()

Reopens an existing persistent Object by name in a new data_context(). Loads the schema from ClickHouse. Raises RuntimeError if the table doesn't exist.

P

Persistent Object

An Object created with name= parameter. Stored with a p_ table prefix, uses MergeTree engine, and survives data_context() exits. Reopen with open_object().

S

Scalar Broadcast

Automatic conversion of Python scalars (int, float, bool, str) to single-value Objects in binary operations. Both obj * 2 and 2 * obj work.

Schema

Dataclass holding an Object's column definitions, fieldtype, engine, and ordering. Passed to create_object() or inferred automatically by create_object_from_value().

Snowflake ID

Timestamp-encoded unique identifier — globally unique 64-bit ID with millisecond-precision timestamp. aaiclick uses Snowflake IDs to mint table names (t_<snowflake>) and as the advisory-lock key for cross-process insert serialisation.

V

View

Read-only filtered projection of an Object — references the same table, no data copy. Created via obj.view(), obj.where(), obj["col"], obj.with_columns(), or obj.explode(). Supports all read operations but cannot insert().