Data and service model

Terms

Term	Meaning
Data service	A published, queryable contract. Its type is time series, event, or lookup.
Contextual event	One occurrence of a happening under a published event collection: what it is (type, facets, titles), when, where — every site of a multi-site happening as sites[], site 1 being the epicenter — who (participants) and with what (media).
Time series	A definition for observations with declared time and measurement semantics.
Time-series family	One measurement concept with interchangeable concrete variants by source, publisher, publication, native resolution, or data-quality grade.
Time-series variant	The independently published, stored, secured, and queryable time series selected from a family.
Observation / data point	A row owned by one published time series.
Event feed	A published event collection with declared occurrence types and fields.
Event occurrence	One concrete, bounded event row owned by an event feed.
Lookup	An on-demand service that resolves supplied values and returns typed fields.
Catalogue master	A reusable entity, unit, metric, dimension, source binding, or series group.
Source adapter	Read-only inventory describing an approved executable source, such as a CTX FDW relation.
Source binding	The limits and source mode selected by a service definition.
Service contract	The accepted inputs and selectable outputs of a published service.
Draft	Editable catalogue state that consumers cannot see.
Published revision	Immutable snapshot accepted for delivery.
Publication	Delivery record for a revision's ClickHouse projection or semantic event.
Saved context	Account or personal preferred navigation with a type-specific data-service, time-series, or event definition.

Ownership and storage

Data	Authoritative store	Notes
Drafts, grants, revisions, and publication records	CTX PostgreSQL, schema ql	Controls authoring and access.
Published catalogue projections	ClickHouse catalogue tables	Used by analytical consumers.
Stored observations	ClickHouse cst.data_points	Written only through a published stored time series.
Stored event occurrences	ClickHouse ql.calendar_events	Written only through a published stored event feed.
On-demand results	ClickHouse cst.data_points / ql.calendar_events + coverage in ql.source_coverage	CTX adapters execute through PostgreSQL FDW; fetched rows are stored next to the stored rows and read back through CTX. No result data in PostgreSQL.
Lookup answers	ClickHouse ctx.resolver_cache (inside CTX)	Cached once at the source layer for the period each relation declares.
Saved-context navigation and filters	CTX PostgreSQL, schema ql	Account/user preferences; periods and locations are supplied at query time.

PostgreSQL is the source of truth for definitions. ClickHouse holds published projections and customer rows. Restoring one store does not reconstruct the other automatically.

Source modes

stored : QuickLookup owns the rows in ClickHouse. No adapter, FDW relation, or external provider runs when the service is queried. Only stored time series and event feeds accept ingestion.

on_demand : QuickLookup validates the request against the published contract and runs an approved adapter. CTX-backed adapters execute an allowlisted PostgreSQL FDW relation. Fetched windows are stored in ClickHouse and served from there while their coverage is valid; only the gaps of a window are fetched again.

Both modes use catalogue discovery and POST /v1/services/{serviceGid}/query. Their write paths and failure modes differ.

Relationships

grouped data service
└── time-series family
    └── concrete variant ── owns ── observations

standalone time-series family
└── concrete variant ── owns ── observations

event feed ── owns ── event occurrences

lookup service ── executes ── lookup adapter

Metrics, dimensions, units, entities, source bindings, and series groups can be reused. Publishing a time series or event feed derives its contract from the selected source and declared fields. A grouped service uses a contract compatible with all of its members.

SeriesGroup is the family identity. TimeSeries is the concrete variant and remains the identity used by paging, caching, ClickHouse rows, FDW requests, and result provenance. QuickLookup recommends one authorized variant but never merges observations or silently changes an explicit selection.

Saved context sits above these catalogue and occurrence layers without flattening them. Time-series context resolves a catalogue collection of families. Event context resolves and pages concrete occurrences across selected feeds. Only navigation metadata and account/personal ownership are shared.