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](object.md#lazy-operator-results-a--b-is-a-plan-not-a-table).

# 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()`.
