Cognitive Schema

DeclarativeAdditiveOn by Default

Stable On by default · production-ready — enable with enable_nervous_system = true · on by default; disable with --disable-nervous-system

What it is

AetheriusDB already lets you declare intent at schema time — time horizons, measures and dimensions, table classes. The Cognitive Schema extends that idea to the one thing the engine otherwise re-discovers on every query: the shape of the workload itself.

Everything here is declarative and additive. A table with no declarations behaves exactly as before, so nothing you declare can make a query fail. Declarations are stored in the catalog, survive restart, and are consulted while the feature is enabled (the default).

Why it matters

Without a declarative layer, the engine re-parses the SQL, rebuilds the predicate, and re-allocates intermediate state for a pattern you already knew was coming. Declaring the pattern lets the engine skip that work — and for some shapes, skip touching raw rows entirely.

• Skip planning on known shapes — a matching query reuses a pre-built plan instead of re-planning.
• Report from aggregates, not rows — a maintained aggregate is updated during ingest, so a matching GROUP BY reads a small matrix instead of scanning the table.
• Pre-built join topology — declared affinity edges pre-build the inter-table index between two tables.
• Backward compatible — zero declarations means today’s behavior, exactly.

The dimensions of intent

The Cognitive Schema covers several independent dimensions of workload intent:

Clause	What it declares
WITH SYNAPTIC PATTERN	The query shapes a table will see, so matching queries reuse a cached plan.
CREATE COORDINATE AFFINITY EDGE	A pre-built join path between two tables.
WITH PROJECTION	A running aggregate; matching GROUP BY reports read it instead of raw rows.
WITH VELOCITY	Lifecycle hints so hot data stays aligned and aged data is compressed along a decay curve.

How you use it

Declarations attach to CREATE TABLE via WITH clauses (in any order), or as standalone DDL.

-- Declare the query shapes this table will see.
CREATE TABLE orders ( order_id BIGINT, customer_id BIGINT, region INT )
WITH SYNAPTIC PATTERN point_lookup ( COLUMNS = ('order_id'), OPS = ('='), WEIGHT = 95 )
WITH SYNAPTIC PATTERN by_region    ( COLUMNS = ('region'),   OPS = ('='), WEIGHT = 4  );

-- Maintain a running aggregate; matching reports read the matrix.
CREATE TABLE sales ( region INT, amount DOUBLE )
WITH PROJECTION rev ( DIMS = ('region'),
                      MEASURES = (SUM(amount), COUNT(amount), AVG(amount)) );

SELECT region, SUM(amount) FROM sales GROUP BY region;   -- reads the aggregate

-- Pre-build the join topology between two tables.
CREATE COORDINATE AFFINITY EDGE orders_lineitems
    FROM orders(id) TO lineitems(order_id)
    WITH (GRAVITY = 'pre_stitched', FREQUENCY = 'high');

-- See which path a query takes:
EXPLAIN SELECT * FROM orders WHERE order_id = 7;

Patterns can be added and removed at runtime. ALTER TABLE orders ADD SYNAPTIC PATTERN … starts accelerating matching queries immediately, and DROP SYNAPTIC PATTERN reverts them to the standard path and releases the pre-built artifact.

flowchart TD
  classDef a fill:#1f2640,stroke:#7c5cff,color:#e8eaf0
  classDef n fill:#1f2640,stroke:#4ade80,color:#4ade80
  classDef r fill:#1f2640,stroke:#00d4ff,color:#e8eaf0

  Q[Query arrives]:::a --> FP[Structural fingerprint<br/>columns + ops, no literals]:::a
  FP --> M{Matches a declared<br/>Synaptic Pattern?}:::a
  M -->|yes| NP[Reuse pre-built plan]:::n
  M -->|no| RP[Standard plan + execute]:::r
  NP --> OUT[Result]
  RP --> OUT[Result]

Observability

Each dimension has a catalog view you can query to see what’s declared and how often it’s being used:

SELECT * FROM system.synaptic_patterns;
SELECT * FROM system.coordinate_affinity_edges;
SELECT * FROM system.projection_cubes;
SELECT * FROM system.cognitive_metrics;

Enabling & disabling

The feature is on by default. To make declarations inert — they stay stored, but every read takes the plain path, which is useful for A/B comparisons — boot with:

aetheriusd --disable-nervous-system   -- or AETHERIUS_DISABLE_NERVOUS_SYSTEM=1

Aggregates stay correct across mutation

Because MIN/MAX have no inverse, an UPDATE or DELETE to a table with a maintained aggregate marks it stale; the next matching report does a one-time re-aggregation before resuming fast maintenance. A maintained aggregate never returns a value inconsistent with a full re-scan. Append-only tables stay on the fast path.

What is not in v1

The decision and maintenance logic ships and is exercised on a single node. Some payoffs depend on multi-node and specialized hardware that this release does not require. Active learning that proposes patterns from observed traffic is a v2 feature — in v1 you declare patterns yourself.

Catalog & Metadata →

Where declarations are stored and surfaced as system views.

Relational Data Model →

Measure and dimension tables you declare alongside these clauses.

Query Data →

Runtime statistics that complement declared workload shape.