Introduction

Nervix is experimental software in active development. It is intended for evaluation, local testing, and design exploration. It is not suitable for real production workloads.

Nervix is a realtime stream processing system with a robust declarative DSL for defining data-flow graphs.

Nervix stream processing Language (NSPL) is used to declare the schemas, connections, runtime nodes, and external integrations that make up a Nervix graph:

• schemas
• wire schemas
• codecs
• relays
• clients
• ingestors
• processors
• emitters
• vhosts
• endpoints

NSPL has reached alpha. Its period of rapid, broad experimentation is over, so large backward-incompatible language changes are no longer expected. The language will continue to evolve, however, and focused breaking changes may still occur. See Language Stability for the current compatibility policy.

The core runtime model is a graph of connected nodes:

• ingestors bring data into the system
• relay owners route data, while processors, junctions, deduplicators, and reingestors transform it
• emitters push results out to external systems

Current built-in transport integrations include Kafka, Pulsar, HTTP, Prometheus, RabbitMQ, Redis, MQTT, NATS, ZeroMQ, SQS, and WebSockets, with Sentry event-envelope emission over HTTP.

The connections between nodes are expressed through RELAYs.

Input data often mixes tenants, users, devices, accounts, or other business groups in the same external feed. Nervix uses explicit CREATE BRANCH declarations to process those groups independently. A branch names the key schema, such as CREATE BRANCH by_tenant_user SCHEMA tenant_user_branch TTL 5m; ingestor and reingestor routes construct concrete keys with BRANCHED BY by_tenant_user SET ....

RELAYs are scheduled runtime nodes between producers and consumers. Each has one owner that holds its buffer, concrete branch presence, fan-out, and metrics. Relays are declared as BRANCHED BY <branch> or UNBRANCHED; only ingestors and reingestors carry the key mapping that constructs concrete branch identities. Processing state remains isolated by that identity, while one relay owner coordinates its cluster-wide buffering and delivery. An emitter drains records out of the graph. A reingestor can compute a new group and start downstream branches under that grouping.

Nervix already runs clustered deployments, schedules graph nodes across multiple servers, executes codecs in the runtime, replicates selected runtime state, and supports multi-node failover scenarios. It is still evolving, but it is beyond a parser-only prototype.

This book is split into six sections:

• Quickstart: running Nervix and building your first graphs step by step
• Client Tools: the command line client and the browser console
• Manual: how to use Nervix’s public surface
• Rust WASM Guest SDK: writing custom WASM processor guests in Rust
• Architecture And Internals: control-plane, data-plane, and runtime implementation details
• Developing Nervix: working on Nervix itself from a repository clone

Start with the quickstart if you are new to Nervix, and with the manual unless you are specifically trying to understand internals. Agents can start with the portable NSPL Agent Skill.

Nervix is licensed under the Fair Core License (FCL). See License.

Quickstart

Nervix is experimental software in active development. It is intended for evaluation, local testing, and design exploration. It is not suitable for real production workloads.

This section takes you from nothing to a running Nervix graph. It is a hands-on tutorial: each step is a small, complete change that you apply to a live single-node cluster and verify before moving on. You build one graph throughout — it starts as a trivial pass-through pipeline and grows into a branched graph with conditional routing and structured error handling.

• Installation: getting Nervix onto your machine
• Running Nervix: starting a single-node server, connecting a client, and starting the Kafka and Redis containers the tutorial talks to
• Your First Pipeline: Kafka To Redis: read JSON orders from a Kafka topic and publish them to a Redis Pub/Sub channel
• Conditional Routing: split the stream with a junction, route filters, and computed fields
• Branched Processing: partition the stream per customer and deduplicate independently inside each branch
• Error Routes: capture failing records as structured errors on a dead-letter relay
• HTTP Ingestion: POST records straight at the server through a vhost-hosted endpoint
• JAQ Transformations: reshape foreign JSON at the boundary with a jq-style codec
• Protobuf Codecs: decode binary payloads from uploaded .proto definitions
• User-Defined Functions: package expression logic as a reusable compiled Roto function
• Window Aggregates: summarize the stream with per-customer sliding windows
• Generators: emit periodic records from materialized relay state
• Correlators: join orders with payments across two streams
• Altering A Running Graph: change routing logic and evolve schemas without tearing anything down
• Paced Domains: replay timestamped history on an accelerated domain clock

Every page links the Manual chapter that documents each feature in full: the tutorial shows one working path, and the manual holds the reference.

Installation

Install the server and CLI from GitHub:

cargo install --locked \
  --git https://github.com/nervix-io/nervix.git \
  nervix-server nervix-cli

Ensure Cargo’s binary directory, $HOME/.cargo/bin by default, is on your PATH.

See Installation for prerequisites, reproducible Git revisions, a three-node Docker deployment, and the Kubernetes Operator installation.

Running Nervix

This page starts everything the tutorial needs on your local machine: one Nervix node, a Kafka broker, and a Redis server.

Start The Server

A Nervix node is a single nervix-server process. From a repository checkout, create the local development identity and start a fresh single-node cluster:

just generate-dev-tls
nervix-server \
  --node-id node-1 \
  --interconnect-listen-addr 127.0.0.1:47392 \
  --interconnect-advertise-addr 127.0.0.1:47392 \
  --interconnect-tls-ca tls/dev/ca.pem \
  --interconnect-tls-cert tls/dev/node.pem \
  --interconnect-tls-key tls/dev/node-key.pem \
  --allow-bootstrap \
  --init-default-user-password nervix

• --node-id names this node inside the cluster.
• The interconnect address and TLS files configure the mandatory authenticated HTTP/2 listener; a single local node points its listener and advertised address at the same local port.
• --allow-bootstrap lets this node form a brand-new cluster instead of joining an existing one.
• --init-default-user-password seeds the default user’s password on the very first startup. Once the user exists, remove the flag from normal startup.

Every flag has a NERVIX_* environment variable twin, such as NERVIX_NODE_ID. Control-plane state is persisted under ./.nervix-db by default; use --db-path to relocate it. The directory contains the node database for registry and runtime state and a separate consensus database whose journal carries only Raft state.

The server exposes:

• the session gRPC API on 127.0.0.1:47391 (--addr), used by nervix-cli and the Rust client library
• the web console at http://127.0.0.1:47420/console/, which combines a command line with a live graph view
• health and metrics endpoints on port 9090: /livez, /readyz, and /metrics (Metrics And Observability)

Stop The Server

Press Ctrl-C, or send the process SIGTERM, to stop the node. The first SIGINT or SIGTERM starts graceful shutdown: the node advertises that its process is terminating, stops admitting new work, closes the client connections it had accepted, and runs its shutdown phases, logging whether each one completed or abandoned work. The process exits with status 0 once graceful shutdown finishes, or prints the error and exits with status 1 when a listener or a shutdown step failed.

Graceful shutdown must finish within the shutdown timeout, --shutdown-timeout (NERVIX_SHUTDOWN_TIMEOUT), which defaults to 50s and is measured from the first signal. When it passes, the process logs the shutdown phase it had reached and exits at once with status 1. Nothing extends that deadline: a client that holds an upload or a session open does not, and a later signal can only end the process sooner.

A second SIGINT or SIGTERM abandons graceful shutdown and ends the process immediately, without running the phases that remain. The process exits with status 130 when the second signal is SIGINT and 143 when it is SIGTERM, the statuses a shell reports for a process those signals terminate. Work still in progress is lost exactly as it is when the process crashes; SIGKILL always ends the process that way.

The server registers both signals before it starts anything else. A signal that arrives while the node is still starting takes effect as soon as startup completes, while its shutdown deadline runs from the moment the signal arrived. A node that cannot register the signals refuses to start.

Shutdown And Recovery describes the phases, what the node drains before it exits, what each ending preserves, and how to read a shutdown that did not finish.

Connect A Client

nervix-cli is the interactive NSPL client. With no arguments it connects to http://127.0.0.1:47391 as user default and prompts for the password:

nervix-cli

nervix[default]> SHOW CLUSTER STATUS;

Statements end with ;, and the prompt shows the active domain. The same statements can be typed into the web console’s command line, or executed one-shot with nervix-cli --command "<statements>". There is no file-execution mode: to run a saved script, paste it into the client or pass it through --command "$(cat pipeline.nspl)". To format a saved script, use nervix-nspl-format.

Start Kafka And Redis

The tutorial reads from Kafka and publishes to Redis. Any reachable Kafka broker and Redis server work; for a throwaway local setup:

docker run -d --name broker -p 9092:9092 apache/kafka:latest
docker run -d --name redis -p 6379:6379 redis:7

If you work from a repository clone, just deps starts a complete local dependency stack instead (Developing Nervix).

Nervix never creates topics, queues, or any other external entities as a side effect of running a graph. Missing entities surface as initialization or publish errors, so the tutorial provisions its Kafka topic explicitly before ingesting from it.

Continue to Your First Pipeline: Kafka To Redis.

Your First Pipeline: Kafka To Redis

The first graph is deliberately trivial: JSON order records arrive on a Kafka topic, Nervix decodes them, and an emitter publishes them to a Redis Pub/Sub channel. Along the way you meet every building block that later steps reuse: domains, schemas, codecs, relays, clients, ingestors, and emitters.

Provision The Topic

Nervix never creates external entities, so create the Kafka topic first:

docker exec broker /opt/kafka/bin/kafka-topics.sh \
  --create --topic orders --bootstrap-server localhost:9092

Create A Domain

Every entity in Nervix lives in an explicit domain — there is no implicit default. Open nervix-cli and create one, then switch the session to it:

CREATE UNPACED DOMAIN quickstart;

USE quickstart;

An unpaced domain admits records as they arrive, with no domain clock pacing — the right choice for a first pipeline. See Domains And Time. USE is a client-local statement that scopes the rest of your session to the domain.

Open A Transaction

Submitting more than one model statement at a time requires a transaction, and it is also how a graph is assembled atomically — nothing takes effect until COMMIT;. See NSPL Overview for the statement surface.

BEGIN;

The graph declarations in the rest of this page run inside this transaction.

Describe The Data

Nervix separates what a record looks like inside the graph from how it is serialized on the wire. The internal schema is exact-typed; the wire schema describes the JSON payload in the wire format’s own type names; the codec bridges the two. See Schemas And Codecs.

CREATE SCHEMA order_record (
  order_id STRING,
  customer STRING,
  status STRING,
  amount I64,
  quantity I64
);

CREATE WIRE JSON SCHEMA order_wire MODE STRICT (
  order_id string,
  customer string,
  status string,
  amount integer,
  quantity integer
);

CREATE CODEC order_codec
  FROM WIRE JSON SCHEMA order_wire
  TO SCHEMA order_record;

STRICT rejects payload fields that are not declared; LOOSE would drop them instead (Wire Schemas). There are no implicit casts anywhere in Nervix, so the codec is the only place where wire values become typed internal values. A DATETIME field would additionally need an explicit encoding such as ENCODE created_at AS RFC3339 (Codecs).

Create A Relay

Relays are the named streams that connect runtime nodes. Each relay carries records of exactly one schema. See Streams And State.

CREATE RELAY orders SCHEMA order_record UNBRANCHED;

UNBRANCHED means one shared stream. Branched Processing introduces the alternative.

Declare The External Connections

Connection endpoints never live on ingestors or emitters; they are named CLIENT objects that nodes reference. Kafka client config is passed through to the Kafka driver, so bootstrap.servers uses its familiar key.

CREATE CLIENT kafka_local
  TYPE KAFKA
  CONFIG {
    'bootstrap.servers' = '127.0.0.1:9092'
  };

CREATE CLIENT redis_local
  TYPE REDIS
  POOL SIZE MIN 1 MAX 4
  CONFIG {
    'addr' = 'redis://127.0.0.1:6379/'
  };

Ingest From Kafka

An ingestor brings external data into the graph. It decodes each payload with the codec and routes the result to a relay:

CREATE KAFKA TOPIC INGESTOR kafka_orders
  FROM kafka_local
  TOPIC 'orders'
  OFFSET BY CONSUMER GROUP 'quickstart'
  MODE ACK SEQUENTIAL ACK TIMEOUT 30s RETRY POLICY BACKOFF 200ms MAX 5s
  ON QUIESCE SUSPEND DECODE USING order_codec
  TO orders
    INHERIT ALL
    UNBRANCHED
    FLUSH EACH 100ms MAX BATCH SIZE 1MiB
    ON MESSAGE ERROR LOG
  ON GENERAL ERROR LOG;

Reading top to bottom:

• KAFKA TOPIC INGESTOR names the connector and the entity the ingestor reads. FROM names the TYPE KAFKA client, and the topic and consumer group are string literals sent to Kafka exactly as written.
• OFFSET BY CONSUMER GROUP tracks progress in Kafka; MODE ACK SEQUENTIAL acknowledges records in order. The full Kafka source grammar is in Supported Ingestor Types.
• TO orders starts a route. Routes begin empty: INHERIT ALL copies every decoded field into the outgoing record, and later steps show SET constructing new values. See The Working Message.
• Every route needs an explicit flush policy — FLUSH EACH <duration> MAX BATCH SIZE <bytes> or FLUSH IMMEDIATE. There are no hidden defaults.
• ON MESSAGE ERROR LOG is the route’s per-record error policy; ON GENERAL ERROR LOG is the node-wide policy (Runtime Node Error Policies).

Emit To Redis

An emitter drains a relay out of the graph. The Redis integration is Pub/Sub (Supported Emitter Sinks), and the same codec that decoded the input encodes it back to JSON:

CREATE EMITTER redis_orders
  FROM orders
  TO REDIS PUBSUB redis_local CHANNEL orders_out
    MODE NO_ACK RETRY POLICY BACKOFF 250ms MAX 30s
    ENCODE USING order_codec
  INHERIT ALL
  FLUSH EACH 100ms MAX BATCH SIZE 1MiB
  ON MESSAGE ERROR LOG
  ON GENERAL ERROR LOG;

Redis Pub/Sub exposes no delivery confirmation, so MODE NO_ACK names server acceptance as the publish boundary. The required retry policy paces connection and other infrastructure failures; it does not turn subscriber presence into an acknowledgment.

Commit And Start

COMMIT; applies the structural changes: the whole graph is validated and installed atomically. Nothing processes data yet — that is the job of START;, the domain lifecycle command that begins actual work (Start And Stop):

COMMIT;

START;

The Complete Script

CREATE UNPACED DOMAIN quickstart;

USE quickstart;

BEGIN;

CREATE SCHEMA order_record (
  order_id STRING,
  customer STRING,
  status STRING,
  amount I64,
  quantity I64
);

CREATE WIRE JSON SCHEMA order_wire MODE STRICT (
  order_id string,
  customer string,
  status string,
  amount integer,
  quantity integer
);

CREATE CODEC order_codec
  FROM WIRE JSON SCHEMA order_wire
  TO SCHEMA order_record;

CREATE RELAY orders SCHEMA order_record UNBRANCHED;

CREATE CLIENT kafka_local
  TYPE KAFKA
  CONFIG {
    'bootstrap.servers' = '127.0.0.1:9092'
  };

CREATE CLIENT redis_local
  TYPE REDIS
  POOL SIZE MIN 1 MAX 4
  CONFIG {
    'addr' = 'redis://127.0.0.1:6379/'
  };

CREATE KAFKA TOPIC INGESTOR kafka_orders
  FROM kafka_local
  TOPIC 'orders'
  OFFSET BY CONSUMER GROUP 'quickstart'
  MODE ACK SEQUENTIAL ACK TIMEOUT 30s RETRY POLICY BACKOFF 200ms MAX 5s
  ON QUIESCE SUSPEND DECODE USING order_codec
  TO orders
    INHERIT ALL
    UNBRANCHED
    FLUSH EACH 100ms MAX BATCH SIZE 1MiB
    ON MESSAGE ERROR LOG
  ON GENERAL ERROR LOG;

CREATE EMITTER redis_orders
  FROM orders
  TO REDIS PUBSUB redis_local CHANNEL orders_out
    MODE NO_ACK RETRY POLICY BACKOFF 250ms MAX 30s
    ENCODE USING order_codec
  INHERIT ALL
  FLUSH EACH 100ms MAX BATCH SIZE 1MiB
  ON MESSAGE ERROR LOG
  ON GENERAL ERROR LOG;

COMMIT;

START;

Send An Order

Subscribe to the output channel in one terminal:

docker exec redis redis-cli SUBSCRIBE orders_out

Produce an order in another:

docker exec -i broker /opt/kafka/bin/kafka-console-producer.sh \
  --bootstrap-server localhost:9092 --topic orders

{"order_id":"o-1001","customer":"acme","status":"new","amount":1500,"quantity":3}

The Redis subscriber prints the record back as JSON. You can also watch any relay from inside Nervix with a read-only session subscription (Sessions):

nervix-cli --domain quickstart subscribe watch orders

The pipeline works end to end. Next, add logic to it in Conditional Routing.

Conditional Routing

The pass-through pipeline treats every order the same. This step adds a junction that splits the stream: high-value orders get a computed tier field and their own Redis channel, routine orders continue separately.

Everything here is additive. The domain keeps running while you apply it — a transaction of pure CREATE statements rebuilds the schedule without pausing the graph (Automatic Model-Alteration Quiescing).

The Enriched Record

Construction is exact-typed, so a record with an extra tier field is a different schema, with its own wire schema and codec for emission — the same pattern as the first pipeline:

BEGIN;

CREATE SCHEMA order_tiered (
  order_id STRING,
  customer STRING,
  status STRING,
  amount I64,
  quantity I64,
  tier STRING
);

CREATE WIRE JSON SCHEMA order_tiered_wire MODE STRICT (
  order_id string,
  customer string,
  status string,
  amount integer,
  quantity integer,
  tier string
);

CREATE CODEC order_tiered_codec
  FROM WIRE JSON SCHEMA order_tiered_wire
  TO SCHEMA order_tiered;

CREATE RELAY high_value_orders SCHEMA order_tiered UNBRANCHED;

CREATE RELAY routine_orders SCHEMA order_record UNBRANCHED;

Route With A Junction

A junction subscribes to one or more relays and fans records out to routes. Each route is an independent contract: its own construction, its own WHERE filter over the finalized output, its own flush policy. See Junction and The Working Message for the input/output scopes used below.

CREATE JUNCTION route_orders
  FROM orders
  UNBRANCHED
  TO high_value_orders
    INHERIT ALL
    SET tier = CASE
          WHEN input.amount >= 10000 THEN "vip"
          ELSE "high"
        END
    WHERE output.amount >= 1000
    FLUSH IMMEDIATE
    ON MESSAGE ERROR LOG
  TO routine_orders
    INHERIT ALL
    WHERE output.amount < 1000
    FLUSH EACH 1s MAX BATCH SIZE 1MiB
    ON MESSAGE ERROR LOG;

• SET initializes the one field INHERIT ALL cannot supply. Assignments run in order, and CASE/IF expressions are part of the expression language (Conditional Expressions).
• The route WHERE filters finalized records: output.amount is the value the route just constructed, while input.amount inside SET reads the incoming record.
• The orders relay now has two subscribers — the emitter from the first pipeline and this junction. Relays fan out to every subscriber (Streams And State).

Emit The High-Value Stream

CREATE EMITTER redis_high_value
  FROM high_value_orders
  TO REDIS PUBSUB redis_local CHANNEL high_value_out
    MODE NO_ACK RETRY POLICY BACKOFF 250ms MAX 30s
    ENCODE USING order_tiered_codec
  INHERIT ALL
  FLUSH EACH 100ms MAX BATCH SIZE 1MiB
  ON MESSAGE ERROR LOG
  ON GENERAL ERROR LOG;

COMMIT;

Watch The Split

Subscribe to the new channel:

docker exec redis redis-cli SUBSCRIBE high_value_out

Produce three orders with different amounts:

{"order_id":"o-1002","customer":"acme","status":"new","amount":250,"quantity":5}
{"order_id":"o-1003","customer":"globex","status":"new","amount":2500,"quantity":1}
{"order_id":"o-1004","customer":"acme","status":"new","amount":25000,"quantity":2}

o-1002 appears only on orders_out. o-1003 also appears on high_value_out with "tier":"high", and o-1004 with "tier":"vip".

Next: Branched Processing partitions this stream per customer.

Branched Processing

One external feed usually mixes many tenants, customers, or devices. Branches are how Nervix processes those groups independently: when a new group key appears, the branched part of the graph gets its own relay presence and processor state for that group, fully isolated from every other group. See Streams, Branch Keys, And Branches.

This step partitions orders per customer and deduplicates them inside each customer’s branch, so one customer’s duplicates can never suppress another customer’s orders.

Declare The Branch

A branch names its key schema and a TTL. When a branch instance goes idle for the TTL, its branch-local relay and processor state is dropped as a whole (TTL). In an unpaced domain the TTL uses wall clock time.

BEGIN;

CREATE SCHEMA customer_branch (
  customer STRING
);

CREATE BRANCH by_customer SCHEMA customer_branch TTL 5m;

CREATE RELAY orders_by_customer SCHEMA order_record BRANCHED BY by_customer;

CREATE RELAY orders_deduped SCHEMA order_record BRANCHED BY by_customer;

Construct The Branch Key

Only ingestors and reingestors construct branch keys. Since orders is already flowing, a reingestor — a branch-boundary node — re-partitions it without touching the existing graph:

CREATE REINGESTOR partition_orders
  FROM orders
  TO orders_by_customer
    INHERIT ALL
    BRANCHED BY by_customer SET customer = message.customer
    FLUSH EACH 100ms MAX BATCH SIZE 1MiB
    ON MESSAGE ERROR LOG;

BRANCHED BY by_customer SET customer = message.customer builds the concrete key from each record. The first order from a customer materializes that customer’s branch; every relay and processor downstream that declares BRANCHED BY by_customer runs per customer (Branch Semantics).

Deduplicate Per Branch

A deduplicator drops records whose key it has already seen within a time window. Declared BRANCHED BY by_customer, its history is branch-local:

CREATE DEDUPLICATOR dedupe_orders
  FROM orders_by_customer
  DEDUPLICATE ON input.order_id
  MAX TIME 5m
  BRANCHED BY by_customer
  TO orders_deduped
    INHERIT ALL
    FLUSH EACH 250ms MAX BATCH SIZE 1MiB
    ON MESSAGE ERROR LOG;

Emit The Deduplicated Stream

An emitter consumes every concrete branch and collapses branch identity at the external boundary (Branch Semantics) — the Redis channel receives all customers:

CREATE EMITTER redis_deduped
  FROM orders_deduped
  TO REDIS PUBSUB redis_local CHANNEL orders_deduped_out
    MODE NO_ACK RETRY POLICY BACKOFF 250ms MAX 30s
    ENCODE USING order_codec
  INHERIT ALL
  FLUSH EACH 100ms MAX BATCH SIZE 1MiB
  ON MESSAGE ERROR LOG
  ON GENERAL ERROR LOG;

COMMIT;

Prove The Isolation

Subscribe to orders_deduped_out, then produce the same order_id interleaved across two customers:

docker exec redis redis-cli SUBSCRIBE orders_deduped_out

{"order_id":"o-2001","customer":"acme","status":"new","amount":900,"quantity":1}
{"order_id":"o-2001","customer":"globex","status":"new","amount":900,"quantity":1}
{"order_id":"o-2001","customer":"acme","status":"new","amount":900,"quantity":1}

The first two records pass — acme and globex each have their own deduplication history. The third is dropped as a duplicate inside the acme branch only. That is branch isolation: state, batching, and routing for one group never interfere with another. For sizing branched graphs, see Capacity Planning For Branched Graphs.

Next: Error Routes handles records that fail instead of dropping them.

Error Routes

So far every failure policy has been LOG. Nervix can instead capture a failing record as a structured error — with a stable reference, code, message, and the partially constructed output — and send it to a dead-letter relay for inspection or downstream handling. See Message Errors. The Errors And Diagnostics architecture chapter explains how a runtime failure becomes this structured error and how sensitive data stays out of it.

To provoke real failures, this step computes a per-unit price: amount / quantity fails when a record arrives with quantity of zero.

The Dead-Letter Model

Error handlers construct an ordinary record on an ordinary relay. Fields taken from partial_output must be OPTIONAL — the failed operation may not have produced them:

BEGIN;

CREATE SCHEMA priced_order (
  order_id STRING,
  customer STRING,
  amount I64,
  quantity I64,
  unit_price I64
);

CREATE SCHEMA order_error (
  error_reference STRING,
  error_code STRING,
  error_message STRING,
  source_order STRING,
  attempted_price I64 OPTIONAL
);

CREATE RELAY priced_orders SCHEMA priced_order UNBRANCHED;

CREATE RELAY order_errors SCHEMA order_error UNBRANCHED;

Send Failures To The Dead Letter

ON MESSAGE ERROR SEND TO replaces LOG on the route. The handler can read the error metadata (error.*), the original input (input.*), and the partial output of the failed construction (partial_output.*):

CREATE JUNCTION price_orders
  FROM orders
  UNBRANCHED
  TO priced_orders
    INHERIT ALL EXCEPT status
    SET unit_price = input.amount / input.quantity
    FLUSH IMMEDIATE
    ON MESSAGE ERROR SEND TO order_errors
      SET error_reference = error.reference,
          error_code = error.code,
          error_message = error.message,
          source_order = input.order_id,
          attempted_price = partial_output.unit_price;

COMMIT;

INHERIT ALL EXCEPT status inherits everything but the one field priced_order does not declare. Error routes preserve the branch in which the failure executed — this junction is unbranched, so order_errors is unbranched too. The node-level ON GENERAL ERROR policy exists only on ingestors and emitters (Runtime Node Error Policies).

Trigger A Failure

Watch the dead-letter relay with a session subscription:

nervix-cli --domain quickstart subscribe errors order_errors

Produce one healthy record and one with quantity of zero:

{"order_id":"o-3001","customer":"acme","status":"new","amount":900,"quantity":3}
{"order_id":"o-3002","customer":"acme","status":"new","amount":900,"quantity":0}

o-3001 flows to priced_orders with unit_price of 300. o-3002 fails the division and arrives on order_errors as a structured record: a stable error_reference, the machine-readable error_code, the human-readable error_message, and a null attempted_price — the division never produced one. Hot-path errors never leak sensitive payload values.

Next: add a second way into the graph in HTTP Ingestion.

HTTP Ingestion

Orders do not have to come through a broker. Nervix hosts its own inbound HTTP endpoints: you declare a virtual host and a path, attach an ingestor, and POST records straight at the server. See HTTP ENDPOINT And WEBSOCKETS ENDPOINT.

Inbound endpoints are served by the node itself on its HTTP listener — --http-listen-addr, 0.0.0.0:8080 by default (TLS-enabled vhosts use the separate HTTPS listener instead).

Declare The Endpoint

Three statements, in order: the VHOST names the hostnames served, the ENDPOINT binds a path on that vhost, and the ingestor consumes the endpoint. An HTTP ENDPOINT ingestor names its connector and entity in its head and reads only a TYPE HTTP endpoint. The existing order_codec decodes the same JSON as the Kafka path:

BEGIN;

CREATE RELAY orders_http SCHEMA order_record UNBRANCHED;

CREATE VHOST edge orders.example.com;

CREATE ENDPOINT orders_ingress
  ON edge
  PATH '/orders'
  TYPE HTTP;

CREATE HTTP ENDPOINT INGESTOR http_orders
  FROM orders_ingress MODE NO ACK
  ON QUIESCE BUFFER MAX SIZE 1MiB DECODE USING order_codec
  TO orders_http
    INHERIT ALL
    UNBRANCHED
    FLUSH IMMEDIATE
    ON MESSAGE ERROR LOG
  ON GENERAL ERROR LOG;

COMMIT;

MODE NO ACK is the only mode endpoint ingestors support — there is no broker to acknowledge to. With this schemaful codec each POST body is one record, while a JAQ-backed codec can unfold one body into several. To merge this stream with the Kafka-fed orders relay, a junction can consume both relays with FROM orders, orders_http.

POST An Order

Watch the relay first:

nervix-cli --domain quickstart subscribe http_watch orders_http

Then send a record. The vhost is matched against the request’s Host header (lowercased, port stripped), so tell curl which host you mean:

curl -i -X POST http://127.0.0.1:8080/orders \
  -H 'Host: orders.example.com' \
  -H 'Content-Type: application/json' \
  -d '{"order_id":"o-4001","customer":"acme","status":"new","amount":700,"quantity":7}'

The server answers 202 Accepted and the record appears in the subscription. Requests to an unknown host or path get 404, and anything other than POST gets 405.

One thing 202 does not mean: that the payload decoded. Dispatch is fire-and-forget — a body that fails the codec goes to the route’s ON MESSAGE ERROR policy, not back to the HTTP client. Verify through the subscription, not the status code.

Next: reshape foreign JSON at the boundary in JAQ Transformations.

JAQ Transformations

So far every payload matched the wire schema field for field. Real feeds rarely do. When a partner sends orders as a nested envelope, a JAQ codec reshapes the payload at the boundary instead of declaring a wire schema: the codec parses the native format and runs a jq-style program whose outputs must each be a JSON object matching the internal schema. The concise JAQ Reference links the complete, version-matched upstream manual.

Suppose the partner posts this envelope:

{"order":{"id":"o-5001","customer":"acme","state":"new"},"totals":{"amount":1200,"quantity":4}}

A JAQ Codec

A JAQ codec replaces the wire schema entirely — it goes straight from the format to the internal schema, with the program inline:

BEGIN;

CREATE CODEC partner_order_codec
  FROM JSON
  TO SCHEMA order_record
  WITH JAQ TRANSFORMATIONS ON INGESTION $jaq$
  {
    order_id: .order.id,
    customer: .order.customer,
    status: .order.state,
    amount: .totals.amount,
    quantity: .totals.quantity
  }
  $jaq$;

The explicit ON INGESTION direction means this codec decodes but cannot encode. A bidirectional codec adds ON EMITTING '<program>' after the ingestion program (JAQ Transformations). FROM accepts JSON, YAML, TOML, XML, and CBOR.

Two rules to remember: any field the program can produce as null must be OPTIONAL in the internal schema, and surplus keys in the program’s output are silently dropped.

Wire It To An Endpoint

Reuse the vhost from HTTP Ingestion with a second path:

CREATE RELAY partner_orders SCHEMA order_record UNBRANCHED;

CREATE ENDPOINT partner_ingress ON edge PATH '/partner-orders' TYPE HTTP;

CREATE HTTP ENDPOINT INGESTOR partner_order_source
  FROM partner_ingress MODE NO ACK
  ON QUIESCE BUFFER MAX SIZE 1MiB DECODE USING partner_order_codec
  TO partner_orders
    INHERIT ALL
    UNBRANCHED
    FLUSH IMMEDIATE
    ON MESSAGE ERROR LOG
  ON GENERAL ERROR LOG;

COMMIT;

Send The Envelope

nervix-cli --domain quickstart subscribe partner_watch partner_orders

curl -i -X POST http://127.0.0.1:8080/partner-orders \
  -H 'Host: orders.example.com' \
  -H 'Content-Type: application/json' \
  -d '{"order":{"id":"o-5001","customer":"acme","state":"new"},"totals":{"amount":1200,"quantity":4}}'

The subscription shows the flattened order_record — the envelope never enters the graph.

Unfold A Batch

A partner that sends several orders in one body needs no second endpoint. Every object the program yields becomes its own message, so a program that iterates an array unfolds one POST into one record per element:

CREATE CODEC partner_batch_codec
  FROM JSON
  TO SCHEMA order_record
  WITH JAQ TRANSFORMATIONS ON INGESTION $jaq$
  .orders[] | {
    order_id: .order.id,
    customer: .order.customer,
    status: .order.state,
    amount: .totals.amount,
    quantity: .totals.quantity
  }
  $jaq$;

An ingestor decoding with partner_batch_codec turns a body of {"orders":[...]} into one order_record per element, in array order. The body is still accepted or rejected as a whole: if one element does not fit the schema, no record from that body enters the graph. Unfolding Payloads covers acknowledgement, limits, and diagnostics.

Next: binary payloads in Protobuf Codecs.

Protobuf Codecs

Protobuf payloads are decoded from real .proto definitions. The definitions are uploaded as a versioned resource; the codec compiles them, decodes each payload into the message’s JSON view, and hands that to a JAQ program — the same bridge as the previous step.

The Proto File

Create proto/order_event.proto in your working directory, with field names matching order_record:

syntax = "proto3";

package quickstart;

message OrderEvent {
  string order_id = 1;
  string customer = 2;
  string status = 3;
  int64 amount = 4;
  int64 quantity = 5;
}

Upload It As A Resource

UPLOAD RESOURCE is a client-side statement — the CLI reads the directory from your machine and streams it to the cluster — so it cannot sit inside a transaction, and its path resolves relative to where nervix-cli runs:

BEGIN;
CREATE RESOURCE order_proto;
COMMIT;

UPLOAD RESOURCE order_proto VERSION './proto';

The client reports uploaded resource version 1. Uploads are immutable and versioned; see Versioning.

The Codec And Its Endpoint

The clause order is rigid: resource and its mandatory version, CONFIG (mandatory — file/include select and root the .proto files inside the resource), the fully-qualified MESSAGE name, then the target schema and JAQ program. VERSION 1 names the upload above; VERSION LATEST would bind the highest completed version when the statement is applied and store that number. The message’s JSON view keeps snake_case proto field names and numeric 64-bit integers, so a field-for-field message needs only the identity program '.':

BEGIN;

CREATE CODEC order_protobuf_codec
  FROM PROTOBUF
  USING RESOURCE order_proto VERSION 1
  CONFIG {'file' = 'order_event.proto', 'include' = '.'}
  MESSAGE 'quickstart.OrderEvent'
  TO SCHEMA order_record
  WITH JAQ TRANSFORMATIONS ON INGESTION '.';

CREATE RELAY proto_orders SCHEMA order_record UNBRANCHED;

CREATE ENDPOINT proto_ingress ON edge PATH '/proto-orders' TYPE HTTP;

CREATE HTTP ENDPOINT INGESTOR proto_order_source
  FROM proto_ingress MODE NO ACK
  ON QUIESCE BUFFER MAX SIZE 1MiB DECODE USING order_protobuf_codec
  TO proto_orders
    INHERIT ALL
    UNBRANCHED
    FLUSH IMMEDIATE
    ON MESSAGE ERROR LOG
  ON GENERAL ERROR LOG;

COMMIT;

Because it declares only ON INGESTION, this codec is decode-only; encoding to protobuf requires an ON EMITTING program. A DATETIME field would ride in a proto string plus ENCODE <field> AS RFC3339 on the codec (Codecs).

Send A Binary Order

Watch the relay:

nervix-cli --domain quickstart subscribe proto_watch proto_orders

protoc --encode turns protobuf text format into wire bytes, which curl posts as the raw body:

protoc --encode=quickstart.OrderEvent proto/order_event.proto <<'EOF' > order.bin
order_id: "o-6001"
customer: "acme"
status: "new"
amount: 4200
quantity: 6
EOF

curl -i -X POST http://127.0.0.1:8080/proto-orders \
  -H 'Host: orders.example.com' \
  -H 'Content-Type: application/octet-stream' \
  --data-binary @order.bin

The decoded record appears in the subscription — typed, with no JSON anywhere on the wire.

Next: extend the expression language itself in User-Defined Functions.

User-Defined Functions

The CASE expression in Conditional Routing works, but the banding logic is trapped inside one junction. A UDF packages it as a named function every node can call. UDFs are written in Roto, compiled to native code, and operate on whole Arrow columns at a time; the source is inline in the statement — there is no separate upload step. See Declaration.

Declare The Function

BEGIN;

CREATE UDF amount_band
  WITH ROTO_0_13
  ARGS (amount I64)
  RETURNS STRING
  CODE $roto$
    fn amount_band(amount: I64Column) -> StringColumn {
        when_s(amount.gt_s(9999), "vip")
            .when_s(amount.gt_s(999), "high")
            .otherwise_s("routine")
    }
  $roto$;

The declared signature must exactly match the Roto entry function — same name, matching column types (an I64 argument is an I64Column), no implicit casts. $roto$ ... $roto$ is a dollar-quoted string, so the body spans lines verbatim. The available column operations are cataloged in Roto Column Operations; UDFs are deterministic unless declared VOLATILE (Nulls, Errors, And Volatility).

Call It

Calls always use the udf:: qualifier and compose with builtins and route filters (Calling UDFs):

CREATE RELAY banded_orders SCHEMA order_tiered UNBRANCHED;

CREATE JUNCTION band_orders
  FROM orders
  UNBRANCHED
  TO banded_orders
    INHERIT ALL
    SET tier = udf::amount_band(input.amount)
    WHERE udf::amount_band(input.amount) != "routine"
    FLUSH IMMEDIATE
    ON MESSAGE ERROR LOG;

COMMIT;

This reuses the order_tiered schema from Conditional Routing — the same enrichment, now expressed once and callable from any junction, filter, or route in the domain.

Watch It Classify

nervix-cli --domain quickstart subscribe band_watch banded_orders

Produce orders with amounts 500, 2500, and 25000 on the Kafka topic (the junction reads the Kafka-fed orders relay). The 500 order is filtered out by the route WHERE; the others arrive with "tier":"high" and "tier":"vip".

Lifecycle notes: changing the body means DROP UDF amount_band; and recreating it, and the drop is rejected while any node still references the function (Introspection And Lifecycle). For where UDFs sit between builtins and WASM processors, see Choosing An Extension Tier.

Next: aggregate the stream in Window Aggregates.

Window Aggregates

Individual orders are flowing; now summarize them. A window processor collects records into sliding windows and constructs aggregate output. Declared BRANCHED BY by_customer, it windows each customer independently — building directly on Branched Processing.

The Summary Model

Window routes are set-only: every output field is an aggregate expression, so the output relay needs its own summary schema (the order schema cannot be reused unless every field is aggregated):

BEGIN;

CREATE SCHEMA order_window (
  customer STRING,
  order_count I64,
  total_amount I64,
  max_amount I64,
  avg_amount F64
);

CREATE RELAY order_windows SCHEMA order_window BRANCHED BY by_customer;

The Window Processor

Windows use WIDTH and STEP instead of FLUSH. Each bound can count messages, elapse a duration, or combine both — a combined bound closes the window when either condition is met:

CREATE WINDOW PROCESSOR customer_order_window
  FROM orders_by_customer
  WIDTH 3 MESSAGES 30s DURATION
  STEP 3 MESSAGES 30s DURATION
  BRANCHED BY by_customer
  TO order_windows
    SET customer = FIRST(input.customer),
        order_count = COUNT(input.order_id),
        total_amount = SUM(input.amount),
        max_amount = MAX(input.amount),
        avg_amount = AVG(input.amount)
  ON MESSAGE ERROR LOG;

COMMIT;

• The aggregate functions are COUNT, COUNT_IF, SUM, AVG, MIN, MAX, FIRST, LAST, ARG_MIN, ARG_MAX, BOOL_AND, BOOL_OR, VAR_POP, VAR_SAMP, STDDEV_POP, STDDEV_SAMP, COVAR_POP, COVAR_SAMP, CORR, and PERCENTILE_LINEAR_HISTOGRAM, and the approximate APPROX_COUNT_DISTINCT, APPROX_QUANTILE, and APPROX_TOP_K. Aggregate calls also participate in larger scalar expressions. See Window Aggregates for their types, null handling, numerical behavior, and the bounded state the approximate ones need.
• A null argument contributes nothing to an aggregate. An aggregate that can be null, such as VAR_SAMP or any aggregate over an OPTIONAL field, needs an OPTIONAL output field or a COALESCE.
• input.<field> is valid only inside aggregate arguments; a bare customer = input.customer is rejected. Aggregates cannot be nested.
• WIDTH equal to STEP makes the windows tumbling (no overlap); a smaller STEP slides them. STEP may never exceed WIDTH.
• Every required field of order_window must be assigned, and every SET target must exist in the schema.

Watch The Summaries

nervix-cli --domain quickstart subscribe window_watch order_windows

Produce three acme orders. When the third arrives, one summary record for the acme branch appears — order_count of 3, with the totals. Interleave globex orders and you will see that each customer’s window fills separately: the branch keeps window state per customer, exactly like the deduplicator’s history. If a window stays partially filled, the 30s duration bound closes it.

Duration bounds start from record timestamp watermarks and become due when a later watermark or the bound domain clock reaches the target. A paced domain’s TIME RATE changes the real wait for a partially filled window while preserving the records’ external event timestamps. The output keeps the window’s minimum low watermark and records the emission snapshot as its high watermark. See Ingestion Timestamps.

Next: produce records without any input at all in Generators.

Generators

Every node so far reacts to input. A generator is the opposite: it has no input relay and produces records on a timer, reading a snapshot of materialized relay state on every tick. The classic use is a per-key heartbeat or periodic re-publication of the latest known value.

Materialize The Relay

Materialized state keeps the latest full record per branch instance. It is a relay property, and an existing relay can adopt it with ALTER RELAY (Altering Relays):

BEGIN;

ALTER RELAY orders_by_customer SET MATERIALIZED STATE LAST BY TIMESTAMP;

LAST BY TIMESTAMP keeps the newest record per customer according to record timestamp watermarks — ingestion time works out of the box in an unpaced domain (Ingestion Timestamps).

The Generator

A generator declares exactly one materialized relay and reads it through the relay_state.<relay>.<field> namespace. Its routes are set-only and, unlike windows, do require a flush policy. Branch identity is node-wide: the generator, its materialized relay, and its output relay must share the exact branch.

CREATE SCHEMA order_heartbeat (
  customer STRING,
  last_order_id STRING,
  last_amount I64
);

CREATE RELAY order_heartbeats SCHEMA order_heartbeat BRANCHED BY by_customer;

CREATE GENERATOR order_heartbeat_source
  USING MATERIALIZED STATE orders_by_customer
  EACH 5s
  BRANCHED BY by_customer
  TO order_heartbeats
    SET customer = relay_state.orders_by_customer.customer,
        last_order_id = relay_state.orders_by_customer.order_id,
        last_amount = relay_state.orders_by_customer.amount
    FLUSH IMMEDIATE
    ON MESSAGE ERROR LOG;

COMMIT;

When a customer’s branch first materializes, that branch gets its own generator task; every 5s tick reads an immutable snapshot of the customer’s latest order and constructs one heartbeat. Branch eviction (the branch TTL) stops the task and drops its state. In an unpaced domain the cadence follows wall clock time; paced domains tick on the domain clock (Domains And Time).

The first generator occurrence is immediate when the generator starts. Later occurrences stay on the original EACH schedule. Slow work coalesces missed ticks into one generation at the newest due occurrence, then continues at the first future boundary without a catch-up burst.

Watch It Tick

nervix-cli --domain quickstart subscribe heartbeat_watch order_heartbeats

Nothing appears yet — a branched generator is silent until a branch exists. Produce one acme order and heartbeats start arriving every five seconds, repeating the latest acme order. Produce a globex order and a second, independent heartbeat stream joins in. Send a newer acme order and the acme heartbeat switches to it on the next tick.

One lifecycle caveat: START clears materialized state for the domain, so after a restart the generators stay silent until new records materialize branches again (Materialized State).

Next: join two streams in Correlators.

Correlators

Orders are one stream; payments are another. A correlator joins two streams on a predicate, holding unmatched records in a bounded buffer until their partner arrives or a deadline passes. There is no ambiguous default input — a correlator has explicit LEFT and RIGHT sides, and every expression reads through the left. and right. scopes.

Branch identity is node-wide here too: the left relays, right relays, output relays, and timeout targets must all share the correlator’s exact branch. This one is fully unbranched, joining the Kafka-fed orders relay with a new payments feed.

The Payments Feed

BEGIN;

CREATE SCHEMA payment_record (
  order_id STRING,
  payment_id STRING,
  amount I64
);

CREATE WIRE JSON SCHEMA payment_wire MODE STRICT (
  order_id string,
  payment_id string,
  amount integer
);

CREATE CODEC payment_codec
  FROM WIRE JSON SCHEMA payment_wire
  TO SCHEMA payment_record;

CREATE RELAY payments SCHEMA payment_record UNBRANCHED;

CREATE ENDPOINT payment_ingress ON edge PATH '/payments' TYPE HTTP;

CREATE HTTP ENDPOINT INGESTOR payment_source
  FROM payment_ingress MODE NO ACK
  ON QUIESCE BUFFER MAX SIZE 1MiB DECODE USING payment_codec
  TO payments
    INHERIT ALL
    UNBRANCHED
    FLUSH IMMEDIATE
    ON MESSAGE ERROR LOG
  ON GENERAL ERROR LOG;

The Correlator

Matched pairs become paid_orders records. Orders that see no payment within MAX TIME are forwarded to unpaid_orders by the left side’s timeout action; unmatched payments are dropped by the right side’s:

CREATE SCHEMA paid_order (
  order_id STRING,
  customer STRING,
  amount I64,
  payment_id STRING
);

CREATE RELAY paid_orders SCHEMA paid_order UNBRANCHED;

CREATE RELAY unpaid_orders SCHEMA order_record UNBRANCHED;

CREATE CORRELATOR correlate_payments
  LEFT FROM orders
  RIGHT FROM payments
  CORRELATE WHERE left.order_id = right.order_id
  MATCH EARLIEST
  MAX TIME 30s
  ON CORRELATION TIMEOUT SEND TO unpaid_orders, DROP
  UNBRANCHED
  TO paid_orders
    SET order_id = left.order_id,
        customer = left.customer,
        amount = left.amount,
        payment_id = right.payment_id
    FLUSH IMMEDIATE
    ON MESSAGE ERROR LOG;

COMMIT;

Reading the clauses:

• CORRELATE WHERE is a full boolean expression — equality is typical, but function calls and AND chains work (left.order_id = right.order_id AND left.amount = right.amount).
• MATCH EARLIEST pairs an arriving record with the oldest pending candidate on the other side (LATEST takes the newest). Matching is one-to-one and consuming: the chosen pair leaves the buffers, and each record correlates at most once.
• MAX TIME bounds how long an unmatched record waits — and therefore the correlator’s memory (Capacity Planning For Branched Graphs).
• ON CORRELATION TIMEOUT <left-action>, <right-action> takes exactly two actions — DROP or SEND TO <relay>. A timeout forwards the original record unchanged, so the target relay’s schema must be compatible with that side’s schema — unpaid_orders reuses order_record.
• Routes are set-only: INHERIT is rejected, and every required field of paid_order must be assigned from left., right., or output. values (Filters And Construction). In an ON MESSAGE ERROR SEND TO handler, a correlator exposes left and right instead of input (Message Errors).

Pay An Order

Watch both outcomes:

nervix-cli --domain quickstart subscribe paid_watch paid_orders
nervix-cli --domain quickstart subscribe unpaid_watch unpaid_orders

Produce an order on the Kafka topic, then pay it over HTTP:

{"order_id":"o-7001","customer":"acme","status":"new","amount":3000,"quantity":1}

curl -i -X POST http://127.0.0.1:8080/payments \
  -H 'Host: orders.example.com' \
  -H 'Content-Type: application/json' \
  -d '{"order_id":"o-7001","payment_id":"p-1","amount":3000}'

The joined record appears on paid_orders. Now produce order o-7002 and pay nothing: thirty seconds later the original order surfaces on unpaid_orders — the timeout path in action.

Next: change the running graph without tearing it down in Altering A Running Graph.

Altering A Running Graph

Nothing built so far required tearing anything down — every step added nodes. ALTER statements change what already exists: junction logic, relay properties, schemas, ingestor sources, emitter sinks, stateful processor behavior, reingestor wiring, and generator cadence or routes. Nervix classifies each validated change and pauses as little as possible — the statement result reports the executed level (ALTER Lock And Quiesce Classification):

• DYNAMIC — hot-applied; nothing pauses (relay capacity, junction filters and route logic, deduplicator or reorderer MAX TIME, emitter flush policy)
• ENTITY_PAUSE — only the affected node or relay is gated and drained (topology changes, deduplication keys, reorderer ordering, ingestor, reingestor, generator, and emitter reconfiguration, relay materialized state — the ALTER RELAY in Generators ran at this level)
• DOMAIN_PAUSE — domain ingestion stops, in-flight work drains, the new graph is installed atomically, and flow resumes (schema and branching changes)

Before altering anything, SHOW CREATE <kind> <name>; prints the current canonical definition.

Change Routing Logic — Dynamic

Lower the high-value threshold from 1000 to 500. Route changes go through ALTER JUNCTION; REPLACE ROUTE requires the complete route body, not a diff:

ALTER JUNCTION route_orders
  REPLACE ROUTE TO high_value_orders
    INHERIT ALL
    SET tier = CASE
          WHEN input.amount >= 10000 THEN "vip"
          ELSE "high"
        END
    WHERE output.amount >= 500
    FLUSH IMMEDIATE
    ON MESSAGE ERROR LOG;

The result reports quiesce level: DYNAMIC — the domain never paused, buffered work stayed in place, and the very next order is evaluated against the new threshold. Produce a 700-amount order and watch it reach high_value_out, which the old threshold would have dropped.

Relay capacity is equally uneventful (Altering Relays, capacity semantics under Capacity):

ALTER RELAY orders SET CAPACITY 8;

Evolve A Schema — Domain Pause

Payments gain a method. A codec requires its wire schema to exactly match the internal schema, so both must change in one transaction — the registry validates the complete candidate graph before anything applies (Altering Schemas):

BEGIN;

ALTER WIRE JSON SCHEMA payment_wire
  ADD FIELD method string OPTIONAL;

ALTER SCHEMA payment_record
  ADD FIELD method STRING OPTIONAL;

COMMIT;

This reports quiesce level: DOMAIN_PAUSE: ingestion stops, buffered output is force-flushed (no in-flight records are lost), the graph is swapped, and flow resumes — there is no user-facing PAUSE statement, and a drain timeout rolls the whole batch back (Automatic Model-Alteration Quiescing).

Add the field as OPTIONAL: old payloads without it keep decoding, and the field finalizes as a typed null. Verify by POSTing a payment with "method":"card" to /payments and watching the payments relay.

Two rules worth knowing before you lean on this:

• One alteration at a time per domain — a concurrent mutation is rejected with already has a model alteration in progress, not queued.
• DROP plus CREATE of the same entity in one batch is compared as one modification — you cannot sneak a schema change past domain quiescing by recreating the relay.

Ingestors and emitters have their own operation sets — Altering Ingestors (an ingestor’s ALTER repeats its connector and entity, such as ALTER KAFKA TOPIC INGESTOR kafka_orders, and every ingestor change is entity-pause) and Altering Emitters (flush changes are dynamic; sink, client, and codec changes are entity-pause; source-list membership changes are domain-pause). Processor operations are covered under Altering Deduplicators, Altering Reorderers, Altering Reingestors, and Altering Generators.

Next: run the graph on a logical clock in Paced Domains.

Paced Domains

The quickstart domain is unpaced: records are admitted as they arrive and every cadence follows wall clock time. A paced domain instead maintains a domain clock — records are admitted by their event timestamps, and every time-driven behavior (generator cadence, branch TTL, duration windows) follows the logical clock. Start the clock at a historical point with an accelerated TIME RATE and the same graph replays the past faster than real time. See Paced Domains.

This page builds a small replay domain next to quickstart.

A Second Domain

CREATE PACED DOMAIN quickstart_replay WITH PERIOD 200ms SKEW 100000h;

USE quickstart_replay;

• PERIOD is the logical spacing between domain ticks.
• SKEW is the admission window around each tick. It is deliberately huge here: the tutorial posts records with fixed historical timestamps, and they must fall inside a window anchored to the clock. Live feeds whose timestamps track the clock use small skews like 1s.

A Timestamped Stream

Paced ingestion needs an event time, so this schema finally carries a DATETIME — which is also the promised demonstration of the codec’s datetime encoding: the wire field is a string, and ENCODE ... AS RFC3339 bridges it (Codecs).

BEGIN;

CREATE SCHEMA order_event (
  order_id STRING,
  amount I64,
  occurred_at DATETIME
);

CREATE WIRE JSON SCHEMA order_event_wire MODE STRICT (
  order_id string,
  amount integer,
  occurred_at string
);

CREATE CODEC order_event_codec
  FROM WIRE JSON SCHEMA order_event_wire
  TO SCHEMA order_event
  ENCODE occurred_at AS RFC3339;

CREATE RELAY replay_orders
  SCHEMA order_event UNBRANCHED
  WITH MATERIALIZED STATE LAST BY TIMESTAMP;

CREATE VHOST replay_edge replay.example.com;

CREATE ENDPOINT replay_ingress ON replay_edge PATH '/events' TYPE HTTP;

CREATE HTTP ENDPOINT INGESTOR replay_source
  FROM replay_ingress MODE NO ACK
  ON QUIESCE BUFFER MAX SIZE 1MiB DECODE USING order_event_codec
  TIMESTAMP AT occurred_at
  TO replay_orders
    INHERIT ALL
    UNBRANCHED
    FLUSH IMMEDIATE
    ON MESSAGE ERROR LOG
  ON GENERAL ERROR LOG;

TIMESTAMP AT occurred_at is not optional style here: in a paced domain every ingestor must declare a timestamp source (TIMESTAMP NOW or TIMESTAMP AT <field>), or ingestion fails with requires ingestor ... to declare TIMESTAMP NOW or TIMESTAMP AT <field> (Ingestion Timestamps).

To make the clock visible, add a generator whose cadence is declared in logical seconds:

CREATE SCHEMA replay_heartbeat (
  order_id STRING,
  amount I64
);

CREATE RELAY replay_heartbeats SCHEMA replay_heartbeat UNBRANCHED;

CREATE GENERATOR replay_ticker
  USING MATERIALIZED STATE replay_orders
  EACH 10s
  UNBRANCHED
  TO replay_heartbeats
    SET order_id = relay_state.replay_orders.order_id,
        amount = relay_state.replay_orders.amount
    FLUSH IMMEDIATE
    ON MESSAGE ERROR LOG;

COMMIT;

Start The Clock

A stopped paced domain has no ticks, so nothing is admitted — try POSTing now and the request fails. Then start the clock at a historical instant, running ten times faster than wall clock (Start And Stop):

START AT '2026-01-01T00:00:00Z' TIME RATE 10.0;

START; alone would resume from persisted state, and START AT NOW re-anchors to the current wall clock; TIME RATE defaults to 1.0.

Replay The Past

nervix-cli --domain quickstart_replay subscribe replay_watch replay_heartbeats

curl -i -X POST http://127.0.0.1:8080/events \
  -H 'Host: replay.example.com' \
  -H 'Content-Type: application/json' \
  -d '{"order_id":"o-8001","amount":1500,"occurred_at":"2026-01-01T00:00:05Z"}'

The record is admitted against its January event time, and heartbeats begin — declared EACH 10s, they arrive roughly every second of wall clock, because ten logical seconds pass per wall second at TIME RATE 10.0. Branch TTLs and duration windows in this domain would follow the same logical clock, which is what makes accelerated replay reproducible; deterministic UDFs preserve that reproducibility too (Domains And Time, UDF determinism under Nulls, Errors, And Volatility).

A record whose timestamp falls outside every reached logical tick window is rejected at ingestion — that is SKEW doing its job. And as everywhere, START clears materialized relay state, so a fresh replay starts from an empty snapshot surface.

Where To Go Next

The tutorial graph now ingests from Kafka, HTTP, JSON envelopes, and protobuf; routes conditionally; partitions and deduplicates per customer; dead-letters failures; classifies with a custom function; aggregates windows; emits heartbeats from materialized state; joins payments to orders; evolves live; and replays history on a logical clock. The manual covers what remains:

• WASM processors run your own compiled transform logic
• Lookups and materialized dependencies enrich in-flight records from reference data
• Sessions provide the read-only subscriptions used throughout this tutorial
• Capacity Planning For Branched Graphs sizes branched graphs
• Metrics And Observability instruments everything you just built
• Examples collects complete runnable graphs, including the examples/ directory in the repository

Installation

Nervix does not yet publish stable binary or container-image releases. Choose the installation method for your environment:

• Cargo Install From GitHub builds and installs nervix-server and nervix-cli for local or non-Kubernetes use.
• Docker runs a three-node cluster with Docker commands or Docker Compose.
• Kubernetes Operator installs the operator with Helm and manages persistent Nervix clusters through NervixCluster resources.

Pin a reviewed Git commit or container-image digest when you need a reproducible installation.

Cargo Install From GitHub

Install the Nervix server, the interactive CLI, and the NSPL formatter directly from the Nervix GitHub repository:

cargo install --locked \
  --git https://github.com/nervix-io/nervix.git \
  nervix-server nervix-cli nervix-nspl-format

This builds the binaries from source and installs them into Cargo’s binary directory, which is $HOME/.cargo/bin by default. Ensure that directory is on your PATH.

The build requires Rust 1.99 or newer and the native build tools required by Nervix’s dependencies. The initial build can take several minutes.

Confirm that the commands are available:

nervix-server --help
nervix-cli --help
nervix-nspl-format --help

Pin A Git Revision

The unpinned command installs the current default branch. For a reproducible installation, select a reviewed commit:

cargo install --locked \
  --git https://github.com/nervix-io/nervix.git \
  --rev <commit-sha> \
  nervix-server nervix-cli nervix-nspl-format

Run the same command with a different revision to upgrade. Add --force if Cargo reports that the selected packages are already installed.

To remove both binaries:

cargo uninstall nervix-server nervix-cli nervix-nspl-format

Docker

Nervix publishes a rolling multi-architecture Debian image to ghcr.io/nervix-io/nervix:debian-latest. The image contains nervix-server, nervix-cli, and nervix-nspl-format. The examples on this page create a three-node cluster for local evaluation.

For a reproducible or production deployment, replace the rolling tag with a reviewed timestamped tag or image digest. Use TLS, a secret manager, and a client-reachable advertise hostname instead of the local-development defaults shown here.

CUDA Images

Build a local CUDA image from a repository checkout with just docker-build-cuda; the build requirements are in Developing Nervix. The image uses the cuda target in Dockerfile.debian; the CPU image uses the cpu target. Both copy the same Nervix binaries from one shared builder stage. The CUDA image contains ONNX Runtime 1.30.0’s CUDA 13 provider, CUDA 13.2.2, and cuDNN 9.25.1. It supports Linux AMD64 and pins the Debian base to debian:trixie-20260918-slim and its image digest. CUDA and cuDNN occupy one layer directly above that base. The next layer updates and upgrades Debian packages while holding CUDA and cuDNN at their pinned versions. Nervix’s layers follow and reuse that CUDA layer across application builds.

To expose an NVIDIA GPU, install a host driver supporting CUDA 13.2 and the NVIDIA Container Toolkit, set NERVIX_IMAGE=nervix:cuda, and add --gpus all to the docker run commands below. The container toolkit supplies the host driver; CUDA and cuDNN are supplied by the image.

Run Three Nodes With Docker

Choose the image and initial password. The password environment variable is expanded by the shell and passed only to the bootstrap node, which creates the default user with it. The other nodes need no password: they read that user from the cluster, and a node that stops gracefully asks the leader to drain it under its node certificate.

export NERVIX_IMAGE=ghcr.io/nervix-io/nervix:debian-latest
export NERVIX_INIT_DEFAULT_USER_PASSWORD='replace-with-a-password'

docker network create nervix
docker pull "$NERVIX_IMAGE"

Provision a CA and one certificate/key pair per node under ./tls before starting the containers:

tls/ca.pem
tls/node-1.pem
tls/node-1-key.pem
tls/node-2.pem
tls/node-2-key.pem
tls/node-3.pem
tls/node-3-key.pem

Each node certificate must permit TLS server and client authentication. It must contain its Docker hostname (nervix-1, nervix-2, or nervix-3) as a DNS SAN and exactly one identity URI matching its configured cluster and node, such as nervix://cluster/nervix-docker/node/node-1. Sign all three certificates with the CA in ca.pem.

Start the bootstrap node:

docker run --detach \
  --name nervix-1 \
  --hostname nervix-1 \
  --network nervix \
  --restart unless-stopped \
  --stop-timeout 60 \
  --volume nervix-node-1-data:/var/lib/nervix \
  --volume "$PWD/tls/ca.pem:/etc/nervix/interconnect/ca.pem:ro" \
  --volume "$PWD/tls/node-1.pem:/etc/nervix/interconnect/node.pem:ro" \
  --volume "$PWD/tls/node-1-key.pem:/etc/nervix/interconnect/node-key.pem:ro" \
  --publish 47391:47391 \
  --publish 47421:47420 \
  --publish 9091:9090 \
  --env NERVIX_ADDR=0.0.0.0:47391 \
  --env NERVIX_GRPC_ADVERTISE_ADDR=127.0.0.1:47391 \
  --env NERVIX_WEB_CONSOLE_LISTEN_ADDR=0.0.0.0:47420 \
  --env NERVIX_WEB_CONSOLE_ADVERTISE_ADDR=127.0.0.1:47421 \
  --env NERVIX_OBSERVABILITY_LISTEN_ADDR=0.0.0.0:9090 \
  --env NERVIX_CLUSTER_ID=nervix-docker \
  --env NERVIX_NODE_ID=node-1 \
  --env NERVIX_INTERCONNECT_LISTEN_ADDR=0.0.0.0:47395 \
  --env NERVIX_INTERCONNECT_ADVERTISE_ADDR=nervix-1:47395 \
  --env NERVIX_INTERCONNECT_TLS_CA=/etc/nervix/interconnect/ca.pem \
  --env NERVIX_INTERCONNECT_TLS_CERT=/etc/nervix/interconnect/node.pem \
  --env NERVIX_INTERCONNECT_TLS_KEY=/etc/nervix/interconnect/node-key.pem \
  --env NERVIX_REPLICA_COUNT=3 \
  --env NERVIX_ALLOW_BOOTSTRAP=true \
  --env NERVIX_INIT_DEFAULT_USER_PASSWORD \
  "$NERVIX_IMAGE"

Start the other two nodes. Both discover the cluster through nervix-1 on the private Docker network:

Keep each node’s named data volume across restarts. Once the three nodes have joined, their Raft membership retains the advertised interconnect names. If nervix-1 stops while the other nodes continue, it uses those names to find a survivor when it restarts; it does not need a second configured bootstrap host. The joining nodes still use NERVIX_CLUSTER_BOOTSTRAP_HOST for their first contact with a fresh cluster. Once they have recovered Raft peer endpoints from their volumes, they can restart while that bootstrap host does not resolve and rejoin through another peer whose name resolves. Keep the other members’ advertised names resolvable to the restarting node.

docker run --detach \
  --name nervix-2 \
  --hostname nervix-2 \
  --network nervix \
  --restart unless-stopped \
  --stop-timeout 60 \
  --volume nervix-node-2-data:/var/lib/nervix \
  --volume "$PWD/tls/ca.pem:/etc/nervix/interconnect/ca.pem:ro" \
  --volume "$PWD/tls/node-2.pem:/etc/nervix/interconnect/node.pem:ro" \
  --volume "$PWD/tls/node-2-key.pem:/etc/nervix/interconnect/node-key.pem:ro" \
  --publish 47392:47391 \
  --publish 47422:47420 \
  --publish 9092:9090 \
  --env NERVIX_ADDR=0.0.0.0:47391 \
  --env NERVIX_GRPC_ADVERTISE_ADDR=127.0.0.1:47392 \
  --env NERVIX_WEB_CONSOLE_LISTEN_ADDR=0.0.0.0:47420 \
  --env NERVIX_WEB_CONSOLE_ADVERTISE_ADDR=127.0.0.1:47422 \
  --env NERVIX_OBSERVABILITY_LISTEN_ADDR=0.0.0.0:9090 \
  --env NERVIX_CLUSTER_ID=nervix-docker \
  --env NERVIX_NODE_ID=node-2 \
  --env NERVIX_INTERCONNECT_LISTEN_ADDR=0.0.0.0:47395 \
  --env NERVIX_INTERCONNECT_ADVERTISE_ADDR=nervix-2:47395 \
  --env NERVIX_INTERCONNECT_TLS_CA=/etc/nervix/interconnect/ca.pem \
  --env NERVIX_INTERCONNECT_TLS_CERT=/etc/nervix/interconnect/node.pem \
  --env NERVIX_INTERCONNECT_TLS_KEY=/etc/nervix/interconnect/node-key.pem \
  --env NERVIX_REPLICA_COUNT=3 \
  --env NERVIX_CLUSTER_BOOTSTRAP_HOST=nervix-1:47395 \
  "$NERVIX_IMAGE"

docker run --detach \
  --name nervix-3 \
  --hostname nervix-3 \
  --network nervix \
  --restart unless-stopped \
  --stop-timeout 60 \
  --volume nervix-node-3-data:/var/lib/nervix \
  --volume "$PWD/tls/ca.pem:/etc/nervix/interconnect/ca.pem:ro" \
  --volume "$PWD/tls/node-3.pem:/etc/nervix/interconnect/node.pem:ro" \
  --volume "$PWD/tls/node-3-key.pem:/etc/nervix/interconnect/node-key.pem:ro" \
  --publish 47393:47391 \
  --publish 47423:47420 \
  --publish 9093:9090 \
  --env NERVIX_ADDR=0.0.0.0:47391 \
  --env NERVIX_GRPC_ADVERTISE_ADDR=127.0.0.1:47393 \
  --env NERVIX_WEB_CONSOLE_LISTEN_ADDR=0.0.0.0:47420 \
  --env NERVIX_WEB_CONSOLE_ADVERTISE_ADDR=127.0.0.1:47423 \
  --env NERVIX_OBSERVABILITY_LISTEN_ADDR=0.0.0.0:9090 \
  --env NERVIX_CLUSTER_ID=nervix-docker \
  --env NERVIX_NODE_ID=node-3 \
  --env NERVIX_INTERCONNECT_LISTEN_ADDR=0.0.0.0:47395 \
  --env NERVIX_INTERCONNECT_ADVERTISE_ADDR=nervix-3:47395 \
  --env NERVIX_INTERCONNECT_TLS_CA=/etc/nervix/interconnect/ca.pem \
  --env NERVIX_INTERCONNECT_TLS_CERT=/etc/nervix/interconnect/node.pem \
  --env NERVIX_INTERCONNECT_TLS_KEY=/etc/nervix/interconnect/node-key.pem \
  --env NERVIX_REPLICA_COUNT=3 \
  --env NERVIX_CLUSTER_BOOTSTRAP_HOST=nervix-1:47395 \
  "$NERVIX_IMAGE"

The host ports are:

Connect an installed CLI to http://127.0.0.1:47391, or open the web console at http://127.0.0.1:47421/console/, and run:

SHOW CLUSTER STATUS;

The cluster status should show one local node, two live peer nodes, and all three nodes in the Raft membership. The CLI follows leader redirects through the three published gRPC ports.

Each node advertises its container name, such as nervix-1:47395, and finds its peers by those names through Docker’s embedded DNS, which Docker names in the container’s /etc/resolv.conf. A node resolves peer names, and the hosts its connectors reach, with its own asynchronous resolver from that file and /etc/hosts, read once at startup; Name Resolution describes the options that point it at other files or name servers, and what it does not support.

docker stop sends each node SIGTERM, which starts graceful shutdown, and kills a container only if its node is still running when the stop timeout ends. A node ends its own shutdown within its shutdown timeout, 50 seconds by default, which covers the 30-second default drain timeout and the services that stop after it. The --stop-timeout 60 above keeps Docker waiting longer than that, so a node that cannot finish shutting down exits with status 1 on its own rather than being killed; with Docker’s default of ten seconds, a node could be killed partway through its drain. Shutdown And Recovery explains what a node loses when its grace period ends first. Stop the nodes, then remove the containers and private network:

docker stop nervix-1 nervix-2 nervix-3
docker rm nervix-1 nervix-2 nervix-3
docker network rm nervix

The named volumes remain so the cluster can be recreated with its state intact. Removing nervix-node-1-data, nervix-node-2-data, and nervix-node-3-data permanently deletes that state.

Run Three Nodes With Docker Compose

Save the following as docker-compose.yml:

x-nervix-common: &nervix-common
  image: ${NERVIX_IMAGE:-ghcr.io/nervix-io/nervix:debian-latest}
  restart: unless-stopped
  stop_grace_period: 60s
  environment: &nervix-environment
    NERVIX_ADDR: 0.0.0.0:47391
    NERVIX_WEB_CONSOLE_LISTEN_ADDR: 0.0.0.0:47420
    NERVIX_OBSERVABILITY_LISTEN_ADDR: 0.0.0.0:9090
    NERVIX_CLUSTER_ID: nervix-docker
    NERVIX_INTERCONNECT_LISTEN_ADDR: 0.0.0.0:47395
    NERVIX_INTERCONNECT_TLS_CA: /etc/nervix/interconnect/ca.pem
    NERVIX_INTERCONNECT_TLS_CERT: /etc/nervix/interconnect/node.pem
    NERVIX_INTERCONNECT_TLS_KEY: /etc/nervix/interconnect/node-key.pem
    NERVIX_REPLICA_COUNT: "3"
  networks:
    - nervix

services:
  nervix-1:
    <<: *nervix-common
    hostname: nervix-1
    environment:
      <<: *nervix-environment
      NERVIX_NODE_ID: node-1
      NERVIX_GRPC_ADVERTISE_ADDR: 127.0.0.1:47391
      NERVIX_WEB_CONSOLE_ADVERTISE_ADDR: 127.0.0.1:47421
      NERVIX_INTERCONNECT_ADVERTISE_ADDR: nervix-1:47395
      NERVIX_ALLOW_BOOTSTRAP: "true"
      NERVIX_INIT_DEFAULT_USER_PASSWORD: ${NERVIX_INIT_DEFAULT_USER_PASSWORD:?set NERVIX_INIT_DEFAULT_USER_PASSWORD}
    ports:
      - "47391:47391"
      - "47421:47420"
      - "9091:9090"
    volumes:
      - nervix-node-1-data:/var/lib/nervix
      - ./tls/ca.pem:/etc/nervix/interconnect/ca.pem:ro
      - ./tls/node-1.pem:/etc/nervix/interconnect/node.pem:ro
      - ./tls/node-1-key.pem:/etc/nervix/interconnect/node-key.pem:ro

  nervix-2:
    <<: *nervix-common
    hostname: nervix-2
    depends_on:
      - nervix-1
    environment:
      <<: *nervix-environment
      NERVIX_NODE_ID: node-2
      NERVIX_GRPC_ADVERTISE_ADDR: 127.0.0.1:47392
      NERVIX_WEB_CONSOLE_ADVERTISE_ADDR: 127.0.0.1:47422
      NERVIX_INTERCONNECT_ADVERTISE_ADDR: nervix-2:47395
      NERVIX_CLUSTER_BOOTSTRAP_HOST: nervix-1:47395
    ports:
      - "47392:47391"
      - "47422:47420"
      - "9092:9090"
    volumes:
      - nervix-node-2-data:/var/lib/nervix
      - ./tls/ca.pem:/etc/nervix/interconnect/ca.pem:ro
      - ./tls/node-2.pem:/etc/nervix/interconnect/node.pem:ro
      - ./tls/node-2-key.pem:/etc/nervix/interconnect/node-key.pem:ro

  nervix-3:
    <<: *nervix-common
    hostname: nervix-3
    depends_on:
      - nervix-1
    environment:
      <<: *nervix-environment
      NERVIX_NODE_ID: node-3
      NERVIX_GRPC_ADVERTISE_ADDR: 127.0.0.1:47393
      NERVIX_WEB_CONSOLE_ADVERTISE_ADDR: 127.0.0.1:47423
      NERVIX_INTERCONNECT_ADVERTISE_ADDR: nervix-3:47395
      NERVIX_CLUSTER_BOOTSTRAP_HOST: nervix-1:47395
    ports:
      - "47393:47391"
      - "47423:47420"
      - "9093:9090"
    volumes:
      - nervix-node-3-data:/var/lib/nervix
      - ./tls/ca.pem:/etc/nervix/interconnect/ca.pem:ro
      - ./tls/node-3.pem:/etc/nervix/interconnect/node.pem:ro
      - ./tls/node-3-key.pem:/etc/nervix/interconnect/node-key.pem:ro

networks:
  nervix:

volumes:
  nervix-node-1-data:
  nervix-node-2-data:
  nervix-node-3-data:

Set the required initial password and start the cluster from the directory containing that file:

export NERVIX_INIT_DEFAULT_USER_PASSWORD='replace-with-a-password'
docker compose up --detach

Set NERVIX_IMAGE before docker compose up to use a pinned tag or digest instead of debian-latest.

Inspect the containers and follow their logs:

docker compose ps
docker compose logs --follow

Use the same host ports in the table above. Stop the cluster while preserving its volumes:

docker compose down

docker compose down sends each node SIGTERM and waits up to the file’s stop_grace_period of 60 seconds, longer than each node’s 50-second shutdown timeout, for graceful shutdown to finish before it kills a container. To permanently delete all three nodes’ persisted state, add --volumes.

Kubernetes Operator

The Nervix Kubernetes Operator watches namespaced NervixCluster resources across a Kubernetes cluster. For each resource, it creates the services, StatefulSet, and one persistent volume claim per Nervix node. It also coordinates one-time initialization of the default user before scaling the StatefulSet to the requested replica count.

Prerequisites

Before installing the operator, ensure that:

• kubectl and Helm 3 can reach the Kubernetes cluster.
• The cluster has a default StorageClass that can provision persistent volumes.
• Your Kubernetes identity can create custom resource definitions and cluster-wide RBAC resources.
• Cluster nodes can pull images from ghcr.io.

Install The Operator With Helm

The Helm chart is currently distributed in the operator repository rather than as a versioned chart release. Clone the repository and install its bundled chart:

git clone --depth 1 https://github.com/nervix-io/nervix-k8s-operator.git

helm upgrade --install nervix-k8s-operator \
  ./nervix-k8s-operator/charts/nervix-k8s-operator \
  --namespace nervix-system \
  --create-namespace

Wait for the operator to become available:

kubectl --namespace nervix-system rollout status \
  deployment/nervix-k8s-operator

The chart installs the NervixCluster custom resource definition and deploys one operator that can manage Nervix clusters in any namespace.

Create The Initial User Secret

Create a namespace and a Secret containing the initial password for the default user. Use a password file that contains the exact password without a trailing newline, and do not commit that file:

kubectl create namespace nervix

kubectl --namespace nervix create secret generic nervix-initial-password \
  --from-file=password=/secure/path/to/password

The operator exposes this credential only to the first bootstrap pod. After authentication proves that Nervix committed the user, the operator restarts that pod without the credential and then scales the cluster to the requested replica count.

Create A Nervix Cluster

Save the following resource as nervix-cluster.yaml:

apiVersion: nervix.io/v1alpha1
kind: NervixCluster
metadata:
  name: nervix
  namespace: nervix
spec:
  image: ghcr.io/nervix-io/nervix:debian-latest
  replicas: 3
  clusterId: nervix-kube
  initialDefaultUserPasswordSecretRef:
    name: nervix-initial-password
    key: password
  storage: 5Gi

Apply it and watch the cluster become ready:

kubectl apply --filename nervix-cluster.yaml
kubectl --namespace nervix get nervixcluster nervix --watch

The READY count should eventually match REPLICAS. Inspect the objects owned by the operator with:

kubectl --namespace nervix get pods,services,persistentvolumeclaims

One operator can manage multiple Nervix clusters. Create each cluster as a separate NervixCluster, usually in a separate namespace or with a distinct name in the same namespace.

Enable Local Access

For development clusters that need direct access from outside Kubernetes, add this to the NervixCluster spec:

  localAccess:
    enabled: true

Apply the updated resource:

kubectl apply --filename nervix-cluster.yaml

The default NodePorts are 31390 for the gRPC entry point, 31420 for the web console, and 31090 for health and metrics. The operator also creates per-node NodePorts so clients redirected to the leader can reach it.

Connect the CLI to the gRPC entry point:

nervix-cli --server http://<node-address>:31390

The web console is available at http://<node-address>:31420/console/. Omit localAccess for an in-cluster-only deployment.

Shutdown And Grace Periods

Deleting a pod, draining a Kubernetes node, or rolling the StatefulSet sends SIGTERM, which starts graceful shutdown. A Nervix node ends its own shutdown within its shutdown timeout, 50 seconds by default, which covers the 30-second default drain timeout and the services that stop after it. The operator sets terminationGracePeriodSeconds: 60 so the kubelet waits longer than that, and a node that cannot finish exits on its own rather than being killed partway through its drain. If you raise NERVIX_SHUTDOWN_TIMEOUT, raise the grace period with it.

Note that /readyz reports whether the node currently knows a Raft leader; it does not turn negative when a node begins terminating. A draining node is therefore not removed from Service endpoints by readiness alone. It stops accepting new client connections itself in the first shutdown phase, and it keeps serving already-admitted work until its drain finishes.

A terminating node moves its scheduled work to a live peer when one is available, and otherwise completes everything it has admitted in place. Rolling one pod at a time keeps a peer available to receive that work, so ownership moves instead of waiting for the pod to come back. See Shutdown And Recovery for the phases, the drain guarantees, and what each ending preserves.

Production Considerations

Both the chart and the example currently default to rolling latest image tags. Pin reviewed operator and Nervix image tags or digests before using this setup in production. Also choose storage, resource requests, NodePort exposure, and Secret management appropriate for the cluster.

Client Tools

Nervix ships two interactive clients, and both speak the same language to the same place: they open a session against the cluster’s session API and submit NSPL to the leader. Almost every statement in this book can be typed into either one, and neither is required — a Nervix cluster is administered entirely through NSPL, whatever submits it.

Choosing A Client

One further tool is not a client at all: nervix-nspl-format formats saved .nspl files and checks that they are formatted. It never opens a session.

The console is the better tool for understanding a graph you did not write, because it draws one. The command line client is the better tool for repeating yourself, because it can be scripted.

Only a few things differ. Uploading a resource version, and restoring a backup archive, name a local path in the command line client and use a file picker in the console; a backup’s archive is written to a local file by the command line client and saved as a browser download by the console, and only the command line client reads an archive with DESCRIBE BACKUP; the command line client follows a domain clock from its domain-clock subcommand or with ATTACH DOMAIN CLOCK, while the console follows the clock of the domain it has selected and shows it in its clock panel; the console additionally offers guided actions — clicking a graph item or an entity — that simply type NSPL for you.

What Every Client Shares

• The same statement surface. Domains, schemas, codecs, relays, clients, runtime nodes, and emitters are all declared in NSPL (NSPL Overview).
• Session and transaction statements. USE, LIST DOMAINS, UPLOAD RESOURCE, CREATE SUBSCRIPTION, DELETE SUBSCRIPTION, ATTACH DOMAIN CLOCK, and DETACH DOMAIN CLOCK are session/client operations. BEGIN, COMMIT, and REVERT operate on a leader-owned, replicated transaction.
• Server-driven completion. Suggestions come from the cluster, not from a local copy of the grammar, so they include the identifiers that actually exist in the active domain. Inside a transaction they also include the identifiers its queued statements define.
• HTTP Basic authentication against a registry user.
• Automatic leader redirects. A session opened against a follower is redirected to the current leader; you do not need to know which node leads.
• Automatic transaction attach. Both interactive clients retain the transaction id and attach it before replaying a command after reconnect or leader failover, and do not repeat an operation whose replicated progress already advanced.

Sessions, subscriptions, sampling, backpressure, and domain clock attachment are described in Sessions.

To get a cluster running first, see Installation and Running Nervix.

Command Line Client

nervix-cli is the interactive NSPL client. It is installed alongside nervix-server (Cargo Install From GitHub) and is also present in the container image (Docker).

Connecting

With no arguments the client connects to http://127.0.0.1:47391 as user default and prompts for the password:

nervix-cli

nervix-cli connected to http://127.0.0.1:47391
Type 'exit' to quit. Trailing ';' is optional.
[events] notifications are printed above the prompt

nervix[default]>

Point it at another cluster with --server, which takes a full URL. An https:// URL enables TLS:

nervix-cli --server https://nervix.example.com:47390 --tls required --tls-ca-cert ./ca.pem

Options

There is no general CLI configuration file and no --version flag. --server, --domain, and the TLS options have no environment-variable equivalents. The DNS options select the resolver used by the native session; the system resolver and hosts files are the defaults, and Name Resolution describes how that resolver answers. The password can come from NERVIX_PASSWORD so it need not appear in shell history.

The table above is the short version. nervix-cli Reference is printed by the binary itself while this book is built, so it is the authoritative list of every option and subcommand for this release.

Modes

The client runs in exactly one of three modes, in this order of precedence:

1. A subcommand, such as subscribe, domain-clock, backup, restore, or drain-node.
2. --command, which submits NSPL, prints the result, and exits.
3. The interactive REPL, when neither of the above is given.

There is no file-execution mode. To run a saved script, pass it through --command; to format one, use nervix-nspl-format:

nervix-cli --domain quickstart --command "$(cat pipeline.nspl)"

The Interactive REPL

Prompt And Multi-Line Input

The prompt shows the active domain, and continuation lines are marked with dots:

nervix[quickstart]> CREATE SCHEMA order_record (
....[quickstart]>   order_id STRING,
....[quickstart]>   amount I64
....[quickstart]> );

Input accumulates until the buffered statements parse or the line ends with ;, so a trailing semicolon is optional on a complete statement and a partial one simply keeps buffering. While a transaction is open the prompt says so:

nervix[quickstart tx]>

After COMMIT is accepted, an in-progress commit is shown as nervix[quickstart committing]>. The prompt is driven by replicated transaction status rather than a local boolean.

Completion

Tab completes. Suggestions are computed by the server for the exact cursor position, so they cover grammar keywords and the identifiers that actually exist: models in the active domain, resource names and versions, session subscription names, and domain names. Inside a quoted path that names a file or directory on this machine, such as UPLOAD RESOURCE ... VERSION '<path>', BACKUP ... TO '<path>', DESCRIBE BACKUP '<path>', and RESTORE ... FROM '<path>', the client completes local filesystem paths instead, expanding ~ to your home directory.

The replacement covers the current word even when the cursor is inside it, and keeps the text after that word. The CLI reads successive bounded pages when the server has more matches. A missing or stale domain or transaction context does not produce candidates from a different configuration.

Scripts can request the same candidates with --suggest 'DROP SCHEMA ord' --cursor 15. The cursor is a UTF-8 byte offset; omitting it selects the end of the input. The CLI prints JSON containing a status and each candidate’s display value, kind, and exact text edit.

While a transaction is open, completion describes the configuration that transaction is building: models and resources its queued statements create are suggested before COMMIT, and a model whose DROP is queued stops being suggested until a later statement recreates it. Only the session bound to the transaction sees them; every other session is offered committed configuration alone. A queued resource has no versions to suggest, because UPLOAD RESOURCE is not transaction content.

History

Submitted lines are stored in .nervix_client_history, relative to the directory the client was started in, capped at 200 entries. ArrowUp and ArrowDown walk it.

Diagnostics

Server-reported errors are rendered as annotated reports against the text you submitted, with the offending span highlighted in place rather than described by offset.

Asynchronous Output

Subscription deliveries, server notifications, and state changes and ticks of an attached clock arrive independently of the prompt and are printed above it:

[events] subscription [watch] from [orders]: {"order_id":"o-1001","amount":1500}
[events] server ERROR: emitter 'redis_orders' publish failed
[events] topology INFO: raft transition: node-2 became leader
[events] domain clock [simulation]: generation 2, stopped
[events] domain clock [simulation] tick: generation 3, id 12, boundary 2030-01-01T00:00:01.100Z, authority UTC 2026-09-27T00:00:00Z, node logical 2030-01-01T00:00:01.120Z

A domain clock line follows each newer state or accepted tick after the attach reply. A state or tick that changes again before it is delivered or read is replaced by the newest one, so a slow client can skip states and tick ids. Between prompts the REPL holds at most 128 event lines, each cut at 8 KiB with … [line truncated]; lines that arrive while it is full are dropped, and [events] notice: <n> event lines were omitted because terminal output could not keep up reports how many. When the server ends an attachment, or the session holding it is interrupted and the clock is attached again on the next session, the line reads [events] domain clock [<domain>] notice: ... with the reason.

The REPL prints these lines when it draws its next prompt: after the statement that is running finishes, or when you press Enter on an empty line.

Output keeps printing across reconnects. When the session is lost, the next statement you run opens a new one; the client also opens one at once while a subscription or a followed clock waits to be restored. Server notices then resume with the new session, rows arrive from every subscription restored on it or opened after it, and a followed clock prints its state again once it is attached there. When the client cannot open a session within its 120-second retry deadline, a line names what is waiting and the whole chain of why, and the client keeps trying:

[events] notice: subscription events could not resume yet: failed to connect to server: transport error: tcp connect error: tcp connect error: Connection refused (os error 111); the client keeps trying

After a reconnect the CLI opens every subscription and attaches every clock again. When the new session refuses one, a notice line reports the server’s message and when the next attempt follows:

[events] subscription [watch] notice: opening the subscription again failed: stream 'orders' does not exist in domain 'quickstart'; the next attempt follows in 2s
[events] domain clock [simulation] notice: attaching the clock again failed: session-scoped and client-local statements cannot be queued in a transaction; the next attempt follows in 2s

DELETE SUBSCRIPTION of a subscription no open session holds, because its session ended or the new session refused to open it again, completes at once and frees the name.

When the server ends a subscription because its relay was redefined or removed, the subscription’s last line reads:

[events] subscription [watch] notice: the subscription ended: session subscription 'watch' ended because relay 'orders' in domain 'quickstart' no longer exists

The CLI never opens an ended subscription again, including after a reconnect. CREATE SUBSCRIPTION under the same name opens it again under the relay’s current definition, and DELETE SUBSCRIPTION of it completes at once and frees the name.

If server notices arrive faster than the CLI reads them, the client drops the ones it held and [events] notice: server notices were dropped because they arrived faster than they were read marks the gap; the notices after it keep printing.

Leaving

exit, quit, Ctrl-D, or Ctrl-C.

Session And Transaction Statements

Some statements affect the client session or replicated transaction state rather than directly applying one model change:

USE, LIST DOMAINS, UPLOAD RESOURCE, BACKUP, DESCRIBE BACKUP, RESTORE, and the domain clock statements must be submitted on their own, and never inside a transaction. ATTACH DOMAIN CLOCK prints the clock the serving node has installed, then each change above the prompt as described in Asynchronous Output:

nervix[simulation]> ATTACH DOMAIN CLOCK;
attached to the clock of domain 'simulation': generation 1, paced: period 1s, skew 100ms, logical origin 2030-01-01T00:00:00Z, UTC anchor 2026-09-27T09:30:00.125Z, time rate 2

A second attach is refused because the session already follows that clock, and a detach without an attachment is refused because it does not. USE does not detach a clock, so the REPL can follow the clocks of several domains at once, and the CLI attaches the clocks it follows again after a reconnect. See Domain Clock Attachment. Read-only statements, subscriptions, CREATE DOMAIN, CREATE USER, and node administration are also rejected while queueing transaction content. DESCRIBE TRANSACTION is the exception: while a transaction is open it reads that transaction’s impact report without queueing anything or consuming an operation number, so the next queued statement keeps the number it would have had. It must be submitted on its own. With an id it reads another transaction of the same user and leaves the prompt, the active domain, and the attached transaction as they were:

nervix-cli --domain production --command \
  "DESCRIBE TRANSACTION '01a0ca64-7062-7302-ac1e-43138ccc2067' OPERATION 2 FORMAT JSON;"

For a standalone --command inspection with FORMAT JSON, stdout contains exactly one JSON document serialized from the typed report, without terminal decoration or unrelated events. Failures print one JSON object with error.code and error.message on stdout and exit nonzero; a configuration, connection or request failure’s message is the whole chain of causes, such as invalid server URL: relative URL without a base. Diagnostic details and unrelated events go to stderr. FORMAT TEXT uses the normal readable terminal output. Inspection output is complete rather than paginated or truncated, so redirect a large text or JSON report to a file or downstream process when terminal output is impractical. After a stale-preview COMMIT refusal, run DESCRIBE TRANSACTION for the attached transaction before retrying the commit so the client fences it to the newly reviewed planning basis. See Transaction Quiescence And Impact Inspection for the report’s planned and actual scopes, historical topology, and diagnostic meanings.

BEGIN requires an existing active domain and binds the transaction to it; attaching a transaction switches the active domain to the transaction’s domain. An upload targets the active domain, renders live progress, and finishes after every current live node incarnation has verified and installed the assigned version:

upload resource 'order_model' finished: 4.2 MiB sent
uploaded resource version 1

See Resources for what a resource version contains.

Use --command for an atomic resource rebinding just like any other server statement:

nervix-cli --domain production --command \
  "REBIND RESOURCE order_model TO VERSION LATEST FOR INFERENCER score_orders;"

The command prints the resolved target, changed and selected usage counts, quiesce level, and a sorted line for every selected model. In a transaction, the queued response is a provisional plan; COMMIT resolves LATEST again before applying the atomic model step.

Backing Up

BACKUP in the REPL or through --command runs the backup and downloads its archive into the named file on this machine. The backup subcommand does the same with arguments instead of NSPL, and exits with a nonzero status whenever the archive was not delivered:

nervix-cli backup cluster --output cluster.nvxb
nervix-cli --domain payments backup domain --output - --without-resources > payments.nvxb
nervix-cli backup domain payments --output payments.nvxb --format json

--output - writes the archive to standard output and the report to standard error. A standard output that would discard the archive, the null device or one that was closed when the CLI started, fails with WRITE_FAILED before the backup is taken. The archive is downloaded and verified in a staging directory first; when standard output then fails, for example because its reader closed the pipe, the CLI keeps the verified archive there and reports WRITE_FAILED with the backup’s execution reference and the kept file, which is the only copy left. Backup And Restore describes how to recover it. --format json prints the report, or the failure, as one JSON document. DESCRIBE BACKUP reads a local archive without connecting to a server, whether it is typed in the REPL or passed to --command:

nervix-cli --command "DESCRIBE BACKUP 'cluster.nvxb' FORMAT JSON;"

The description lists every runtime state section of each domain under runtime_state. A deduplicator line names its keyspace’s branch fingerprint, key count, groups, revision and schema fingerprint; a window processor line names its branch fingerprint, retained rows, groups, branch incarnation, next admission sequence, pending delayed histogram removals, revision, schema fingerprint and window model digest. JSON reports the same values with kind deduplicator or window_processor, together with the length and digest of every section. Neither form prints branch-key values or deduplicator keys.

See Backup And Restore for what an archive holds and how long the server retains it.

Restoring

RESTORE in the REPL or through --command streams the archive the statement names from this machine to the leader, and prints the restore’s report when it ends. The restore subcommand does the same with arguments instead of NSPL, shows how much of the archive was sent while it streams, and exits with a nonzero status whenever the restore did not complete:

nervix-cli restore cluster --input cluster.nvxb --on-existing-user skip
nervix-cli restore domain payments --as payments_copy --input cluster.nvxb
nervix-cli restore domain payments --input payments.nvxb --dry-run --format json
nervix-cli restore domain payments --input payments.nvxb --resume --format json

--resume starts the complete restored domain at its archived generation and mapping, preserving materialized rows, deduplicator keys and windows. The default leaves it stopped; a subsequent normal START advances its generation and clears materialized state, while deduplicator keys and windows continue. A window whose model or branch incarnation changed starts empty, and the report lists it among its warnings. Text and JSON reports include each domain’s status and start generation, including the planned lifecycle of a dry run.

--dry-run verifies the archive and plans the restore without changing anything, and --format json prints the report, or the failure, as one JSON document. The Rust client sends the archive again under the same execution reference after a redirect or a lost connection, so a restore interrupted by a leader change is resumed rather than repeated. See Backup And Restore for what a restore recreates and the order of its steps.

Streaming A Relay

The subscribe subcommand opens a read-only session subscription and prints events until interrupted:

nervix-cli --domain quickstart subscribe watch orders

nervix-cli --domain quickstart subscribe sampled orders \
  --dropping \
  --batch-sample-rate 0.1 \
  --where 'input.amount >= 1000'

--dropping and --blocking are mutually exclusive. Subscription semantics, sampling, and backpressure are covered in Sessions.

The subcommand prints server notices beside the rows, and keeps printing both across reconnects: the client opens the subscription again on its next session, reports the gap as an interruption notice, and resumes the notices of the new session, as described in Asynchronous Output. A subscription the server ended is not opened again: the subcommand prints its end and keeps printing server notices until interrupted.

Following A Domain Clock

The domain-clock subcommand attaches to the selected domain’s clock and prints its state and progress on stdout until interrupted:

nervix-cli --domain simulation domain-clock

The first line is the attach reply. Every later clock state, tick, interruption, or attachment end uses the same one-line format as the REPL’s Asynchronous Output:

attached to the clock of domain 'simulation': generation 1, paced: period 1s, skew 100ms, logical origin 2030-01-01T00:00:00Z, UTC anchor 2026-09-27T09:30:00.125Z, time rate 2
[events] domain clock [simulation] tick: generation 1, id 1, boundary 2030-01-01T00:00:00Z, authority UTC 2026-09-27T09:30:00.125Z, node logical 2030-01-01T00:00:00Z
[events] domain clock [simulation]: generation 1, stopped
[events] domain clock [simulation]: generation 2, paced: period 1s, skew 100ms, logical origin 2026-09-27T09:31:00Z, UTC anchor 2026-09-27T09:31:00Z, time rate 1

The domain and generation identify each state. A paced state includes its period, skew, logical origin, UTC anchor, and rate. A tick includes its id, logical boundary, the authority’s UTC observation, and the serving node’s logical reading.

Stdout carries these lines and nothing else, and their format is stable, so scripts and external observers can parse them. Every line has one of these forms:

<clock> is generation <n>, followed by stopped, uninstalled, unpaced, or paced: period <duration>, skew <duration>, logical origin <time>, UTC anchor <time>, time rate <rate>. Within a line:

• In the attach reply, state, and tick lines, fields are separated by , and appear in the order shown. Each field but the state is its name, one space, and its value, and a name can contain spaces, as logical origin, UTC anchor, time rate, authority UTC and node logical do. The state is stopped, uninstalled, unpaced, or paced: followed by one space and the period field.
• <n> is an unsigned decimal integer. The generation counts the domain’s STARTs, and tick ids number the ticks of a generation from one: a tick’s boundary is the logical origin plus the id minus one periods.
• <time> is an RFC 3339 instant in UTC with a Z offset and no fractional digits, or three, six, or nine of them, as the instant needs.
• <duration> has unit suffixes, such as 500ms, 1s, or 1s 500ms, and can contain spaces, so read a field by its name rather than by splitting at spaces.
• <rate> is a decimal number, such as 2 or 0.25.
• In a notice line, <message> is display text that can itself contain , and ; , and <wait> is a whole number of seconds such as 1s or 30s.

Within one session, the tick ids of a generation increase and can skip, because the authority coalesces missed periods and a slow reader receives the newest tick rather than a backlog. When the session is lost, for example because its node restarts, the interruption line reports the gap, and the client opens a new session within its retry deadline and attaches the clock again. The output then shows the clock the new session reports, and its ticks continue from the newest one that session’s node holds. Ticks accepted in between are not replayed, and the first tick after the interruption can repeat the last id printed before it, or precede it when another node serves the new session. A node that is still starting answers the attach once it has installed the cluster’s committed domains, so a restart never ends the attachment. When the new session refuses the attach for another reason, a notice line reports it and when the client tries again on that session.

The server ends an attachment when the domain no longer exists on the serving node, and a new session that no longer has the domain ends it the same way. <reason> then reads the domain no longer exists on the serving node. The end line is the last clock line and the command exits with status 0, as it does after Ctrl-C detaches the clock or finds it already detached. A failed connection, a refused attach, including a missing domain, and a refused detach print the typed reason on stderr and exit nonzero, as does a lost session the client cannot replace within its retry deadline.

Cluster Node Administration

Each of these submits one statement and exits:

Drain and replication behaviour is described in Replication And Drain Behavior.

drain-node cordons the target before moving work. It visits domains and their hard placement groups or independent runtime nodes in canonical order, drains one unit at a time, and leaves the node cordoned. A successful result starts with the aggregate and effective quiesce level, followed by one line per move:

drained node 'node-2' (moved 2 of 2 scheduled graph node(s))
quiesce level: ENTITY_PAUSE
- kind=ingestor name=orders from=node-2 to=node-3 replicas=node-2 promoted_replica=yes
- kind=emitter name=warehouse from=node-2 to=node-1 replicas=none promoted_replica=no

Each move line identifies the runtime-node kind and name, former and destination owners, resulting replicas, and whether the destination was promoted from a replica. A node with no scheduled graph work reports moved 0 of 0 and quiesce level: DYNAMIC.

If one unit cannot drain or activate, the command returns an error containing the same header plus a failed: line for that unit. Independent units continue moving, so moved can be smaller than of. The node stays cordoned, successful moves remain committed, and running drain-node again retries the units it still owns.

Shell Completions

nervix-cli completions bash > /etc/bash_completion.d/nervix-cli

bash, elvish, fish, powershell, and zsh are supported. This subcommand does not contact the server, so it works before a cluster exists.

Leader Redirects

Persistent statements are applied by the leader. The CLI gives each one a stable execution reference and retains it until the terminal result. If the session lands on a follower, the client follows the redirect and reconnects on its own, repeating the statement under the same reference, and waits out an election the same way; ordinary commands are bounded by the client’s 120-second retry deadline. BACKUP uses the global --backup-wait-timeout instead, ten minutes by default, for the entire command across all domain cuts and reconnections. This applies to NSPL in --command and the REPL as well as the backup subcommand. Its per-domain TIMEOUT does not determine that total wait. A statement the leader never answered in its wait is reported with its execution reference as not known yet. A redirect that reaches the terminal as a statement’s own result is printed as:

topology: not-a-leader, retry on leader 'node-2' at http://10.0.0.12:47391/

After an uncertain backup, backup --execution-reference REFERENCE recovers the admitted command and downloads its archive with the original selected domain, scope, resources and capture options. The output file or stdout destination may change. The JSON failure report exposes error.execution_reference; Backup And Restore describes recovery and retention limits.

Transaction controls follow the same redirect beginning with BEGIN. The CLI retains the returned transaction id and attaches it on the new connection before resuming any queued statement or commit. Each append keeps its execution reference and expected queue position. A pending commit waits for the exact retained terminal result recorded under its own reference. An open transaction therefore survives an unclean connection loss or leader failover; a clean CLI exit reverts it. See Replicated NSPL Transactions and Client Session Protocol.

nervix-cli Reference

Every option, subcommand, default, and environment variable nervix-cli accepts, printed by the binary itself while this book was built. It therefore describes exactly the release you are reading about. For how to use the client, see Command Line Client.

nervix-cli

Interactive Nervix client

Usage: nervix-cli [OPTIONS] [COMMAND]

Commands:
  completions    Generate shell completion scripts
  subscribe      Subscribe to one relay and print events until interrupted
  domain-clock   Follow the selected domain's clock until interrupted
  remove-node    Remove a node from the cluster membership
  cordon-node    Prevent the scheduler from placing new tasks on a node
  uncordon-node  Allow the scheduler to place new tasks on a node
  drain-node     Move scheduled graph nodes away from a node and keep it cordoned
  backup         Back up configuration, users and resources into an archive file
  restore        Restore configuration, users and resources from an archive file
  help           Print this message or the help of the given subcommand(s)

Options:
      --server <SERVER>
          Session gRPC endpoint; an https:// URL connects over TLS [default: http://127.0.0.1:47391]
      --tls <TLS>
          Whether TLS is required; `required` refuses a server URL that is not https [default: preferred] [possible values: preferred, required]
      --tls-ca-cert <TLS_CA_CERT>
          PEM certificate authority used to verify the server certificate
      --dns-resolver-config <DNS_RESOLVER_CONFIG>
          Resolv.conf-format file used by native session hostname resolution [env: NERVIX_DNS_RESOLVER_CONFIG=] [default: /etc/resolv.conf]
      --dns-hosts-file <DNS_HOSTS_FILE>
          Hosts-format file consulted before DNS [env: NERVIX_DNS_HOSTS_FILE=] [default: /etc/hosts]
      --dns-name-server <DNS_NAME_SERVERS>
          Name server addresses with ports, replacing those in the resolver configuration [env: NERVIX_DNS_NAME_SERVERS=]
      --domain <DOMAIN>
          Domain the session starts in [default: default]
      --username <USERNAME>
          Registry user to authenticate as [env: NERVIX_USERNAME=] [default: default]
      --password <PASSWORD>
          Password for the registry user; prompted for interactively when unset [env: NERVIX_PASSWORD=]
      --backup-wait-timeout <BACKUP_WAIT_TIMEOUT>
          Overall BACKUP command wait across all domain cuts, redirects and reconnects (default 10m)
      --command <COMMAND>
          Run NSPL statements once and exit instead of starting the interactive REPL
      --suggest <SUGGEST>
          Print completion candidates for NSPL input as JSON and exit
      --cursor <CURSOR>
          UTF-8 byte cursor in --suggest input; defaults to the end
  -h, --help
          Print help

nervix-cli completions

Generate shell completion scripts

Usage: nervix-cli completions [OPTIONS] <SHELL>

Arguments:
  <SHELL>  Target shell [possible values: bash, elvish, fish, powershell, zsh]

Options:
      --backup-wait-timeout <BACKUP_WAIT_TIMEOUT>
          Overall BACKUP command wait across all domain cuts, redirects and reconnects (default 10m)
  -h, --help
          Print help

nervix-cli subscribe

Subscribe to one relay and print events until interrupted

Usage: nervix-cli subscribe [OPTIONS] <NAME> <RELAY>

Arguments:
  <NAME>   Session-local subscription name
  <RELAY>  Relay name to subscribe to

Options:
      --dropping
          Drop delivered events when the session transport queue is full
      --blocking
          Block delivered events when the session transport queue is full
      --batch-sample-rate <BATCH_SAMPLE_RATE>
          Optional per-arrival batch sample rate from 0.0 through 1.0
      --where <WHERE_CLAUSE>
          Optional NSPL predicate applied to delivered records
      --backup-wait-timeout <BACKUP_WAIT_TIMEOUT>
          Overall BACKUP command wait across all domain cuts, redirects and reconnects (default 10m)
  -h, --help
          Print help

nervix-cli domain-clock

Follow the selected domain's clock until interrupted

Usage: nervix-cli domain-clock [OPTIONS]

Options:
      --backup-wait-timeout <BACKUP_WAIT_TIMEOUT>
          Overall BACKUP command wait across all domain cuts, redirects and reconnects (default 10m)
  -h, --help
          Print help

nervix-cli remove-node

Remove a node from the cluster membership

Usage: nervix-cli remove-node [OPTIONS] <NODE_ID>

Arguments:
  <NODE_ID>  Node id to remove

Options:
      --backup-wait-timeout <BACKUP_WAIT_TIMEOUT>
          Overall BACKUP command wait across all domain cuts, redirects and reconnects (default 10m)
  -h, --help
          Print help

nervix-cli cordon-node

Prevent the scheduler from placing new tasks on a node

Usage: nervix-cli cordon-node [OPTIONS] <NODE_ID>

Arguments:
  <NODE_ID>  Node id to cordon

Options:
      --backup-wait-timeout <BACKUP_WAIT_TIMEOUT>
          Overall BACKUP command wait across all domain cuts, redirects and reconnects (default 10m)
  -h, --help
          Print help

nervix-cli uncordon-node

Allow the scheduler to place new tasks on a node

Usage: nervix-cli uncordon-node [OPTIONS] <NODE_ID>

Arguments:
  <NODE_ID>  Node id to uncordon

Options:
      --backup-wait-timeout <BACKUP_WAIT_TIMEOUT>
          Overall BACKUP command wait across all domain cuts, redirects and reconnects (default 10m)
  -h, --help
          Print help

nervix-cli drain-node

Move scheduled graph nodes away from a node and keep it cordoned

Usage: nervix-cli drain-node [OPTIONS] <NODE_ID>

Arguments:
  <NODE_ID>  Node id to drain

Options:
      --backup-wait-timeout <BACKUP_WAIT_TIMEOUT>
          Overall BACKUP command wait across all domain cuts, redirects and reconnects (default 10m)
  -h, --help
          Print help

nervix-cli backup

Back up configuration, users and resources into an archive file

Usage: nervix-cli backup [OPTIONS] --output <OUTPUT> <SCOPE> [NAME]

Arguments:
  <SCOPE>
          What the archive covers: `cluster` for every domain and user, `domain` for one domain

          Possible values:
          - cluster: Every domain and every user
          - domain:  One domain

  [NAME]
          The domain a `domain` backup covers; the session's `--domain` when omitted

Options:
  -o, --output <OUTPUT>
          Where the archive is written; `-` writes it to standard output

      --without-resources
          Record every resource version and its digests without the version's bytes

      --without-state
          Capture configuration only, without pausing domains

      --without-pause
          Capture the latest published state without pausing domains

      --timeout <TIMEOUT>
          Maximum time for each running domain's quiesced capture

      --execution-reference <EXECUTION_REFERENCE>
          Recover the same backup with its original domain and capture options

      --format <FORMAT>
          How the backup's report is printed
          
          [default: text]
          [possible values: text, json]

      --backup-wait-timeout <BACKUP_WAIT_TIMEOUT>
          Overall BACKUP command wait across all domain cuts, redirects and reconnects (default 10m)

  -h, --help
          Print help (see a summary with '-h')

nervix-cli restore

Restore configuration, users and resources from an archive file

Usage: nervix-cli restore [OPTIONS] --input <INPUT> <SCOPE> [NAME]

Arguments:
  <SCOPE>
          What to restore: `cluster` for every domain and user of a cluster archive, `domain` for one domain of an archive

          Possible values:
          - cluster: Every domain and user of a cluster archive
          - domain:  One domain of an archive

  [NAME]
          The archived domain a `domain` restore recreates

Options:
  -i, --input <INPUT>
          The archive file to restore from

      --as <TARGET>
          Restore the domain under this name instead of its archived one

      --on-existing-user <ON_EXISTING_USER>
          What a cluster restore does with an archived user the cluster already has; `fail` when omitted

          Possible values:
          - fail:    Refuse the restore before it changes anything
          - skip:    Keep the existing user and its password
          - replace: Give the existing user the archived password hash

      --resume
          Resume the archived start and clock mapping after installing all state

      --dry-run
          Verify the archive and plan the restore, changing nothing

      --without-state
          Restore configuration without runtime state

      --without-source-offsets
          Restore runtime state but leave source offsets empty

      --format <FORMAT>
          How the restore's report is printed
          
          [default: text]
          [possible values: text, json]

      --backup-wait-timeout <BACKUP_WAIT_TIMEOUT>
          Overall BACKUP command wait across all domain cuts, redirects and reconnects (default 10m)

  -h, --help
          Print help (see a summary with '-h')

Web Console

Every Nervix node serves a browser console. It combines a live drawing of the running execution graph with an NSPL command line, so the same session can be used to read a graph and to change it.

Opening The Console

The console is served by the node itself; nothing extra is deployed. It listens on 0.0.0.0:47420 by default and is served under /console/, with / and /console redirecting there:

http://127.0.0.1:47420/console/

Change the address with --web-console-listen-addr or NERVIX_WEB_CONSOLE_LISTEN_ADDR. The published ports differ by installation method: see Docker and Kubernetes Operator.

Any node works. Opening the console on a follower is supported — the console follows the leader redirect, reconnects there, and reports which node it reached:

connected to leader 'node-2'

Signing In

Without credentials in the URL the console shows a login form for a registry user. Two other forms are accepted, which is what automation and bookmarks use:

• an Authorization: Basic <base64(user:password)> request header
• an ?auth=<base64(user:password)> query parameter

The query parameter puts credentials into browser history and server access logs, so prefer the login form or the header for anything but a local cluster.

Layout

The console is one screen with three regions:

• the sidebar on the left: the domain selector, live throughput for the selected domain, and the domain’s entities grouped by kind — schemas, wire schemas, codecs, resources, clients, vhosts, and endpoints
• the execution graph in the upper right
• the REPL below it, which also hosts any relay subscriptions you open

The top bar carries the websocket connection state, the global Create menu, the Backups button, the domain lifecycle button, the selected clock state, and the theme picker. The clock panel below the domain selector shows the selected domain’s clock in detail.

Sidebar entries are counted per kind and each group collapses. Selecting an endpoint runs its DESCRIBE in the REPL; selecting a resource does the same and opens its version dialog. The Cluster footer stays independent of the selected domain: it reports the number of running domains, non-relay graph nodes, and relays across the current cluster graph.

Following the selected domain clock

Selecting a domain attaches the console session to its clock once. The console selects the first listed domain on its own when none is selected or the selected one disappears, and selecting another domain, from the domain menu or with a typed USE, detaches the previous clock first. The console’s session is served by the leader, so after a connection interruption or a leader change it attaches the selected clock again on the new session; the server releases the earlier attachment when its session ends. A console that holds a transaction attaches it first on a new connection, and while the session holds it the server refuses the clock attachment, as it refuses the automatic detach. The panel shows the attached clock’s typed state and START generation. For a paced clock it also shows logical now, rate, period, skew, the logical origin and UTC anchor, and the latest accepted tick id and logical boundary. Logical now is projected from the committed mapping at the browser’s UTC, refreshed four times a second; a browser whose clock differs from the cluster’s can show a different projection. The tick is the serving node’s accepted observation. Stopped, uninstalled, and unpaced states have no projected logical time. A refused attachment shows its reason and is not retried until the selection or connection changes.

The panel and the top bar’s CLOCK state name the attachment’s phase: NO DOMAIN without a selection, ATTACHING until the attach reply, STOPPED, UNINSTALLED, UNPACED or PACED while it follows the clock, INTERRUPTED while the connection is lost, which shows no projection, REFUSED with the server’s reason, DETACHED after a typed detach, and ENDED with its reason once the server ends the attachment, which the console does not attach again until the selection or connection changes.

Creating Entities From Forms

The top bar’s Create menu opens keyboard-accessible forms for domains, users, resource catalogs, schemas, codecs, signaling protocols, clients, VHOSTs, endpoints, hash maps, Roto UDFs, relays, branches, ingestors, junctions, reingestors, and subscriptions. The resource group in the sidebar also provides a contextual create action. A form keeps its unfinished draft when it closes, restores focus to the action that opened it, reports validation and server failures inline, and shows the canonical NSPL statement before submission. An expression typed into a form, such as a filter, a WHERE predicate, an assigned value or an invocation argument, reads exactly as it does in a typed statement: its string literals are verbatim, so a backslash is an ordinary character. The domain form supports paced and unpaced clocks, period and skew for a paced clock, placement policy, and IF NOT EXISTS. User and resource forms support their corresponding names and the same creation modifier.

Pace and placement are typed choices supplied by the session server. They are searchable and paged independently, and the placement lookup carries the selected pace as a typed dependency. Loading and no matches have separate neutral messages. A missing prerequisite, such as a captured domain or a selected relay for its field list, shows a neutral hint naming what to choose. A stale choice page shows a neutral message and Retry, which requests a fresh first page. Lookup, session-channel, and unreadable-reply failures remain alerts. These states apply to the domain, branch, relay, and subscription forms. An edit, dialog close, or replacement session makes an older reply ineligible to change the form.

A resource draft captures the selected domain the first time it opens. If the console later selects another domain, reopening the retained draft keeps its captured scope and offers Use current domain as an explicit change. Domain and user creation are cluster scoped. Passwords are sent in the canonical command but appear as eight asterisks in both the preview and REPL; the cleartext value is never added to terminal history.

Submitting uses the same durable command path as the REPL. The form therefore keeps the command’s execution reference through redirects and reconnects, uses the attached transaction’s expected position, and reports Editing, Submitting, Queued until reconnect, Queued in transaction, Completed, or Failed from the correlated outcome. A queued transaction operation is not presented as externally complete. A successful standalone resource create opens the existing resource version dialog, where upload identity and completion continue to be owned by the upload workflow.

The Create menu also opens forms for internal schemas, JSON/CBOR/AVRO wire schemas, and named branches. Schema fields are added in declaration order and can be moved or removed. An internal field selects its exact scalar type, then may wrap it in any sequence of variable vectors and fixed arrays; each fixed array needs a positive length. Optional and sensitive flags are separate controls. Wire fields select the types of their chosen format and an explicit STRICT or LOOSE mode. A wire schema’s format is part of its identity, so JSON, CBOR, and AVRO definitions may share a name. The preview and submitted command come from the completed semantic Model’s canonical renderer, just as they do for the earlier forms.

A branch form selects an internal key schema from a server-backed, searchable, paged list, then requires a TTL. It may set a positive maximum instance count with LRU eviction. The schema list uses the draft’s captured domain and the session’s attached transaction prefix, so a schema staged earlier in the same transaction is selectable. Changing the captured domain keeps a previous selection visible but marks it invalid until it is selected again. An invalid branch key schema, including one containing BYTES, is rejected by registry validation and shown inline with the branch and field named. These domain-owned drafts keep their captured scope when reopened; Use current domain changes it explicitly.

A relay form selects the relay’s internal schema from the same kind of list, then states its branching explicitly: UNBRANCHED, or BRANCHED BY with a branch chosen from a searchable, paged list of the captured domain’s branches. A new draft has chosen neither, and it cannot be submitted until one is chosen, so a relay is never unbranched by omission. Capacity starts from the default relay buffer and must be a positive count. Materialized state is NONE or LAST BY TIMESTAMP. Both lists read the attached transaction prefix, so a schema or branch staged earlier in the transaction is selectable, and a relay created while a transaction is attached is queued in it like the other forms’ creates. Changing the captured domain keeps the selected schema and branch visible but invalid until each is selected again. The preview is the canonical CREATE RELAY statement, which always states its capacity.

A codec form selects one current wire format: a declared JSON, CBOR, or AVRO wire schema; the fixed SYSLOG format; a JAQ-native JSON, YAML, TOML, XML, or CBOR format; or Protobuf. The internal schema is an exact typed selection. Declared wire-schema choices are limited to the selected format, even when wire schemas of different formats share a name. JAQ-native and Protobuf codecs choose ingestion (decode), emitting (encode), or both, and may add an emitting-batch program after an emitting program. These are program editors: their contents remain jaq source in the current codec Model, including quotes and whitespace. RFC3339 field encoding rules can be added in order where the format supports them. The preview renders the complete codec Model as canonical NSPL.

The Protobuf controls select an existing resource and one of its completed versions, including LATEST, then accept an optional .proto file and include root, additional compiler configuration entries, message type, and optional batch message type. The resource list includes catalogs staged earlier in the attached transaction; the version list offers completed uploads only. LATEST stays unresolved in the draft and submitted command, and is pinned when the server applies the statement. These controls never create a resource or upload a file as a side effect; provision and upload it explicitly through the resource workflow. Changing the resource or captured domain leaves an earlier version visible but requires selecting it again. A rejected program or configuration reports failure inline and keeps the draft editable.

A signaling protocol form chooses JSON, YAML, TOML, XML, CBOR, RAW, or Protobuf. Protobuf uses the same resource, version, file, include, and compiler configuration controls and requires separate send and wait message types. The ordered handshake editor adds SEND and WAIT steps, moves or removes steps, and keeps each step’s jaq programs in written order. WAIT steps can have multiple matchers, failure matchers, an optional capture when there is exactly one matcher, and ACCEPT DATA. The form also offers connection-wide ACCEPT DATA, failure matchers, and the handshake timeout. Its canonical preview and command preserve the order and raw program text. Both forms use the existing durable command dispatcher and retain rejected drafts, transaction positions, and reconnect handling.

A client form offers every current transport as a typed selection. Connector CONFIG remains an ordered key/value editor whose keys and values are passed to the connector unchanged; the form does not provision external services, topics, buckets, tables, or other objects. Redis, Postgres, MySQL, and MongoDB clients require explicit minimum and maximum pool sizes. A client may mount an existing resource and a completed version. A WebSocket client may select a configured signaling protocol. Switching transports clears transport-specific configuration and signaling choices; changing the resource or captured domain invalidates its version selection. LATEST remains a request until the server applies the statement, when the stored binding becomes an exact version. Configuration rows can be marked secret, and common credential keys and URLs with passwords are treated as secret automatically. Secret inputs use password controls. The preview and the command line history mask those values, while the transmitted command keeps the actual values.

A VHOST form accepts ordered hostnames and may bind TLS to an existing resource and completed version. A TLS VHOST installs its certificate in the HTTPS listener of every live node at command completion, including nodes that do not lead or run the domain’s graph. The certificate bundle must already be uploaded; missing or invalid material follows the existing command failure path and leaves the draft editable. An endpoint form selects an existing VHOST, requires a path, and chooses HTTP or WEBSOCKETS. A WebSocket endpoint may also select a signaling protocol. VHOST and signaling lists are typed, searchable, paged, and scoped to the captured domain, including the attached transaction prefix. An upstream selection or domain change refreshes dependent choices; stale selections must be chosen again before submission. A completed VHOST or endpoint is usable immediately by later commands through the same session.

A hash map form selects a resource, a completed version or LATEST, a codec, and a key field from that codec’s output schema. It also requires the file path within the resource. Codec and key choices read the captured domain and the attached transaction prefix; changing the codec makes an earlier key selection invalid until selected again. A changed resource invalidates its version, and changing the captured domain invalidates all references while leaving them visible for correction. LATEST remains unresolved in the draft and canonical command; the server pins it when the statement applies. The form shows Completed only after the resource file has decoded and the lookup index is ready. A malformed file or unavailable version reports failure inline and keeps the entered path and selections for inspection. A successful hash map can be queried with LOOKUP or used by LOOKUP_HASH_MAP immediately.

A Roto UDF form keeps arguments in declaration order, with exact scalar, vector, and fixed-array types and separate optional flags. The result has the same type controls. The current language is ROTO_0_13, with an explicit volatility control. The source editor preserves its complete text, including quotes, whitespace, the named function body, and Roto test blocks; canonical NSPL chooses a safe dollar-quote delimiter around it. The server checks the declared signature exactly and runs the Roto tests before Completed appears. Compilation, type, or test failure keeps the signature and source editable. A completed function is available to udf:: calls in later commands under the same session and domain.

An ingestor form offers every connector and entity an ingestor reads through a transport: HTTP REQUEST, HTTP ENDPOINT, KAFKA TOPIC, PULSAR TOPIC, MQTT TOPIC, NATS SUBJECT, RABBITMQ QUEUE, REDIS PUBSUB, PROMETHEUS QUERY, ZEROMQ PULL, SQS QUEUE, WEBSOCKETS CONNECTION, WEBSOCKETS ENDPOINT, and SYSLOG LISTENER. Its client or endpoint is a typed choice limited to that pair: clients of its connector, or endpoints of the TYPE its head names. The preview writes the statement under that pair’s head. The source’s own fields, delivery mode, quiesce mode, and required durations or sizes appear as explicit controls. A topic, queue, subject, channel, consumer group, queue group or subscription keeps its text exactly as typed, case and spaces included, and the form refuses a name its entity’s rule refuses. The decoding codec list contains only codecs that support decoding. Timestamp behavior must be chosen explicitly: source timestamp, NOW, or AT a typed field from the codec’s output schema.

Each ingestor route explicitly chooses an unbranched or named branch and a relay with that exact branch declaration. Routes can be added, removed, and moved in order. They edit inheritance, ordered output assignments and function invocations, an optional WHERE expression, branch key assignments, an explicit flush policy, and a route-local message error policy. An ingestor error route selects an unbranched relay and its own field assignments. The node-wide general error policy is also required. The draft retains incomplete values and shows the canonical NSPL preview only when every required choice and expression is valid. It submits through the usual durable command path, including attached transactions and reconnect recovery.

A junction form chooses its exact unbranched or named branch before its input relays. A reingestor chooses inputs first and gives each output route an independent branch action: preserve the input branch, become unbranched, or construct a named branch from ordered key assignments. Additional inputs are offered only when their declared schema and branch match the first input exactly. Both forms keep input predicates, optional collection bounds, materialized dependencies, and output routes in visible order. A materialized dependency resolves against the incoming branch and requires REQUIRED SKIP, REQUIRED WAIT, or DEFAULT with ordered assignments. Each transforming route has ordered inheritance, output assignments, and invocations, an optional predicate, an explicit flush policy, and a route-local message error policy. Server-backed choices restrict output and error relays to the required branch and offer only materialized relays for state. A changed domain or dependent reference keeps the draft visible and requires the affected choice to be selected again. The preview and durable submission use the completed semantic Model; registry validation reports any remaining schema, branch, sensitivity, or graph error inline.

The Execution Graph

The graph is redrawn from snapshots the leader pushes twice a second. It shows external clients, ingestors, processors, relays, and emitters, connected in the direction records flow.

Records always travel from left to right. Items sit in columns ordered by how far a record has travelled, and every item appears to the right of everything that feeds it. Relays get columns of their own between the processing columns, drawn as labelled capsules with a bar per buffer quantile and the p50/p90/p99 depths on hover, so a relay reads as the port its producers converge on and its consumers fan out from. A pipeline with no branching or fan-out is drawn as a single straight line.

Edges run horizontally and vertically with rounded corners, through gutters kept clear of the items, so no edge ever passes under a node, a capsule, or a label. Each edge leaves and arrives at its own attachment point, so a node with several outputs fans out visibly rather than from one spot. Two relations between the same pair of items stay two edges: a node that both reads a relay’s records and looks up its materialized state draws one edge of each style, side by side. Edge style carries meaning:

• solid — records flowing
• dashed, error tint — a route’s ON MESSAGE ERROR destination
• dashed, warning tint — a correlator’s ON TIMEOUT destination; a correlator’s two inputs are labelled LEFT and RIGHT
• dotted, hollow arrow — a materialized-state dependency, including the relay a generator reads with USING MATERIALIZED STATE. State is looked up rather than delivered, so these edges carry no rate

A graph that feeds back on itself — a reingestor writing a relay that reaches it again — draws that one edge as a marked return path above the items it spans, so backwards travel is never mistaken for forward flow. Disconnected parts of a graph are stacked as separate bands.

When traffic is flowing, each edge carries its own rate, with the full messages, bytes, and batches per second on hover, and a pulse travelling along the edge. Where a node declares several routes to the same relay they are drawn as one edge, and hovering reports how many routes it stands for.

Branch groups are drawn as a tinted region with a stacked outline around the part of the graph that runs per branch, containing exactly the items that run per branch and nothing else. Regions of different branches never touch, even where they share a column. The region is headed with the branch name, its key fields, and how many branch instances are currently live; the outline thickens with that count. The count comes from the per-branch statistics of the graph snapshot, which name each concrete branch by the lowercase hexadecimal fingerprint of its key, so a snapshot never carries key values a branch schema may declare SENSITIVE. The ingestors and reingestors that construct the branch, and the emitters and reingestors that collapse it, sit on the region’s border rather than inside it. Clicking the header opens the branch’s key schema and its live instances.

The toolbar controls framing. Search highlights matching items, dims the rest, and brings the matches into view; the zoom buttons step in tens and Ctrl/Cmd with the scroll wheel is continuous, both between 25% and 300%; FIT frames the whole graph, which is also the view you start with; the fullscreen button expands the graph over the whole window. Dragging pans. The graph moves only when the topology changes, and never because traffic changed.

The header carries the domain’s lifecycle state — RUNNING, PAUSED, or STOPPED — and the state of the feed: LIVE while snapshots arrive, STALE when they stop, and OFFLINE when the session is disconnected. A stopped domain still draws its whole graph, with no rates and no pulses.

A domain with no installed graph shows NO ACTIVE DATAFLOW GRAPH instead.

Item Actions

Clicking any node or relay opens its action menu. Each action types the corresponding statement into the REPL and runs it, so the console never does anything you could not have typed:

• DESCRIBE — the runtime view of the item, where the item has a DESCRIBE form
• SHOW CREATE — the NSPL that declares it
• SUBSCRIBE — relays only; opens the subscription form described below for that relay, whose tab runs the same CREATE SUBSCRIPTION the REPL accepts

Node Health

Nodes are drawn with their runtime status. A node whose external connection has failed is marked in error, and an ingestor or emitter waiting to reconnect shows a countdown to its next attempt. Hovering a node reveals the underlying reason. Metrics for alerting belong in the observability endpoint rather than here — see Metrics And Observability.

Subscribing To A Relay

The Create menu’s subscription form opens a read-only session subscription as a tab beside the REPL. A relay’s SUBSCRIBE action opens the same form as a new draft for that relay in the graph’s domain, while the Create menu reopens the retained draft. A draft starts under a generated name such as web_console_subscription_2, which can be edited; names are unique among the console’s tabs.

The relay is selected from a searchable, paged list of the captured domain’s relays. The selected relay’s fields are listed in declaration order with their exact types, OPTIONAL, and SENSITIVE; selecting one inserts a typed input.<field> reference into the filter. The filter is the WHERE predicate over the relay’s record. While it is edited, the form shows its canonical reading, and it refuses to submit text that is not an expression. Checking the fields, scopes, and types the predicate uses belongs to the server, which reports a failure such as a string compared with an integer field when the subscription is created. Delivery is BLOCKING or DROPPING, and batch sampling takes a rate from 0 through 1 that each selected row passes with that probability. The preview is the canonical CREATE SUBSCRIPTION statement the tab sends.

Submitting opens the tab through the same subscription lifecycle as a CREATE SUBSCRIPTION typed in the REPL. The tab waits until the session can serve it, opens and becomes active once the server announces the schema of its rows, and streams records into it. The form reports Completed once the tab is open. It reports Failed with the server’s reason, such as a relay that no longer exists, a filter the server cannot compile, or an open transaction, and then no tab remains and the draft stays editable. A name an open tab already uses fails before anything is sent. After a reconnect or leader change, the console restores each open tab once under its name; the form does not submit it again.

The console restores its tabs before it attaches the session’s transaction again, because a session that holds a transaction refuses subscriptions, so an open transaction does not keep a tab from coming back. A tab stays restoring until the server opens its subscription again. A restoration the server refuses leaves the tab interrupted with the reason, and the console tries it again every second while no transaction is attached; closing an interrupted tab stops that.

When a relay is redefined or removed, the server ends the subscriptions that read it. Such a tab turns ended: it keeps the rows it showed together with the reason, receives nothing more, and is not restored after a reconnect, which would not change why it ended. Its ↻ button resubscribes it under the same name with the statement that first opened it. The tab shows resubscribing until the server answers, then becomes active again with the relay’s current schema. A refusal, such as a relay that no longer exists, leaves the tab ended with the reason. An ended tab keeps its name until it is closed, so resubscribe it or close it before opening another subscription with that name.

Closing the tab ends the subscription; closing an ended tab only removes it, because the server already ended its subscription. Subscriptions are read-only views: they cannot construct, inherit, or produce side effects. See Sessions.

The NSPL REPL

The REPL accepts the same NSPL as the command line client, including the client-local statements USE, LIST DOMAINS, BEGIN, COMMIT, REVERT, and the subscription statements. A typed CREATE SUBSCRIPTION opens a tab in the selected domain exactly as the subscription form does, and DELETE SUBSCRIPTION <name> closes the open tab of that name. The prompt shows the active domain, and marks an open transaction the same way the terminal client does:

nervix[quickstart]>
nervix[quickstart tx]>
nervix[quickstart committing]>

The console sends a statement whether or not a domain is selected, and the server decides whether it needs one: SHOW CLUSTER STATUS or CREATE DOMAIN runs with no domain selected, while a statement that acts on a domain fails with no active domain selected.

A typed BACKUP runs through the Backups dialog, which opens to show its progress and downloads its archive. A typed RESTORE opens the dialog’s restore form with the statement’s options, because the browser cannot read the path the statement names. BACKUP, RESTORE, and DESCRIBE BACKUP must each be sent on their own, and DESCRIBE BACKUP, which reads an archive file on the client’s machine, runs only in nervix-cli.

The REPL renders attachment outcomes, domain-clock state and tick frames, and attachment ends. Tick entries include the id, boundary, authority UTC observation, and serving node’s logical reading. Every tick adds a line, so a fast clock can push earlier output out of the REPL’s latest 256 lines. ATTACH DOMAIN CLOCK and DETACH DOMAIN CLOCK typed into the REPL use the same session-local requests as the automatic attachment, and the console refuses them itself while a transaction is active. A typed second attach is refused as already attached. A typed detach releases the clock and leaves the panel detached until a typed ATTACH DOMAIN CLOCK, another domain selection, or a new connection restores following.

BEGIN requires a selected domain that already exists and binds the transaction to it. The console follows the transaction’s domain, so attaching switches the domain selector to it. DESCRIBE TRANSACTION prints the open transaction’s impact report between queued statements, and with an id it reads another transaction of the same user while the prompt, domain selector, and attached transaction stay as they were. See NSPL Overview for its forms and output.

Every persistent command keeps one execution reference while the browser waits, reconnects, or follows leadership. The transaction id and status are replicated. If the WebSocket closes unexpectedly or leadership changes, the console reconnects and attaches that id before resuming a pending command. Each append is matched by its reference and expected position, and an outstanding commit remains pending through COMMITTING until its exact terminal result. A finished or failed attach does not settle pending commands: the console sends each under its original reference and position to recover its own outcome, or a failure if it was never admitted. The Create form then leaves Queued until reconnect with a completed or failed result. A second session can attach the same owner’s transaction and take it over; the displaced console then gets an explicit takeover error. A clean console session close reverts an open transaction, while an accepted commit continues on the leader without the browser. See Replicated NSPL Transactions and Client Session Protocol.

Tab cycles through completions offered by the server for the current cursor position. ArrowUp and ArrowDown walk the session’s command history, Ctrl/Cmd with Enter submits, and clear empties the scrollback.

Accepting a candidate replaces its exact source range, including the rest of a word after the cursor, while preserving surrounding text. The list shows one bounded page at a time; use MORE SUGGESTIONS to fetch the next page. The console shows a message when the selected domain or transaction context is missing or stale, or when the candidate lookup fails. An empty list with no message means there are no matches.

Bounded Buffers

The console holds a bounded amount of everything it keeps, however long it runs or however fast its session delivers, and says where it left something out:

• The REPL and every subscription tab each keep their latest 256 lines, up to 256 KiB of text, and a line longer than that is cut. The first line then says that earlier lines were omitted.
• The command history behind ArrowUp and ArrowDown keeps the latest 256 commands, up to 256 KiB. Walking back to the oldest command kept says that earlier commands were omitted, and a command larger than the whole history says that it cannot be recalled.
• While the console connects or waits to reconnect, at most 64 requests of its controls wait for the session, carrying at most 4 MiB of statements, completion input, and search text. Once connected, at most 256 requests, carrying at most 16 MiB, are held or awaiting their reply. Commands, subscription changes, and inspections wait in the order they were issued while 64 requests, the most the server admits for one session, are in flight, and go out as earlier replies arrive; a completion, choice lookup, or domain selection goes out at once and is reported if the server finds the session full. A request past either bound is not sent, and the control that issued it shows why where its outcome would have appeared: the REPL, a form, a tab, the resource dialog, or the inspector. A completion request that is not sent reports a failed lookup rather than an empty list.
• The execution graph and sidebar keep only the latest snapshot of the selected domain. Selecting another domain replaces it with that domain’s snapshot, which the server sends at once.
• A backup’s download moves each 256 KiB chunk of the archive into the browser’s own blob storage as it arrives, and the page holds one chunk at a time. A restore reads its archive file one slice at a time, at most 4 MiB while it digests the file and 256 KiB while it streams it, and keeps at most 1 MiB queued on its connection.

Inspecting a transaction

Select Transaction · Inspect in the top bar while a transaction is active. The inspector reads the typed impact report without attaching another transaction or changing the session domain. Use Discover transactions to list retained transactions in the REPL, then enter a transaction ID to inspect one. A DESCRIBE TRANSACTION command also opens its typed result in the inspector; the REPL still prints the server’s text or JSON rendering.

The outline groups accepted operations by their execution steps. Selecting an operation shows its own planned contribution; selecting its step shows the effective pause and effects of the atomic step. Whole transaction shows the union of the steps. Switch between Before, Changes, and After without moving graph items, or between Planned and Actual to review recorded progress. Search frames matching names and kinds; FIT, zoom, and drag control the viewport. Select a node or relation for its before/after presence, roles, and contributing operation numbers. The Relations list offers labeled buttons for keyboard selection of graph edges, including parallel data and materialized-state paths. Role marks and the resource card shape supplement the graph colors.

The summary names the transaction, domain, state, accepted and applied counts, completeness, freshness, aggregate quiesce level, planning basis, relocations, rebuilds, and state resets. An incomplete report shows its diagnostics. A stale preview must be refreshed before retrying COMMIT. The console sends the inspected whole-transaction preview identity with COMMIT, even when an operation is selected. Inspecting another transaction leaves the attached transaction’s commit basis intact. Retained reports keep their own graph geometry when the live execution graph changes.

The inspector receives the same complete typed report as the Rust client and CLI. It does not silently omit nodes, edges, operations, or steps from a large retained report; search, focus, and the outline change what is visible in the viewport without narrowing the result that was read. The Transaction Quiescence And Impact Inspection chapter defines the operation, step, and whole-transaction facts behind these views.

Uploading Resources

The sidebar shows each resource’s highest completed version, such as v2, or catalog while no upload has completed. Selecting a resource opens its version list, read from the typed description that DESCRIBE RESOURCE returns beside the text the REPL prints: every version with each file and directory under its exact path, and under each version the models bound to it, listed by kind and name, or none.

Files or a whole directory can be uploaded from the browser as a new version of that resource in the selected domain. The successful upload result arrives after every current live node has verified and installed the version. An upload moves no binding: models keep the version they pin until REBIND RESOURCE moves them. Version contents and how nodes consume them are covered in Resources.

Backing Up And Restoring

The top bar’s Backups button opens a dialog with two forms, Back up and Restore. They run the same BACKUP and RESTORE statements as nervix-cli, on the console’s own session: they follow its leader redirect, and a statement typed in the REPL runs through the same dialog. Each form is bound to the statement’s options and shows the canonical NSPL it sends before you submit it. Backup And Restore describes what the statements capture and restore.

Taking A Backup

The Back up form backs up the cluster or one domain, the selected domain by default, into the archive file you name. It captures runtime state quiesced, optionally with a drain timeout, live (WITHOUT PAUSE), or not at all (WITHOUT STATE), and can leave resource bytes out (WITHOUT RESOURCES). Back up and download sends the BACKUP as a command. Once it completes, the dialog lists the summary the backup reported: the archive’s size and BLAKE3 digest, when it was captured and until when it can be downloaded, the users, and each domain with its cut, revision, and sections. The REPL prints the outcome as it prints any command’s.

The console then downloads the archive from the leader that assembled it, and checks it as it arrives. It accepts the archive only once every byte arrived and the size and BLAKE3 digest match the summary, and only then hands it to the browser as a download, saved under the last component of the file the statement names; the browser chooses the directory. A partial or altered archive never reaches the browser’s downloads. The first complete download releases the archive on the leader.

A download that fails in transport, stalls, or ends early starts again from the first byte while the leader retains the archive, and Download again retries one that stopped for such a reason. A download the leader refuses, because the archive expired, a download already collected it, or the node that assembled it restarted, ends with that reason; the backup itself completed, and running it again assembles a new archive.

The console records each backup it sends in the browser tab’s session storage until the archive is downloaded. Reloading the page while the backup runs or downloads sends the same backup again under its execution reference: the leader answers with the backup’s recorded outcome instead of running it twice, and the console downloads the archive again from its first byte. The node collects an archive once it has queued the archive’s last bytes for a download, so a reload that comes after that moment finds the archive collected, and the backup must run again. Closing the tab or signing in as another user forgets the record. So does a reload that finds a record the console cannot read back as exactly what it wrote, such as one edited outside the console; the reload then resumes nothing. An archive stays downloadable only while it is retained, by default for 15 minutes from the moment the console sent the backup.

The browser saves the archive with the permissions of its downloads directory. An archive holds password hashes, client secrets, and TLS private keys, so keep a downloaded archive where only its owner can read it.

Restoring An Archive

The Restore form restores one domain of an archive, under its archived name or a new one, or a whole cluster archive with its policy for users the cluster already has. It can resume the restored domains at their archived lifecycle, and leave out source offsets or all runtime state.

Choose the archive file, set the options, and select Dry run. The console reads the file once to measure its size and BLAKE3 digest, then streams it to the leader with the statement’s DRY RUN form, showing how many bytes it has read and sent. The dry run reports what the restore would create: each domain under the name it would have, with its status, start version, models, and resource versions, and every step it would apply. The planned model run of each domain is drawn with the transaction inspector’s view.

Restore streams the archive again and runs the same statement without DRY RUN. It stays disabled until a dry run of the current options and file has planned the restore. The result lists each step as applied, failed, or not attempted: a restore that fails at a step keeps the steps before it, and the dialog names the step. A refusal shows the leader’s reason, such as a domain that already exists or an archive that is not a valid backup archive, and changes nothing.

A restore that skips archived state says so. The result lists the restore’s warnings above its report, as nervix-cli prints them: the state the restored schedule cannot take, such as a window whose model changed, with the reason. The REPL prints the same warnings after the restore’s message.

A restore runs outside transactions, so the form refuses while the session holds one. Every attempt sends the same execution reference, statement, and archive: a lost connection or an unknown outcome streams the archive again, from its first byte, until the leader answers. If no answer arrives within about ten minutes, the dialog reports the restore’s outcome as unknown and names its execution reference.

The console never renders what an archive holds beyond the summary a backup reports and the report a restore returns.

Domain Lifecycle

The sidebar’s domain selector switches the console between domains; the top bar shows the selected domain’s state and runs START; or STOP; for it. Both statements appear in the REPL as if you had typed them. See Start And Stop.

Themes

Four themes are available from the top bar: Dark navy (the default), Pure dark, D0ZNPP, and Light.

NSPL Formatter

nervix-nspl-format puts NSPL files into their canonical shape. It is an offline tool: it never opens a session, contacts a cluster, or executes anything it reads. It parses a file, renders every statement canonically, writes the result back, and can instead report which files would change.

The shape it writes is the same one SHOW CREATE prints, so text copied between a file and a session is already formatted.

Installing

The formatter is installed alongside the other tools; see Cargo Install From GitHub.

Using It

nervix-nspl-format pipeline.nspl              # format one file in place
nervix-nspl-format .                          # format every NSPL file beneath here
nervix-nspl-format --check .                  # report instead of rewriting
nervix-nspl-format --stdout pipeline.nspl     # write to standard output
cat pipeline.nspl | nervix-nspl-format -      # read standard input

--check and --stdout cannot be combined, and - cannot be combined with other paths.

Searching Directories

A path naming a directory is searched recursively for .nspl files. The search honors your .gitignore and skips hidden directories, so it never descends into build output or vendored trees, and it does not follow symbolic links. Files are formatted in a stable order, so --check output is reproducible.

A path naming a file is formatted whatever its extension — naming a file is an explicit request. Only the recursive search filters by extension, which is why a template such as graph.nspl.upon is never picked up by nervix-nspl-format ..

There is no built-in diff. To see what would change:

nervix-nspl-format --stdout pipeline.nspl | diff -u pipeline.nspl -

Exit Codes

A file that fails never blocks the others: every failure is reported and every other file is still formatted. A file that fails is left exactly as it was.

What It Guarantees

• Meaning is preserved. Reparsing the output yields exactly the statements that went in. The formatter checks this itself before writing, and refuses to write if it ever fails.
• Formatting is idempotent. Formatting an already formatted file changes nothing, byte for byte, and the file is not rewritten at all — so modification times do not churn.
• Comments survive. A comment between two statements stays between them, and a comment above a statement stays above it. A file header and a comment trailing the last statement are kept.
• Writes are atomic. The result is written to a temporary file in the same directory and renamed over the target, so an interrupted run never leaves a partly written file.

What It Changes

Formatting a hand-written file for the first time normalizes more than layout:

• Keywords are uppercased, including type names, and identifiers are lowercased — NSPL lowercases identifiers when it parses them, so this is the name the cluster already uses.
• String literals prefer single quotes; a value containing an apostrophe uses double quotes, and a value containing a newline or both quote styles is dollar-quoted, with a delimiter the value cannot close early, not even with its last characters.
• Line endings become \n, except inside a string literal, whose line breaks are part of its value and are kept exactly as written. Trailing whitespace is dropped from comments.
• An MQTT topic stays bare only when it is a lower-case identifier; any other topic, including one with an upper-case letter, is quoted, because MQTT topics are case-sensitive.
• A START AT timestamp is written in UTC with an explicit +00:00 offset. A leap second, which RFC 3339 writes as :60, is written as the instant it reads as: one second past the second before it.
• Values that were left implicit are written out, such as a relay’s CAPACITY and an ingestor’s INSTANCES.
• Redundant parentheses are dropped from expressions, keeping only those that change grouping.

Durations and byte sizes keep the spelling you wrote: 250ms stays 250ms, and 1MiB stays 1MiB. A domain’s PERIOD and SKEW, a generator’s EACH and a polling ingestor’s EVERY are held as nanoseconds, so they are written as one whole number of the largest unit that divides them exactly: 1500ms stays 1500ms, and 60s becomes 1m.

Comments Inside A Statement

A comment between two statements has one obvious place to go. A comment inside a statement does not, so the formatter does not guess: a statement containing a comment in its body is written back exactly as you wrote it, and the statements around it are still formatted.

That statement keeps its original layout until the comment is moved out of it. This is deliberate — the alternative is relocating a comment away from the clause it explains.

NSPL Agent Skill

Nervix publishes a portable Agent Skills package that teaches compatible AI coding agents how to design, explain, review, and troubleshoot Nervix configurations written in NSPL. The maintained source is nervix-io/nervix/.agents/skills/nspl.

The skill contains guidance and references, not a Nervix client or server. Review its contents before installing it, just as you would review any third-party instructions supplied to an agent. It is distributed under the repository’s FCL-1.0-ALv2 license.

The skill discovers public language documentation through the versioned llms.txt index. That endpoint selects the latest published documentation version, whose relative Markdown links remain pinned to the same immutable build. The index intentionally covers the public NSPL configuration surface rather than Nervix internals or local-development instructions.

You do not need to clone the Nervix repository. The installer downloads the skill directly from the public GitHub repository, and the installed skill uses the public Nervix documentation.

Quick Start

1. Preview And Install The Skill

The skill becomes installable directly from the public repository as soon as it is merged into the default branch. A separate package upload, repository clone, or GitHub release is not required.

GitHub CLI 2.90.0 or newer provides the preview gh skill commands. If gh skill is unavailable, install or update GitHub CLI before continuing. Then inspect the complete skill before installing it:

gh skill preview nervix-io/nervix nspl --allow-hidden-dirs

Install it for one agent at user scope so it is available in every project. This Codex example can use claude-code, kimi-cli, or another value listed by gh skill install --help instead:

gh skill install nervix-io/nervix nspl \
  --allow-hidden-dirs \
  --agent codex \
  --scope user

The --allow-hidden-dirs option is required because the maintained source lives under .agents/skills/nspl. GitHub CLI records the repository source with the installation so it can be updated later.

Cross-Agent Installer

The skills CLI is an alternative that can install into multiple supported agents at once, including agents not currently supported by gh skill. It requires Node.js and can run directly through npx.

Install the NSPL skill for your user account so it is available in every project:

npx skills add nervix-io/nervix --skill nspl --global

The installer detects supported coding agents and asks which ones should receive the skill. It can install one canonical copy and create the agent-specific links needed by Claude Code, Codex, Cursor, Kimi Code CLI, GitHub Copilot, Gemini CLI, OpenCode, Grok Build, and other supported agents.

For a non-interactive installation into every agent supported by the installer:

npx skills add nervix-io/nervix --skill nspl --global --agent '*' --yes

Use --agent '*' only when all of those integrations are intentional. For a smaller installation, repeat --agent with the desired identifiers:

npx skills add nervix-io/nervix \
  --skill nspl \
  --global \
  --agent claude-code \
  --agent codex \
  --agent kimi-code-cli \
  --agent grok

Both installers download only the skill content needed by the selected agents. Neither command clones Nervix into the current directory.

2. Start A New Agent Session

Open the selected coding agent in your own project, configuration repository, or any other working directory. Start a new session after installation so the agent discovers the newly installed skill.

3. Ask The Agent To Use NSPL

The most portable invocation is to name the skill in the request:

Use the nspl skill to design a Nervix configuration that reads JSON orders from Kafka,
deduplicates them by order_id for 10 minutes, and publishes valid orders to another Kafka topic.
Use placeholders for broker addresses and credentials.

Agents may also expose installed skills through a skill picker or command. For example, use $nspl or /nspl when the selected agent supports that form:

$nspl Review this Nervix configuration for invalid types, missing flush policies, and branch
isolation problems: <paste NSPL here>

The agent can also select the skill automatically from an ordinary request about authoring, explaining, reviewing, or troubleshooting a Nervix configuration. Naming nspl explicitly is useful when you want to guarantee that the installed guidance is loaded.

Describe What You Need

Give the agent as much of this deployment contract as you know:

• the input system, external topic, queue, stream, table, or other entity, and a sample payload;
• the required internal fields and exact types, when known;
• whether records are unbranched or isolated by fields such as tenant, device, or customer;
• filtering, transformation, deduplication, windows, correlation, inference, lookup, or custom WASM processing;
• operator-trusted Roto UDF requirements, including representative cases for test blocks;
• the output system and desired payload shape;
• delivery, ordering, batching, flush, error-handling, TLS, and credential requirements; and
• whether you want a new graph, an explanation, a review, or help diagnosing an error.

Use this copyable template when starting from a new graph:

Use the nspl skill to produce a complete Nervix configuration.

Input system and external entity:
Sample input payload:
Required processing:
Branch key, or unbranched:
Output system and external entity:
Delivery, flush, and error requirements:
Deployment-specific values that should remain placeholders:

Return assumptions, external prerequisites, ordered NSPL command phases, and verification
commands. Do not invent undocumented syntax.

If details are missing, the skill directs the agent to ask only questions that materially change the graph or to use conspicuous placeholders and state its assumptions.

Use The Result

A generated configuration should contain:

1. assumptions and external prerequisites;
2. separate client-local and transactional server command phases;
3. complete NSPL with deployment placeholders called out; and
4. relevant SHOW, DESCRIBE, lookup, or subscription commands for verification.

An agent-generated Roto UDF should also contain test blocks for its contract. Nervix runs those tests during CREATE UDF; any rejecting test prevents the UDF from being persisted. See User-Defined Functions. For replay-sensitive functions, tests should also protect the deterministic-by-default and VOLATILE contract.

The skill does not connect to or configure a running Nervix deployment by itself. Review the result, replace placeholders, provision required external entities such as Kafka topics, and then submit the NSPL through your normal Nervix client workflow. See the NSPL Overview for the current language documentation.

Install For One Project

With GitHub CLI, change the scope from user to project:

gh skill install nervix-io/nervix nspl \
  --allow-hidden-dirs \
  --agent codex \
  --scope project

With the cross-agent installer, omit --global:

npx skills add nervix-io/nervix --skill nspl

Run the command from the target project’s root. Review the generated agent directories before committing them because project-scoped installations become part of that project rather than the Nervix repository.

Verify The Installation

List skills installed by GitHub CLI:

gh skill list

List globally installed skills:

npx skills list --global

For a project-scoped installation, run npx skills list from the project root. Confirm that nspl appears for the expected agents.

Update The Skill

Update an installation managed by GitHub CLI:

gh skill update nspl

Update a global installation to the latest version from the default branch of nervix-io/nervix:

npx skills update nspl --global

Update a project-scoped installation from that project’s root:

npx skills update nspl --project

Start a new agent session after updating when an existing session has already loaded the previous skill contents. Update the skill whenever upgrading Nervix or when the public NSPL surface changes.

For stricter reproducibility, install a reviewed commit instead of following repository updates:

gh skill install nervix-io/nervix nspl \
  --allow-hidden-dirs \
  --agent codex \
  --scope user \
  --pin <commit-sha>

Pinned installations do not update until they are reinstalled with a different commit.

Trust And Safety

Keeping the skill in the Nervix repository makes its changes visible in the same version history and code review as NSPL and its documentation. It does not make installed skills inherently trusted: a skill supplies instructions to an agent, and future updates can change those instructions.

• Preview the skill before installing or updating it.
• Review changes to SKILL.md and every bundled reference as carefully as code changes.
• Pin a reviewed commit when reproducibility matters more than automatic updates.
• Never add credentials or deployment secrets to a skill directory.
• Remember that an agent follows a skill with the permissions already available to that agent; the skill itself grants no additional access.

The current NSPL skill contains instructions, public-documentation references, and display metadata. It contains no executable scripts.

Manual Installation

If Node.js or the skills CLI is unavailable, download the complete nspl skill directory and copy it into a skill location supported by the target agent. Keep SKILL.md, references/, and any future bundled resources together.

Common project-level locations include:

• .agents/skills/nspl/ for Codex, Kimi Code CLI, GitHub Copilot, Cursor, Gemini CLI, Antigravity, and OpenCode
• .claude/skills/nspl/ for Claude Code
• .grok/skills/nspl/ for Grok Build

For a manual update, replace the entire installed nspl directory with the latest directory from the repository. Do not update only SKILL.md, because its bundled references are part of the same versioned skill.

Manual

This section is the user-facing guide to Nervix. If you are new to Nervix, the Quickstart builds a first graph step by step; this section is the full reference behind it.

Nervix is experimental software in active development. It is intended for evaluation, local testing, and design exploration. It is not suitable for real production workloads.

Use it for:

• understanding product boundaries and non-goals
• learning the NSPL surface
• understanding the currently supported transport integrations, including Kafka and Pulsar
• defining schemas, resources, relays, ingestors, processors, and emitters
• planning branch capacity from the documented cost structure and current signals
• working with sessions and the Rust client
• following end-to-end examples

To write custom WASM processor guests in Rust, continue to the Rust WASM Guest SDK. If you want implementation details, runtime internals, or control-plane/data-plane architecture, continue to Architecture And Internals.

What It Is Not

Nervix is not an exactly-once transactional engine.

With ACK-based ingestion modes, Nervix behaves as an at-least-once system. Without ACK tracking, it behaves as at-most-once. That is an intentional design choice: Nervix prioritizes throughput and low latency over transactional persistence on every action.

Operationally, Nervix is much closer to a high-performance in-memory relaying runtime with snapshot-style replicated state than to a transactional database or durable event log.

Important consequences:

• Raft-backed strong consistency applies to the control plane, not to the data plane.
• Records moving through ingestors, processors, and emitters do not cross an exactly-once transactional boundary.
• ACKs control retry and replay behavior. They do not provide exactly-once execution and are not persisted.
• Runtime state persistence and replication are practical recovery mechanisms for selected execution node state, not atomic commit boundaries across the whole graph.
• Nervix does not provide arbitrary-key queries against live runtime state from expressions. Materialized state is readable only inside its own branch. Cross-key access is out of scope because serving arbitrary keyed reads is database behavior. Nervix’s database-like surfaces, including materialized streams and resource-backed lookups, are structurally amortized instead. See Choosing An Enrichment Mechanism.

The data plane operates in two broad modes:

1. Pure in-memory stream processing. Records traveling through relays and runtime nodes stay in memory while they are being routed and processed. ACK guards, ACK tokens, and ACK maps are part of this hot path and are not persisted.
2. Snapshot-style replicated runtime state. Selected runtime state such as Kafka domain offsets, deduplicator state, and materialized relay state is snapshotted to persistent storage and replicated to followers. WASM guest state is the one kind a source acknowledgement waits for: an ATTACHED WASM processor checkpoints its guest state to stable storage and to every assigned replica before it acknowledges the inputs the checkpoint covers. That checkpoint still does not make the path exactly once; see Recovery, Replay And Duplicates.

The execution graph itself is different: NSPL models and domain schedules are control-plane state and are persisted with strong consistency guarantees before the data plane runs them.

Each runtime graph node is scheduled onto one cluster node and may have replicas. Replicas maintain eventually consistent copies of replicated runtime state and are designed to catch up through the replication channel.

NSPL Overview

NSPL is the language used to define the Nervix graph.

Language Stability

NSPL has reached alpha. Its period of rapid, broad experimentation is over, and large backward-incompatible changes are no longer expected. The language is more stable, but alpha is not a promise of backward compatibility: NSPL will continue to evolve, and focused breaking changes may still be made when they materially improve the language model or correctness.

AI coding agents can use the portable NSPL Agent Skill to design, explain, review, and troubleshoot Nervix configurations. The guide explains installation without cloning this repository, skill invocation, useful request details, expected output, and updates.

For application-owned producers and consumers, Client Ingestors And Emitters connects the native endpoint grammar to a complete graph and its execution contracts.

The current top-level surface includes:

• domain lifecycle statements
• user statements
• create/alter/drop model statements
• resource lifecycle statements
• session subscription statements
• explicit transaction controls: BEGIN, COMMIT, and REVERT
• describe and show commands

Core create statements:

CREATE [IF NOT EXISTS] USER <name> WITH PASSWORD '<password>';

CREATE [IF NOT EXISTS] SCHEMA <name> (<field> <type> [OPTIONAL], ...);
CREATE [IF NOT EXISTS] WIRE JSON SCHEMA <name> MODE STRICT|LOOSE (<field> <json_type> [OPTIONAL], ...);
CREATE [IF NOT EXISTS] WIRE CBOR SCHEMA <name> MODE STRICT|LOOSE (<field> <cbor_type> [OPTIONAL], ...);
CREATE [IF NOT EXISTS] WIRE AVRO SCHEMA <name> MODE STRICT|LOOSE (<field> <avro_type> [OPTIONAL], ...);

CREATE [IF NOT EXISTS] CODEC <name>
  FROM WIRE JSON SCHEMA <wire_schema>
  TO SCHEMA <schema>
  [ENCODE <field> AS RFC3339, ...];

CREATE [IF NOT EXISTS] CODEC <name>
  FROM WIRE CBOR SCHEMA <wire_schema>
  TO SCHEMA <schema>
  [ENCODE <field> AS RFC3339, ...];

CREATE [IF NOT EXISTS] CODEC <name>
  FROM WIRE AVRO SCHEMA <wire_schema>
  TO SCHEMA <schema>
  [ENCODE <field> AS RFC3339, ...];

CREATE [IF NOT EXISTS] CODEC <name>
  FROM JSON|YAML|TOML|XML|CBOR
  TO SCHEMA <schema>
  WITH JAQ TRANSFORMATIONS
  [ON INGESTION '<program>']
  [ON EMITTING '<program>' [ON EMITTING BATCH '<program>']];

CREATE [IF NOT EXISTS] CODEC <name>
  FROM PROTOBUF
  USING RESOURCE <resource> VERSION <n> | LATEST
  CONFIG {'file' = '<path.proto>', 'include' = '.'}
  MESSAGE '<package.Message>'
  [BATCH MESSAGE '<package.BatchMessage>']
  TO SCHEMA <schema>
  WITH JAQ TRANSFORMATIONS
  [ON INGESTION '<program>']
  [ON EMITTING '<program>' [ON EMITTING BATCH '<program>']];

CREATE [IF NOT EXISTS] CODEC <name>
  FROM SYSLOG
  TO SCHEMA <schema>;

CREATE [IF NOT EXISTS] RELAY <name> SCHEMA <schema> [CAPACITY <n>]
  [WITH MATERIALIZED STATE LAST BY TIMESTAMP];

CREATE [IF NOT EXISTS] PLACEMENT <name>
  FROM <runtime_node> [, <runtime_node> ...]
  TO <runtime_node> [, <runtime_node> ...]
  REQUIRE COLOCATION|PREFER COLOCATION|NEUTRAL|SUGGEST SEPARATION
  [RANK <n>];

JAQ-backed codecs require at least one direction. When both are present, ON INGESTION precedes ON EMITTING.

Core alter statements:

ALTER DOMAIN SET PLACEMENT
  REQUIRE COLOCATION|PREFER COLOCATION|NEUTRAL|SUGGEST SEPARATION;

ALTER RELAY <name>
  SET CAPACITY <n> |
  SET SCHEMA <schema> |
  SET BRANCHED BY <branch> |
  SET UNBRANCHED |
  SET MATERIALIZED STATE LAST BY TIMESTAMP |
  DROP MATERIALIZED STATE
  [, ...];

ALTER JUNCTION <name>
  ADD FROM <relay> [WHERE <expr>] |
  DROP FROM <relay> |
  ALTER FROM <relay> SET WHERE <expr> |
  ALTER FROM <relay> DROP WHERE |
  SET COLLECT FOR <duration> [MAX BATCH SIZE <bytes>] |
  DROP COLLECT |
  SET FILTER WHERE <expr> |
  DROP FILTER WHERE |
  SET ATTACHED | SET DETACHED |
  SET BRANCHED BY <branch> | SET UNBRANCHED |
  ADD|DROP|ALTER MATERIALIZED STATE ... |
  ADD|DROP|REPLACE ROUTE ...
  [, ...];

ALTER DEDUPLICATOR <name>
  SET DEDUPLICATE ON <expr> [, <expr> ...] |
  SET MAX TIME <duration> |
  ADD|DROP|ALTER FROM ... |
  SET|DROP COLLECT ... |
  SET|DROP FILTER WHERE ... |
  SET ATTACHED | SET DETACHED |
  SET BRANCHED BY <branch> | SET UNBRANCHED |
  ADD|DROP|ALTER MATERIALIZED STATE ... |
  ADD|DROP|REPLACE ROUTE ...
  [, ...];

ALTER REORDERER <name>
  SET BY <expr> [, <expr> ...] |
  SET MAX TIME <duration> |
  ADD|DROP|ALTER FROM ... |
  SET|DROP COLLECT ... |
  SET|DROP FILTER WHERE ... |
  SET ATTACHED | SET DETACHED |
  SET BRANCHED BY <branch> | SET UNBRANCHED |
  ADD|DROP|ALTER MATERIALIZED STATE ... |
  ADD|DROP|REPLACE ROUTE ...
  [, ...];

ALTER EMITTER <name>
  ADD FROM <relay> [WHERE <expr>] |
  DROP FROM <relay> |
  ALTER FROM <relay> SET WHERE <expr> |
  ALTER FROM <relay> DROP WHERE |
  SET TO <full sink clause including MODE> |
  SET MODE <transport-specific publishing mode body> |
  SET CLIENT <client> |
  SET ENCODE USING <codec> | DROP ENCODE |
  SET COLLECT FOR <duration> [MAX BATCH SIZE <bytes>] | DROP COLLECT |
  SET ATTACHED | SET DETACHED |
  SET BATCH MAX MESSAGES <n> MAX SIZE <bytes> | DROP BATCH |
  SET FLUSH EACH <duration> MAX BATCH SIZE <bytes> | SET FLUSH IMMEDIATE |
  SET COMMIT EACH <duration> MAX SIZE <bytes>
  [, ...];

ALTER <CONNECTOR> <ENTITY> INGESTOR <name>
  SET FROM <body> |
  SET QUIESCE <quiesce body> |
  SET DECODE USING <codec> |
  SET TIMESTAMP NOW | SET TIMESTAMP AT <field> | DROP TIMESTAMP |
  SET FILTER WHERE <expr> | DROP FILTER WHERE |
  ADD|DROP|REPLACE ROUTE ... |
  SET GENERAL ERROR IGNORE|LOG
  [, ...];

ALTER REINGESTOR <name>
  ADD|DROP|ALTER FROM ... |
  SET|DROP COLLECT ... |
  SET|DROP FILTER WHERE ... |
  SET ATTACHED | SET DETACHED |
  ADD|DROP|ALTER MATERIALIZED STATE ... |
  ADD|DROP|REPLACE ROUTE TO <relay> <construction> BRANCHED BY <branch>|UNBRANCHED ...
  [, ...];

ALTER GENERATOR <name>
  SET MATERIALIZED STATE <relay> |
  SET EACH <duration> |
  SET BRANCHED BY <branch> | SET UNBRANCHED |
  ADD|DROP|REPLACE ROUTE ...
  [, ...];

ALTER PLACEMENT <placement>
  SET POLICY REQUIRE COLOCATION|PREFER COLOCATION|NEUTRAL|SUGGEST SEPARATION |
  SET RANK <n> |
  DROP RANK |
  SET FROM <runtime_node> [, ...] TO <runtime_node> [, ...] |
  RENAME TO <name>
  [, ...];

ALTER SCHEMA <name>
  ADD FIELD <field> <type> [OPTIONAL] [SENSITIVE],
  DROP FIELD <field>,
  RENAME FIELD <field> TO <field>,
  ALTER FIELD <field> SET TYPE <type>,
  ALTER FIELD <field> SET|DROP OPTIONAL,
  ALTER FIELD <field> SET|DROP SENSITIVE;

ALTER WIRE JSON|CBOR|AVRO SCHEMA <name>
  MODE STRICT|LOOSE,
  ADD FIELD <field> <wire_type> [OPTIONAL],
  DROP FIELD <field>,
  RENAME FIELD <field> TO <field>,
  ALTER FIELD <field> SET TYPE <wire_type>,
  ALTER FIELD <field> SET|DROP OPTIONAL;

Operations in one ALTER RELAY, ALTER JUNCTION, ALTER DEDUPLICATOR, ALTER REORDERER, ALTER EMITTER, ALTER <CONNECTOR> <ENTITY> INGESTOR, ALTER REINGESTOR, ALTER GENERATOR, or ALTER PLACEMENT execute in written order. An ingestor’s ALTER repeats the connector and entity the ingestor reads, such as ALTER KAFKA TOPIC INGESTOR, and never changes them. See Streams And State for relay operations, Processors for the full processor operation shapes, and Emitters and Ingestors for boundary-node operations. See Schemas And Codecs for ordered schema changes and atomic migrations, and Placement Policies for placement rank, path coverage, and enforcement.

All CREATE statements may optionally insert IF NOT EXISTS immediately after CREATE.

When IF NOT EXISTS is present and the named entity already exists, the command succeeds as a no-op instead of failing. Command responses also mark that condition explicitly with already_existed = true.

The rest of the graph is built with:

• CREATE DOMAIN, CREATE UNPACED DOMAIN, CREATE PACED DOMAIN
• CREATE USER
• CREATE CLIENT
• CREATE VHOST
• CREATE ENDPOINT
• CREATE <CONNECTOR> <ENTITY> INGESTOR, such as CREATE KAFKA TOPIC INGESTOR or CREATE CLIENT PRODUCER INGESTOR; see Ingestors
• CREATE GENERATOR
• CREATE INFERENCER
• CREATE JUNCTION
• CREATE DEDUPLICATOR
• CREATE REINGESTOR
• CREATE EMITTER
• CREATE PLACEMENT
• CREATE HASH MAP

CREATE DOMAIN <name> is the short spelling for CREATE UNPACED DOMAIN <name>.

Domain creation may declare a placement default, and named placement rules may overlay paths in the active domain. Omission means NEUTRAL, which preserves ordinary scheduler heuristics. See Placement Policies for the four policy levels and lifecycle commands.

Multiple NSPL statements in one request must be wrapped in an explicit transaction. BEGIN creates a replicated transaction and returns its id, COMMIT executes the queued statements, and REVERT drops them without applying them. A transaction survives an unclean disconnect or leader failover; the CLI and web console re-attach before sending another command. Sending multiple statements without BEGIN is rejected.

CREATE DOMAIN production;
USE production;

BEGIN;
CREATE SCHEMA notification (user_id I64);
COMMIT;

BEGIN binds the transaction to the selected domain, which must already exist, and every queued statement must select that same domain. BEGIN inside an active transaction is an error. COMMIT and REVERT also require an active transaction. Queueable content is limited to that domain’s model mutations, including REBIND RESOURCE, domain configuration and lifecycle, and CREATE RESOURCE. CREATE DOMAIN, CREATE USER, most read-only statements, subscriptions, resource uploads, and node administration are not valid inside a transaction and must be sent separately. SHOW TRANSACTIONS; and DESCRIBE TRANSACTION run separately beside an attached transaction without entering its queue or changing its binding. Use SHOW TRANSACTIONS; to inspect live transactions and retained outcomes. See Control Plane for attach, failover, commit-step, expiry, and limit semantics.

DESCRIBE TRANSACTION reads one transaction’s impact report without changing that transaction:

Transaction Quiescence And Impact Inspection explains the planned and actual scopes, affected topology, and retained outcomes reported by this statement.

DESCRIBE TRANSACTION [ '<id>' ] [ OPERATION <n> ] [ FORMAT TEXT | JSON ];

Without an id it reads the transaction attached to the session. A quoted id, as BEGIN and SHOW TRANSACTIONS print it, reads that transaction instead; it must belong to the same user, and reading it never attaches it or selects its domain. OPERATION <n> names an accepted operation, numbered from 1 in the order the statements were queued, and leads the report with that operation and the execution step it belongs to without narrowing the rest. TEXT is the default; FORMAT JSON prints the same report as one JSON document. Both formats contain the complete report. Large affected graphs and repeated execution steps are not paginated or shortened; plan client response memory and output handling for the transaction’s accepted operation count and affected topology. In the Rust client, reading the attached transaction at its current queue position refreshes the preview supplied with a later COMMIT. An inspection of another id leaves that preview and the session binding untouched. After a stale-preview refusal, inspect the attached transaction again before retrying the commit.

The statement is the one read-only statement allowed while a transaction is open. It is answered before queueing, so it never becomes transaction content and never consumes an operation number, but it must be sent on its own rather than inside a multi-statement request:

// The transaction attached to this session.
DESCRIBE TRANSACTION;
// Its second queued operation first.
DESCRIBE TRANSACTION OPERATION 2;
// A transaction by id, as one JSON document.
DESCRIBE TRANSACTION '01a0ca64-7062-7302-ac1e-43138ccc2067' FORMAT JSON;

For two queued schemas, the text report reads:

transaction: 01a0ca64-7062-7302-ac1e-43138ccc2067
domain: production
state: OPEN
operations: 2 accepted, 0 applied, 2 pending
report: COMPLETE
planning basis: 10b2c6ecf022ec0f2d9149fe98039cc065533d326e5dba7ea74660f64b893ef8
quiesce level: DYNAMIC
pause: NO_PAUSE
operation 1: CREATE_CONFIGURATION kind=schema name=notification
  execution step: 1-2
  reason: CONFIGURATION kind=schema name=notification aspect=ENTITY_CREATED
operation 2: CREATE_CONFIGURATION kind=schema name=delivery
  execution step: 1-2
  reason: CONFIGURATION kind=schema name=delivery aspect=ENTITY_CREATED
execution step 1-2: planned DYNAMIC, actual DYNAMIC, outcome UNATTEMPTED
  pause: NO_PAUSE
  effect: configuration CREATED kind=schema name=delivery operations=2
  effect: configuration CREATED kind=schema name=notification operations=1
  effect: topology before nodes=0 edges=0 after nodes=2 edges=0

A paused subgraph lists each paused node and admission gate under its pause: line with the operations that require it, and a finished transaction reports the APPLIED or FAILED outcome each execution step recorded, for as long as its outcome is retained. An inspection that cannot be answered says why: no transaction is attached, the id is unknown or its retention has expired, the transaction belongs to another user, the operation number is past the operations it accepted, or no coherent report can be read for it, as for a transaction that ended before planning any operation. See Control Plane for what each transaction state reports.

Ingestors, relay-consuming processors, and generated-output processors use optional node-level arrival filters and route-local construction. Relay-consuming processors may also attach a source-level filter to FROM:

FROM <relay> [WHERE <expr>], ...
[COLLECT FOR <duration> [MAX BATCH SIZE <bytes>]]
[FILTER WHERE <expr>]
TO <relay>
  [INHERIT ...]
  [SET <field> = <expr>, ...]
  [WHERE <expr>]
  FLUSH ...
  ON MESSAGE ERROR ...
[TO <relay> ...]

COLLECT FOR is optional on graph nodes that consume relay input through FROM. It is unavailable to ingestors, which read external sources rather than relays. When omitted, each incoming Arrow batch proceeds directly to node execution. When present, Nervix maintains an input batch independently for each source relay and concrete branch, then executes the node when the duration expires or the optional size boundary is reached. Correlators configure the clause independently after each LEFT FROM and RIGHT FROM relay list. Emitters place it after their complete FROM <relay> [WHERE ...] [, ...] list. All emitter inputs declare the same payload schema, but they may belong to differently named branches; collection remains independent for each source relay and concrete branch. Generators do not read a FROM relay and therefore have no input collection clause. The duration is measured on the domain clock and starts when the source and branch collector changes from empty to non-empty. A paced domain’s TIME RATE scales that wait.

FROM ... WHERE runs first. FILTER WHERE runs next, before the node accepts rows into its state, buffer, inferencer, or guest. Every route then creates a new empty output, performs its own ordered construction, finalizes the declared schema, and evaluates its route WHERE. Required fields must be initialized; omitted optional fields become typed nulls. There is no implicit identity transformation and no global SET or INHERIT.

Input collection assembles relay batches before that execution sequence. Its time and size include rows that a later source or node filter may reject. COLLECT FOR controls input delivery to the node; route-local FLUSH controls output delivery from the node. The two policies are independent.

Transforming routes use one working message from input through finalization. Transforming routes—ingestors after decoding, reingestors, junctions, deduplicators, reorderers, and codec emitters—may use INHERIT. Generators, windows, inferencers, WASM processors, correlators, and direct emitters are set-only and reject INHERIT. Generated inferencer and WASM state is an immutable read source shared independently by every route; it is not an automatically initialized output and it is not exposed as input or message.

This surface is available on:

• CREATE <CONNECTOR> <ENTITY> INGESTOR
• CREATE INFERENCER
• CREATE JUNCTION
• CREATE DEDUPLICATOR
• CREATE REINGESTOR
• CREATE WASM PROCESSOR
• CREATE WINDOW PROCESSOR
• CREATE EMITTER

Every TO destination on a flush-based node requires FLUSH EACH <duration> MAX BATCH SIZE <bytes> or FLUSH IMMEDIATE; there are no hidden defaults. Each concrete output branch owns its buffer and deadline. FLUSH EACH measures its duration on the domain clock, beginning when data first enters an empty buffer. Window processors use WIDTH and STEP, and WASM processors use guest-owned output cadence instead of FLUSH.

This is the authoritative FLUSH IMMEDIATE timing rule. During normal processing, FLUSH IMMEDIATE starts a system-owned physical 100 µs minimum batching timeout when data first enters an empty route buffer. Domain pacing never scales this monotonic wait. The route flushes when that timeout expires, allowing nearby arrivals to remain in one Arrow batch instead of collapsing to one batch per message. FLUSH IMMEDIATE has no size boundary; shutdown and error handling may still force pending data out.

Treat each required FLUSH clause as workload-specific operational tuning. FLUSH IMMEDIATE minimizes time spent waiting beyond the system-owned batching window, while FLUSH EACH <duration> MAX BATCH SIZE <bytes> emits when either configured boundary is reached. Choose both values for the route’s traffic, downstream behavior, and branch cardinality. Values in examples are illustrative, not recommended defaults. Two measured facts decide what a FLUSH clause can buy.

MAX BATCH SIZE only clamps a batch; it never grows one. The batch a route emits is roughly its arrival rate multiplied by the FLUSH EACH interval, cut off at the byte cap, so raising a cap that never fires changes nothing and the only way to grow batches is a longer interval, paid in latency. Upstream of every route, ingestors build their first Arrow batches from source groups that close at 1,024 messages, or earlier after a 5 ms idle gap, independent of any FLUSH policy; a payload a JAQ-backed codec unfolds is never split, so its group may close above 1,024. Larger batches downstream come only from route buffering across an interval. Read actual batch sizes from the nervix_messages_per_batch histogram instead of inferring them.

Larger batches do not make program execution faster beyond about a thousand rows. Execution is columnar, so its fixed per-batch cost is amortized quickly. The table shows per-row throughput of the VM batch-size sweep (crates/nervix-vm/benches/vm.rs, criterion, one development machine, September 2026) relative to the 1,024-row value for each program shape: at 64 rows it is 12–60% of that value and climbs steeply; above 1,024 rows most shapes are flat within measurement noise, float arithmetic dips, and only the cheapest shape, nullable casts, keeps gaining, because batches above 1,024 rows execute on the node’s data workers and their per-batch admission and hand-off is no longer amortized by more work. Absolute rates are machine-specific; the shape is not.

Larger batches genuinely pay only at boundaries that do work per batch rather than per record:

• OTEL emitters send one export request per batch, so batch size sets request count and the compression ratio.
• Iceberg emitters write one staging file per flush and one commit per COMMIT EACH ... MAX SIZE boundary, so batch and commit sizes set file counts and Parquet file sizes.
• Inferencers whose tensor shapes declare a batch dimension run one model invocation per batch.
• WASM processors serialize one Arrow IPC payload per batch, and cluster interconnect sends one frame per batch, with a fixed 8 MiB frame limit.

Broker emitters — Kafka, Pulsar, NATS, RabbitMQ, MQTT, Redis, ZeroMQ, Sentry, and syslog — encode and publish one record at a time whatever the batch size; wire batching there belongs to the client, such as Kafka’s linger.ms and batch.size. SQS BATCH groups at most ten records per request, and database sinks split every flush into statements of at most the batching clause’s MAX MESSAGES records. On such routes a larger MAX BATCH SIZE or a longer interval buys only fewer flush cycles, at the cost of latency, memory, and coarser failure and retry granularity: prefer the shortest interval the sink tolerates and let the byte cap protect memory.

MAX BATCH SIZE measures the logical Arrow data in the current batch slice: value buffers plus the offsets and validity data needed to represent those values. It does not count unused buffer capacity or Rust and Arrow object overhead.

SET assignments execute left to right and repeated targets are valid. A later assignment may read an earlier value through the bare field or output.<field>. INHERIT ALL, INHERIT ALL EXCEPT ..., and explicit INHERIT field, ... copy compatible same-named input fields. UNSET is not part of NSPL.

Supported expression surface:

• literals: I64 integers, F64 floats, BOOL, and STRING
• identifiers: field references from the current row
• arithmetic: +, -, *, /, %
• comparisons: =, !=, >, <, >=, <=
• null-safe equality: IS DISTINCT FROM, IS NOT DISTINCT FROM
• membership and ranges: value [NOT] IN (constant, ...) and value [NOT] BETWEEN low AND high
• boolean logic: AND, OR, NOT
• conditionals: IF condition THEN value ELSE value END, searched CASE WHEN condition THEN value ... [ELSE value] END, and simple CASE operand WHEN match THEN value ... [ELSE value] END
• parentheses for nesting and precedence control
• explicit conversions only: expr AS TYPE, which fails a message whose value does not convert, and TRY_CAST(expr AS TYPE), which yields a typed null for it instead
• JSON extraction from STRING values holding JSON: JSON_VALUE(doc, '$.path' AS TYPE), which fails a message whose document or value does not read as TYPE, TRY_JSON_VALUE(doc, '$.path' AS TYPE), which yields a typed null for it instead, and JSON_EXISTS(doc, '$.path'); TYPE may be a scalar, VEC<...>, or ARRAY<..., n> type

Expression Functions owns the semantics of every form above, including conditional typing, the reserved words, and the rules for where each function may run.

Expression types match the full Nervix internal schema type set:

• integers: U8, I8, U16, I16, U32, I32, U64, I64
• floating point: F32, F64
• other scalars: BOOL, STRING, BYTES, DATETIME
• lists: ARRAY<...> and VEC<...>

AS and TRY_CAST(expr AS TYPE) convert between scalar types and accept long and short spellings, such as AS UINT8 or AS U8; see Conversions for every spelling and the values each conversion rejects.

Supported built-ins include string, null-handling, numeric, regex, and contextual functions such as:

• string transforms: lower, upper, trim, length, concat
• null handling: coalesce, is_null, nullif
• numeric and predicates: abs, contains, starts_with, ends_with
• extrema: greatest, least, clamp
• datetime: date_part, date_trunc, date_bin, date_add, date_diff, to_unix, from_unix, format_datetime, parse_datetime, with calendar units and explicit time zones
• IP addresses and networks: ip_from_string, ip_to_string, ip_family, ip_trunc, ip_in_network, ip_unmap, is_ip_address, over 4- or 16-octet BYTES addresses
• URLs: url_scheme, url_host, url_port, url_path, url_query, url_fragment, url_query_value, url_query_values, url_decode, is_url
• contextual functions: now, uuid_v4, uuid_v7

See Expression Functions for the full current function list, signatures, and aliases.

User-defined calls always use udf::<name>(...). The explicit namespace means adding a builtin can never shadow a UDF or change existing user code. See Choosing An Extension Tier.

General expression rules:

• builtin calls may be nested or chained, for example lower(trim(raw))
• arithmetic and predicate expressions may also be nested with parentheses
• there is no implicit cast insertion; type mismatches must be resolved with an explicit AS ... or TRY_CAST(... AS ...)
• relay names are graph references, never expression qualifiers
• language scopes are message, input, output, branch, left, right, relay_state.<relay>, metadata, partial_output, and error; availability depends on context
• transforming construction reads the working message; output.field reads only an already initialized output field
• generated routes allow bare reads from immutable generated state until the same-named output is initialized; message and input are unavailable
• branch.field must be explicit and is unavailable in successful emitter expressions
• supported ingestors read headers with read_header(name) and read_headers(name); Kafka exposes typed metadata.topic, metadata.partition, and metadata.offset, while Syslog exposes optional metadata.peer_addr
• supported codec emitters stage ordered write_header(name, value) calls in INVOKE

Example:

CREATE BRANCH by_tenant
  SCHEMA tenant_branch TTL 5m;

CREATE HTTP ENDPOINT INGESTOR notifications_in
  FROM ingress MODE NO ACK
  ON QUIESCE BUFFER MAX SIZE 1MiB DECODE USING notification_codec
  FILTER WHERE input.active
  TO notifications
    INHERIT ALL EXCEPT raw
    SET amount = message.amount + 1,
        normalized = lower(input.raw)
    BRANCHED BY by_tenant SET tenant = message.tenant
    FLUSH EACH 100ms MAX BATCH SIZE 1MiB
    ON MESSAGE ERROR LOG
  ON GENERAL ERROR LOG;

Another example showing nested conditions and chained calls:

CREATE EMITTER outbound
  FROM notifications
  TO KAFKA kafka_main TOPIC notifications_out
    MODE ACK PARALLEL MAX 1000 ACK TIMEOUT 30s
      RETRY POLICY BACKOFF 250ms MAX 30s
    ENCODE USING notification_codec
  INHERIT ALL EXCEPT raw
  SET normalized = lower(trim(input.raw)), magnitude = abs(input.amount)
  WHERE (output.active AND output.amount > 5) OR contains(lower(trim(input.raw)), 'urgent')
  INVOKE write_header('tenant', input.tenant)
  FLUSH EACH 100ms MAX BATCH SIZE 1MiB
  ON MESSAGE ERROR LOG
  ON GENERAL ERROR LOG;

The leader parses and validates these structured expressions immediately when the statement is applied. Models never store raw executable NSPL, and runtime execution never reparses expressions.

Generators use a narrower surface:

CREATE GENERATOR synth_notifications
  USING MATERIALIZED STATE notifications
  EACH 100ms
  BRANCHED BY by_tenant
  TO generated_notifications
    SET user_id = relay_state.notifications.user_id,
        amount = relay_state.notifications.amount
    FLUSH EACH 1s MAX BATCH SIZE 1MiB
    ON MESSAGE ERROR LOG;

Generator-specific rules:

• only SET is allowed
• exactly one materialized relay is declared and is accessed as relay_state.<relay>.<field>
• every route sees the same immutable state snapshot for one tick
• FLUSH EACH <duration> MAX BATCH SIZE <bytes> or FLUSH IMMEDIATE is mandatory and controls buffered emission
• paced domains evaluate both generator cadence and flush cadence against the bound logical clock; unpaced domains receive actual UTC through the same domain capability, with no missing-clock fallback

Runtime Node Error Policies

The Errors And Diagnostics chapter explains how failures are classified before these policies receive them.

Every TO route on an ingestor or relay-consuming processor must declare its message error policy after that route’s construction clauses:

ON MESSAGE ERROR IGNORE | LOG | SEND TO error_stream
SET error_reference = error.reference,
    error_code = error.code,
    source_id = input.id,
    attempted_total = partial_output.total

An ingestor additionally declares its node-level general policy after the source configuration:

ON GENERAL ERROR IGNORE | LOG

Emitters attach ON MESSAGE ERROR to their single external route and retain ON GENERAL ERROR at node level. WASM processors keep ON GLOBAL ERROR at node level for guest failures that are not tied to a message.

MESSAGE errors carry a stable UUIDv7 reference, code, operation, optional operation index, sorted affected field paths, timestamp, and a non-sensitive message. Error construction can read the eligible original input, the exact materialized-state snapshot, an all-optional partial_output, and the structured error scope. The error route preserves the branch in which the failure occurred. On flush-based nodes, SEND TO records are buffered independently for the owning TO route and concrete branch, then emitted when that route’s FLUSH interval or maximum batch size fires. They are not dispatched immediately. Error-record construction failures are logged and no-acked without recursively invoking the same policy. General and global errors remain node-wide and do not inherit a route-local FLUSH policy.

Client definitions are key-value based and may optionally mount a resource for file-backed settings such as TLS material:

CREATE [IF NOT EXISTS] CLIENT <name>
  TYPE <client_type>
  [MOUNT <resource> VERSION <n>|LATEST]
  CONFIG {
    '<key>' = '<value>'
  };

WebSocket clients and endpoints may also reference a signaling protocol:

CREATE [IF NOT EXISTS] SIGNALING PROTOCOL <name>
  FORMAT JSON | YAML | TOML | XML | CBOR | RAW
       | PROTOBUF USING RESOURCE <resource> VERSION <n> | LATEST
         CONFIG { '<key>' = '<value>' }
         SEND MESSAGE '<message_type>' WAIT MESSAGE '<message_type>'
  ON CONNECT
  ( SEND JAQ '<program>'[, '<program>'...]
  | WAIT JAQ '<matcher>'[, '<matcher>'...]
  | WAIT JAQ '<matcher>' [CAPTURE '<program>'] [ACCEPT DATA] )+
  [FAIL JAQ '<matcher>'[, '<matcher>'...]]
  TIMEOUT <duration>;

CREATE [IF NOT EXISTS] CLIENT <name>
  TYPE WEBSOCKETS WITH SIGNALING PROTOCOL <name>
  CONFIG {
    'endpoint' = 'wss://example.com/ws'
  };

Each SEND JAQ program must produce exactly one value, which is serialized in the declared format. Each WAIT JAQ matcher is satisfied by any output that is neither null nor false, so it can assert the fields that matter and ignore the connection ids and timestamps real services add. FAIL JAQ matchers abort the handshake immediately with the matched value as the reason.

Steps run strictly in written order: a step completes before the next starts, so a request can depend on an earlier reply. A WAIT step completes when every matcher it lists is satisfied, in any arrival order. CAPTURE records values from the matched frame, which every later program reads through $state.

ACCEPT DATA says where payload starts flowing to the relay — on ON CONNECT for the first frame, or on the WAIT step whose completion proves the peer is streaming. Frames arriving before that are dropped rather than buffered. A FAIL JAQ guard on a step aborts during that step; the optional one before ON CONNECT applies throughout.

Current built-in client transport kinds include:

• KAFKA
• PULSAR
• HTTP
• SENTRY
• OTEL
• PROMETHEUS
• RABBITMQ
• REDIS
• MQTT
• NATS
• ZEROMQ
• SYSLOG
• SQS
• WEBSOCKETS
• S3
• GCS
• AZURE_BLOB
• CLICKHOUSE
• POSTGRES
• MYSQL
• MONGODB
• ICEBERG_REST

Resource management commands:

CREATE [IF NOT EXISTS] RESOURCE <name>;
UPLOAD RESOURCE <name> VERSION '<local_directory>';
DESCRIBE RESOURCE <name>;
DESCRIBE RESOURCE <name> VERSION <n>;
REBIND RESOURCE <name> TO VERSION <n> | LATEST
  [FOR <kind> <name> [, <kind> <name> ...]];

TLS-capable VHOSTs:

CREATE [IF NOT EXISTS] VHOST <name> <hostname>, ...
  [WITH TLS <resource> VERSION <n> | LATEST];

Every resource binding names its version: WITH TLS on a VHOST, USING RESOURCE on a protobuf codec, protobuf signaling protocol, inferencer, or WASM processor, FROM RESOURCE on a hash map, and MOUNT on a client. VERSION <n> binds that completed version. VERSION LATEST binds the highest completed version when the statement is applied, and the stored model keeps that number, so a later upload never moves the binding. See Versioning.

REBIND RESOURCE atomically moves all current usages, or an exact kind-qualified FOR selection, to one completed version. The resource itself is unchanged. Every selected replacement validates before any model is written; a no-op selection succeeds without a write. Resource descriptions list all bound usages, while a version-qualified description lists only usages pinned there.

Backup and restore commands, which read and write archive files on the client’s machine:

BACKUP CLUSTER TO '<file>' [WITHOUT RESOURCES] [WITHOUT STATE | WITHOUT PAUSE | TIMEOUT <duration>];
BACKUP DOMAIN [<name>] TO '<file>' [WITHOUT RESOURCES] [WITHOUT STATE | WITHOUT PAUSE | TIMEOUT <duration>];
DESCRIBE BACKUP '<file>' [FORMAT TEXT | JSON];
RESTORE CLUSTER FROM '<file>' [RESUME] [ON EXISTING USER FAIL | SKIP | REPLACE] [DRY RUN] [WITHOUT STATE | WITHOUT SOURCE OFFSETS];
RESTORE DOMAIN <name> [AS <new_name>] FROM '<file>' [RESUME] [DRY RUN] [WITHOUT STATE | WITHOUT SOURCE OFFSETS];

BACKUP is admitted and run by the leader like other persistent commands, and the client downloads the archive it assembles. DESCRIBE BACKUP runs in nervix-cli without a server. RESTORE streams the archive to the leader, which verifies and plans the whole restore before it changes anything, and then recreates the users, the domains stopped, their resource versions under their archived numbers, their models, and their compatible runtime checkpoints, including materialized relay rows. RESUME makes a complete restored domain running at its archived start generation and clock mapping. A normal START advances that generation and clears materialized state. A normal backup quiesces each running domain for the state cut. See Backup And Restore.

Session-only commands:

CREATE SUBSCRIPTION <name> TO <relay> [BLOCKING|DROPPING] [BATCH SAMPLE RATE <rate>] [WHERE ...];
DELETE SUBSCRIPTION <name>;
DESCRIBE RELAY <relay> WHERE (...);
DESCRIBE INGESTOR <ingestor>;
DESCRIBE JUNCTION <junction>;
DESCRIBE DEDUPLICATOR <deduplicator>;
DESCRIBE REORDERER <reorderer>;
DESCRIBE WINDOW PROCESSOR <window_processor>;
DESCRIBE HASH MAP <hash_map>;
DESCRIBE PLACEMENT <placement>;
DESCRIBE RELOCATION <selection> ONTO NODE <node_id>
  FOLLOW PREFERENCES | IGNORE PREFERENCES
  [FOR <kind> <name> FOLLOW PREFERENCES | IGNORE PREFERENCES ...];
DESCRIBE DOMAIN;
LOOKUP <hash_map> KEY '<key>';
ATTACH DOMAIN CLOCK;
DETACH DOMAIN CLOCK;

Show commands:

SHOW CREATE <kind> <name>;
SHOW CREATE BRANCH by_tenant;
SHOW PLACEMENTS;
SHOW RELAY <name> MATERIALIZED STATE;
SHOW CLUSTER STATUS;
DROP NODE <node_id>;
CORDON NODE <node_id>;
UNCORDON NODE <node_id>;
DRAIN NODE <node_id>;
RELOCATE <selection> ONTO NODE <node_id>
  FOLLOW PREFERENCES | IGNORE PREFERENCES
  [FOR <kind> <name> FOLLOW PREFERENCES | IGNORE PREFERENCES ...];

A relocation <selection> is a kind-qualified list, <kind> <name>[, ...], or a directed corridor, FROM <kind> <name>[, ...] TO <kind> <name>[, ...].

For a wire schema, <kind> is the exact multi-word kind: WIRE JSON SCHEMA, WIRE CBOR SCHEMA, or WIRE AVRO SCHEMA. The same exact kind is required by DROP.

General notes:

• keywords are case-insensitive
• autocomplete is derived from the parser surface
• transport/client configs are generally preserved as pass-through string key/value pairs
• native schema fields may use the SENSITIVE modifier; session subscription output masks those values as <masked>, while emitters may send sensitive values to their configured external sink
• CREATE SUBSCRIPTION and DELETE SUBSCRIPTION are not persisted in the registry
• ATTACH DOMAIN CLOCK and DETACH DOMAIN CLOCK follow and stop following the active domain’s clock for the session alone and are not persisted either; see Domain Clock Attachment
• session subscription names are unique within a connected session; one session may subscribe to relays from multiple domains, and DELETE SUBSCRIPTION uses the name rather than repeating subscription parameters
• every RELAY is scheduled with one owner; only that owner instantiates its buffer, concrete branch presence, fan-out, subscriptions, and metrics
• relay CAPACITY bounds the single owner buffer cluster-wide; each producer node and remote consumer node adds one fixed in-flight dispatch slot, independent of branch count
• materialized state adds scheduler-selected state replicas to the relay rather than a separate runtime-node kind; ordinary relays report no replicas
• ingestors and reingestors construct branch identities, and a relay owner applies branch TTL and MAX INSTANCES across all producers for that relay
• DESCRIBE INGESTOR exposes runtime-facing ingestor state, including memory-backpressure state and committed Kafka OFFSET BY DOMAIN partition assignment

The Working Message

A transforming route operates on one working message. It begins as the route’s input view. The route constructs a new output shape: INHERIT carries fields into that shape, ordered SET assignments rewrite it step by step, and finalization fixes it as the route output. message.<field> always reads the working message as it currently stands.

Three scopes pin reads to points on that timeline:

• input.<field> pins the original record. It never changes.
• message.<field> reads the live current value.
• output.<field> reads only a value that this route has already explicitly initialized.

The precise resolution rule is:

During transforming construction, message.field and a bare RHS field read the working output and fall back to the exact-compatible input.field only while the output field is uninitialized. After finalization, route WHERE sees the finalized output and performs no fallback.

Set-only output-construction routes have no message or input.

One Record, Step By Step

Assume the input record contains x = 2 and untouched = 9. Both fields are required I64. This route constructs an output with x, copied_untouched, and other required fields:

INHERIT x
SET x = message.x + 3,
    copied_untouched = message.untouched,
    x = message.x * 2

The working message changes in written order:

This is not an implicit identity transformation. Enrichment is a basic operation of Nervix, and the working message is the native consequence of native inheritance: a route can carry input values forward while progressively replacing selected values. Use input and output when every read should be pinned to the original record or to explicit output initialization.

Scope Boundaries And Edge Cases

Exact compatibility means the same Nervix type and the same nullability. If the input and output both declare a field name but their types or nullability differ, an uninitialized output field does not make the incompatible input field available through message or a bare read. Use an explicit, valid conversion from input.<field> where the language supports one.

Set-only output-construction routes begin with an empty output, reject INHERIT, and expose neither message nor input. They must initialize every required output field. Omitted optional fields finalize as typed nulls. Direct-emitter VALUES is a separate source-row mapping surface: input, message, and bare fields read the source row, while output is unavailable.

Correlators have no default input scope. They expose left and right, reject bare RHS field reads, and do not expose input or message.

Generated inferencer and WASM routes are set-only. Bare reads resolve against immutable generated state until a same-named output field has been initialized. Generated state is independently visible to every route and never initializes route output automatically.

Error routes expose the original eligible input, or left and right for correlators; the exact captured relay_state snapshot; structured error; and the all-optional partial_output view. Their ordered assignments may read values initialized by earlier error-record assignments. They do not turn a partial output into a transforming working message.

See Runtime Nodes for route families and VM Functions for the implementation boundary.

Expression Functions

This chapter is the reference for NSPL expressions: the operators, conversions, builtin functions, and window aggregates they can use, with each one’s exact types, null handling, errors, and limits. Expressions appear on ingestors, processors, routes, and emitters, most often in route construction:

[INHERIT ...]
[SET <field> = <expr>, ...]
[WHERE <expr>]
[INVOKE write_header(<name-expr>, <value-expr>), ...]

SET assignments and INVOKE calls execute left to right. A transforming route begins empty and may initialize fields with INHERIT and SET; a set-only route begins empty and supports only SET. Route WHERE runs after output finalization. INVOKE and write_header are emitter-only; side-effect functions are invalid inside ordinary expressions. See The Working Message for the field scopes a route reads and how they resolve, and Where Expressions Run for every other place an expression appears.

General rules:

• function names are case-insensitive, and an alias such as ceiling or substring behaves as, and is reported under the name of, the function it stands for
• there is no implicit cast insertion; expr AS TYPE and TRY_CAST(expr AS TYPE) convert explicitly, as Conversions describes, and JSON_VALUE reads a value of a declared type from JSON text, as JSON Documents describes
• argument and result types are validated when the statement is applied, except for the few expressions Where Expressions Run lists as checked later
• sensitive values retain their sensitivity through expression evaluation; an output field that is not sensitive can hold one only through an explicit leak_sensitive(...), as Function Properties describes
• now() returns the execution-local domain time as DATETIME, and uuid_v7() uses that same time when building the UUID

Domain-owned Roto UDFs use the same call syntax and exact typing rules. Builtins take the unqualified call surface. UDFs use the explicit udf:: namespace.

The Catalog at the end of this chapter lists every operator, builtin, and aggregate with its signature, result, and the section that describes it.

Choosing An Extension Tier

Use the smallest extension tier that fits the operation:

Tenant-supplied or potentially non-terminating logic belongs on the WASM processor path. Roto UDF creation is operator-trusted administration. See User-Defined Functions for the native execution contract and Module Sharing And Branch Memory for the WASM isolation and memory boundary.

Where Expressions Run

Every operator and builtin on this page is available wherever an expression is, except for the functions that depend on their context. This table lists those, by the context an expression sits in:

• write_header is a statement of an emitter route’s INVOKE clause, never part of an expression; see Header Functions.
• A udf:: call is available in every context. A materialized-state DEFAULT accepts only a UDF that is not VOLATILE, and reads no field at all: it is built from constants.
• Outside a window route, count, sum, first, last, min, and max are the array and vector functions, and every other aggregate name is an unknown function, such as unknown function 'avg' with arity 1.
• Set-only routes, which are the routes of windows, generators, correlators, inferencers, and WASM processors, accept no INHERIT and no INVOKE.

Reorderer BY expressions and emitter VALUES and ATTRIBUTES mappings are compiled when their domain’s execution is built rather than when the statement is applied, and a subscription’s WHERE when the subscription is created, so a type error in one of them is reported then.

Evaluation Model

Builtins are evaluated over Arrow columns: one call computes its result for every message in a batch together. A message’s result never depends on the other messages in the batch, so batching does not change any value. The one limit a batch’s messages share is the bytes one STRING or BYTES column holds; see Result Size. How a function traverses its column, whether through an Arrow compute kernel, one pass over the column’s value buffer, or a loop over its rows, is internal to the function and does not change its results.

Several builtins run on libraries that choose SIMD instructions at run time from the ones the node’s CPU offers: JSON extraction finds a document’s structure that way, base64 and hexadecimal encoding and decoding process their octets that way, sha256 uses the SHA instructions of x86-64 CPUs that have them, and substring searches such as contains_any and regular expressions scan text that way. xxh3_64 uses the SIMD instructions of the CPU target the binary is built for. Integer + and -, and * over every integer type but I64 and U64, run on Nervix’s own kernels, which also choose vector instructions at run time from the ones the node’s CPU offers. The other checked numeric kernels and passes over value buffers are written as loops the compiler can turn into vector instructions for the CPU target the binary is built for, and Nervix makes no claim about which of them it does. None of these choices changes a result. The one exception is the transcendental functions, whose last places come from the platform’s C math library; see Numeric Functions.

The compiler applies three optimizations that preserve results in the same way:

• A deterministic call that cannot fail and whose arguments are all literals may be computed once instead of for every batch. It produces exactly the value that evaluating it for each message would, so upper('grüßen') and upper(input.text) agree when input.text holds grüßen.
• Identical deterministic expressions that cannot fail may be computed once and shared within one assignment or clause. Calls that return a new value for every message, such as uuid_v4(), and calls that can report a per-message error are evaluated at each occurrence, so each occurrence reports its own error.
• A literal, and any expression whose arguments are all literals or now(), is carried through a batch as one value rather than as a column of copies. A function reads it as one value where it can and expands it to a column only where a message-by-message operation or an output field needs one, so the result is the same either way. When such an expression fails, such as 1 / 0, every message that evaluates it reports the error.

Every operand of an operator or a function is evaluated for every message the expression evaluates, so AND, OR, coalesce, and the other operators never skip an operand. Only a conditional expression evaluates an operand for some messages and not others.

VM Functions describes the implementation behind this model: how an expression is compiled and executed over a batch, and which kernels each function family uses.

Function Properties

Every builtin follows these rules unless its own description says otherwise:

Sensitivity is checked where a value is stored, never where it is only tested. Assigning a sensitive value to an output field that is not sensitive is rejected with SET field '<field>' would store sensitive data in a non-sensitive output field; use leak_sensitive(...) to explicitly remove sensitivity, while a WHERE clause, a deduplication or ordering key, or a subscription filter may read sensitive fields freely. INHERIT <field> LEAK SENSITIVE, written in an explicit field list, copies a field as leak_sensitive(input.<field>) does. Emitters apply their own rules to the values they send; see Emitters.

Errors

A function that cannot compute its result for a message reports an error of one of four kinds:

The sections below name the kind and message of every failure. A failed message yields null for the failed operation, and the message then takes its context’s error handling:

• A failure in route construction (INHERIT, SET, route WHERE, and INVOKE), in an ingestor’s FILTER WHERE or BRANCHED BY ... SET, in a generator route, and in an emitter’s FROM ... WHERE, route, or VALUES hands the message to the route’s ON MESSAGE ERROR policy; an ingestor FILTER WHERE failure goes to the policy of every route. SET runs before route WHERE, so a SET failure is reported even for a message that WHERE would drop. A failed branch SET reports the set operation and the message branch SET failed with, the kind, the reason and the operation’s range, and the error route reads the route’s finalized output as partial_output.
• A failure in a processor’s FROM ... WHERE or FILTER WHERE, or in the argument of a window aggregate, is logged, and the message is not acknowledged.
• A failure in a session subscription’s WHERE skips the record, and the session is told how many records the filter skipped.
• Deduplication keys, reorderer BY expressions, CORRELATE WHERE conditions, inferencer INPUTS mappings, and a reingestor’s BRANCHED BY ... SET have no message-error route. A reingestor whose branch construction fails for one message fails every message of that batch: the failure is logged, and none of them is acknowledged. Keep expressions that can fail out of them, or guard them with a conditional, TRY_CAST, or TRY_JSON_VALUE.

In an ON MESSAGE ERROR SEND TO ... SET, a function failure has the error scope below. Every failure an expression reports has the code evaluation; the kind appears in the message, which names the node, the program, the kind, and the reason, such as junction 'enrich' FILTER-MAP side error division_by_zero: integer division by zero at 12..18. The range at the end locates the failed operation within the route’s program. When several operations fail for one message, the record reports the first.

Some failures belong to a batch rather than to a message: a UDF trap, an invalid UDF result, or a UDF that exceeds its watchdog, a failed key expression of LOOKUP_HASH_MAP, and a limit of a column that a whole batch exceeds, such as the one format_datetime checks. Such a failure fails every message of the batch: a processor reports an internal error and leaves the batch unacknowledged, and an emitter applies its ON GENERAL ERROR policy.

A statement whose expression does not type-check is rejected when it is applied, with a message such as function 'trim' requires Utf8 input, found Int64. These messages name types by their Arrow names:

Literals

A literal reads the same wherever its expression is written: in a statement, in a web console form, and in nervix-cli subscribe --where.

There is no DATETIME, BYTES, NaN, or infinity literal. Convert a string instead: '2024-02-29T12:00:00Z' AS DATETIME, hex_decode('00ff'), 'NaN' AS F64, or 'inf' AS F64. A NULL anywhere else is rejected with NULL requires a declared optional assignment target; a typed null comes from a conditional without ELSE or from TRY_CAST.

Integer literals are I64 and float literals F64, and operands are never converted, so a literal combined with a value of another width is written with a cast: input.priority > 5 AS I32, bitwise_and(input.flags, 255 AS U16), or input.ratio * 0.5 AS F32. Arguments that take a count of any integer type, such as the digits of round and the counts of the string and shift functions, accept an I64 literal as it is.

Operator Precedence

Operators bind in this order, tightest first:

Three consequences are easy to miss:

• NOT binds tighter than comparisons, so NOT input.count > 5 negates input.count and is rejected with operator Not is not valid for Int64. Write NOT (input.count > 5) or input.count <= 5.
• AS binds tighter than unary minus, so -128 AS I8 casts 128, which fails. Write (-128) AS I8.
• An AS applies only to the operand it follows, so input.low + input.high AS STRING converts input.high alone, and input.low + 1 AS I32 adds 1 AS I32.

Comparisons group from the left like the arithmetic operators, so a = b = c compares a = b with c, and a < b < c is rejected because a < b is a BOOL. A trailing comma is accepted in the arguments of a call, the elements of an IN set, and the elements of [...].

Reserved Words

These words are reserved in expressions: WHERE, SET, INHERIT, ALL, EXCEPT, LEAK, SENSITIVE, INVOKE, AS, TRY_CAST, JSON_VALUE, TRY_JSON_VALUE, JSON_EXISTS, AND, OR, NOT, TRUE, FALSE, NULL, IF, CASE, WHEN, THEN, ELSE, END, IN, BETWEEN, IS, DISTINCT, FROM, and UDF. Wherever a keyword could stand, a reserved word reads as that keyword, so a bare field, a call, or a SET, DEFAULT or INHERIT field named with one is written between backticks: SET `end` = input.end. After a field scope such as input. and after udf::, no keyword can stand, so the name is written as it is: input.end, left.from and udf::case(input.value) read without backticks.

Every other word, including a statement keyword such as to, on, by, or max, is an ordinary name wherever an expression writes one: SET to = input.to writes a field named to.

Inside an expression, a name between backticks may hold any character a name may, such as -, ~, ., or a leading digit, which a bare word cannot: input.`user-id`. Canonical NSPL, as SHOW CREATE and nervix-nspl-format write it, puts a name between backticks exactly where the name would not read back otherwise. It also quotes a bare field named like an ALTER operation keyword, ADD, DROP, ALTER, REPLACE, or RENAME, because inside an ALTER statement a comma before such a word begins the next operation.

Expressions Inside Statements

A statement reads an expression it embeds for as long as the expression can go on, and the statement’s next clause begins where it cannot, so an expression needs no parentheses to end. After WHERE input.total > 10, a TO, MAX TIME, or correlator RIGHT FROM continues no expression, so it begins the next clause. A word written where an operand, a call, or a field belongs is part of the expression, whatever keyword it spells: in DEDUPLICATE ON max(input.readings), max MAX TIME 10m the first max is a call, the second a field, and the third begins MAX TIME, and a correlator’s left input can test right(left.name, 2) = right before its RIGHT FROM.

When the expression goes on with a token and then cannot finish, as an IN ( that is never closed cannot, the statement is rejected where the expression fails rather than read as a shorter expression. Inside an ALTER statement, a comma followed by a bare operation keyword begins the next operation, while a comma inside a call’s parentheses never does, so SET FILTER WHERE concat(input.kind, replace) holds one expression.

A statement reads the expression it embeds from its own words, with the same lexer and grammar that read an expression in a web console form, in nervix-cli subscribe --where, and through the client library. Keywords, literals, comments, and spacing therefore mean the same wherever an expression is written: text one of them accepts reads as the same expression in all of them, and text one of them rejects all of them reject. A rejected expression is reported at the word of the statement where it went wrong. When the expression itself cannot finish, the message is the one a web console form shows for the same text; when a complete expression is followed by a word no clause of the statement expects, the statement names the clauses it expected there.

Logical Operators

AND, OR, and NOT take BOOL operands and return BOOL. They follow three-valued logic, in which null means an unknown truth value:

NOT of null is null. A WHERE selects only the messages whose condition is TRUE, so a null condition drops the message. The result is optional when either operand is, even where the other operand decides it.

Both operands are evaluated for every message, whatever the first one holds. A failure in the second operand therefore fails the message even where the first operand already decides the result: input.divisor != 0 AND input.total / input.divisor > 10 reports division_by_zero for a message whose divisor is 0. Guard such an operand with a conditional, which evaluates it only for the messages that select it:

WHERE CASE WHEN input.divisor = 0 THEN FALSE ELSE input.total / input.divisor > 10 END

An operand of another type is rejected: operator And is not valid for Int64, or binary operator And requires matching operand types, found Int64 and Boolean for operands of two types.

Conditional Expressions

NSPL provides three self-delimited conditional forms:

IF <bool-condition> THEN <result> ELSE <result> END

CASE
  WHEN <bool-condition> THEN <result>
  [WHEN <bool-condition> THEN <result> ...]
  [ELSE <result>]
END

CASE <operand>
  WHEN <match-value> THEN <result>
  [WHEN <match-value> THEN <result> ...]
  [ELSE <result>]
END

Every form uses first-match-wins ordering. A null condition is not a match, and a null operand never equals a simple-CASE match value. Conditions are BOOL, and a simple-CASE operand and its match values have one exact type; the operand is computed once, before any arm. All non-null results must have the same exact type, which may be any scalar type but not ARRAY or VEC; implicit casts are not inserted. An omitted ELSE is a typed null and therefore requires an optional destination. An IF always includes ELSE. A statement that breaks these rules is rejected with a message such as CASE WHEN condition must evaluate to Boolean, found Int64, CASE results must have one exact type, found Int64 and Utf8, or CASE result type List(...) is not supported by conditional selection, which IF reports too.

Conditional values are computed in the columnar batch engine, and every arm is evaluated only for the messages that select it: a condition is evaluated for the messages no earlier arm answered, and a result for the messages its condition selected. A function in an arm therefore never reports an error for a message that selects another arm, so an error in an unselected arm never reaches the message’s error handling, and a CASE guard shields a function from the messages it cannot handle. Context-injected operations such as window aggregates, header reads, and UDFs are invoked for the selected messages only, and not at all in a batch where no message selects their arm; a whole-batch failure of such an invocation still fails the batch it was invoked for.

The words IF, CASE, WHEN, THEN, ELSE, and END are reserved.

Comparison And Equality

=, !=, <, <=, >, and >= require both operands to have the same exact type. = and != compare any scalar type, BYTES included, which compares octet by octet. The ordering comparisons <, <=, >, and >= accept numeric, STRING, and DATETIME operands. A null operand makes the comparison null. No comparison is defined for ARRAY and VEC values: compare their elements with the array and vector functions instead.

• STRING values compare by Unicode code point, which is also the order of their UTF-8 bytes. Comparison is case-sensitive and never depends on a locale.
• Floating-point comparisons follow IEEE 754. NaN is unequal to every value, including another NaN, so = is false, != is true, and every ordering comparison with NaN is false. 0.0 and -0.0 are equal.
• nullif(a, b), a simple CASE <operand> WHEN <value>, IS [NOT] DISTINCT FROM, and IN decide equality exactly as = does.

a IS NOT DISTINCT FROM b is equality under which two nulls are equal: it is true when both operands are null or both are present and a = b, and false otherwise. a IS DISTINCT FROM b is its negation, a null-safe !=. Neither is ever null, so a required BOOL field can hold either, and input.region IS DISTINCT FROM input.home_region is true where exactly one region is null, where input.region != input.home_region is null. Both operands must have the same exact scalar type. Present floats compare as = does, so NaN is distinct from every value, another NaN included, and 0.0 is not distinct from -0.0.

IN, BETWEEN, and IS [NOT] DISTINCT FROM bind like the comparison operators and group from the left with them, so a = b IN (TRUE) tests whether a = b is in the set. Unary NOT binds more tightly than any comparison, so NOT x IN (1, 2) negates x before testing it; write x NOT IN (1, 2) or NOT (x IN (1, 2)) instead. See Operator Precedence. There is no IS NULL operator: test for null with is_null(x) and NOT is_null(x).

Membership And Ranges

<value> IN (<element>, ...) tests whether a value equals an element of a written set, and <value> NOT IN (<element>, ...) is its negation. <value> BETWEEN <low> AND <high> tests whether a value lies in an inclusive range, and <value> NOT BETWEEN <low> AND <high> is its negation.

input.status IN ('open', 'held')
input.priority NOT IN (1 AS I32, 2 AS I32)
input.weight BETWEEN 1.0 AND 50.0
input.observed_at NOT BETWEEN input.window_start AND input.window_end

Sets

A set lists its elements in parentheses, separated by commas. Every element is a constant: a literal, optionally negated with - or NOT and cast with AS or TRY_CAST, such as -1 AS I32 or '2026-01-01T00:00:00Z' AS DATETIME. Each element is evaluated once, when the statement is applied, exactly as the same expression evaluates for a message, so an element that cannot be evaluated, such as 300 AS U8, rejects the statement, and so does a TRY_CAST that cannot convert its literal, whose typed null is no valid element. So does an element that reads a field or calls a function; to test a value against other fields, compare it with = and combine the comparisons with OR.

The operand may have any numeric type, BOOL, STRING, or DATETIME, and every element must have exactly the operand’s type. Integer literals are I64 and float literals F64, so a set tested against an I32 or F32 value casts each element: input.priority IN (1 AS I32, 2 AS I32).

A value is an element of a set when it equals one of its elements under =:

• NULL is not a valid element, because no value equals it; test for null with is_null(...) or IS NOT DISTINCT FROM.
• An empty set is valid. No value is an element of it, a null one included, so x IN () is false and x NOT IN () true for every message.
• Otherwise a null operand makes both IN and NOT IN null, so a WHERE selects a message with a null operand for neither.
• Writing an element twice changes nothing.
• NaN equals no value, so a NaN element matches nothing and a NaN operand is an element of no set, while 0.0 and -0.0 are the same element.

A set is prepared once for its program rather than for every batch or message. A small set of numbers, BOOL, or DATETIME values is tested by comparing the value with each of its elements, while a larger set, and every set of STRING values, is looked up by key, so a set of thousands of elements still costs each message one lookup.

Ranges

x BETWEEN low AND high is x >= low AND x <= high with x computed once, so an operand that fails reports its error once. The operand and both bounds must have one exact type: any numeric type, STRING, or DATETIME, the types < orders. Both bounds are inclusive, and a range whose low bound is above its high bound holds no value; the bounds are never swapped.

Nulls follow AND: a null operand makes the result null, and a null bound makes it null unless the comparison with the other bound is false, which makes it false. NaN lies in no range, so BETWEEN is false for a NaN operand or bound and NOT BETWEEN is true. NOT BETWEEN negates BETWEEN; it is not x < low OR x > high, which is false for a NaN operand.

The AND that closes a low bound belongs to the range, so x BETWEEN 1 AND 5 AND y is (x BETWEEN 1 AND 5) AND y. A bound that is itself a comparison needs parentheses.

Arithmetic

+, -, *, /, and % require both operands to have the same exact numeric type, and the result has that type. Unary - applies to signed integer and floating-point operands; an unsigned operand is rejected with operator Neg is not valid for UInt8. A null operand makes the result null. Integer literals are I64, so input.count + 1 over a U32 field is rejected with binary operator Add requires matching operand types, found UInt32 and Int64; write input.count + 1 AS U32. + does not join text, which concat does, and DATETIME values have no arithmetic operators: move and measure them with date_add and date_diff, or convert them to I64 nanoseconds explicitly.

Arithmetic is checked. An operation whose result its type cannot hold reports a per-message error and yields null for that message, instead of wrapping, saturating, or producing NaN or an infinity. Only that message fails: every other message in the batch is computed as usual, and a message’s result never depends on the other messages in its batch.

• Integer +, -, and * report an overflow error when the exact result does not fit the operand type, so - over U8, U16, U32, or U64 operands fails when the right operand is larger.
• Integer / truncates toward zero. A zero divisor reports a division_by_zero error, and dividing the minimum value of a signed type by -1 reports an overflow error.
• Integer % returns the remainder with the sign of the dividend. A zero divisor reports a division_by_zero error. Every other remainder exists, so the remainder of the minimum value of a signed type by -1 is 0.
• Unary - on the minimum value of a signed integer type reports an overflow error.
• F32 and F64 arithmetic is IEEE 754 arithmetic at the operand’s own width, and % returns the remainder with the sign of the dividend. A result that is NaN or an infinity reports an invalid_argument error, which includes every division by zero and every operation on NaN. The rule applies to the result, so an infinite operand fails only where the result is not finite: 1.0 / x is 0.0 for an infinite x. Unary - on a float never fails: it changes the sign of every value, including zero, NaN, and the infinities.

The error’s message names the failure: integer addition overflowed, integer subtraction overflowed, integer multiplication overflowed, integer division overflowed, or integer negation overflowed for an overflow; integer division by zero or integer remainder by zero for a division_by_zero; and floating-point operation produced a non-finite result for an invalid_argument.

Conversions

A value never changes its type implicitly. Two explicit forms convert it to another scalar type. They accept the same types and convert every value the same way, and differ only in what a value that does not convert does:

<type> is a scalar type written with the same spellings in both forms, in any letter case: U8 or UINT8, I8 or INT8, U16 or UINT16, I16 or INT16, U32 or UINT32, I32 or INT32, U64 or UINT64, I64 or INT64, F32 or FLOAT32, F64 or FLOAT64, BOOL or BOOLEAN, STRING or UTF8, BYTES, and DATETIME. Any other name is rejected with unsupported type '<name>'. Conversions are defined between scalar values only: an ARRAY or VEC type cannot be written as a target, and no conversion is defined for an ARRAY or VEC operand. A BYTES value converts only to BYTES, which returns it unchanged, and no other type converts to BYTES; a statement that asks for either is rejected with BYTES conversions require bytes_from_utf8, bytes_to_utf8, base64 or hex functions, which name the functions that convert explicitly. A null operand is not a failure: it converts to a typed null in both forms, so input.amount AS I64 over a message without an amount yields null and reports nothing. Test the operand to tell a missing value from one that did not convert:

SET amount = TRY_CAST(input.amount AS I64),
    amount_state = CASE
      WHEN is_null(input.amount) THEN 'missing'
      WHEN is_null(TRY_CAST(input.amount AS I64)) THEN 'malformed'
      ELSE 'converted'
    END

The result of TRY_CAST is optional even for a conversion that cannot fail, so it initializes a required field only through an expression that is never null, such as coalesce(TRY_CAST(input.amount AS I64), 0), and a statement that assigns it to a required field directly is rejected when it is applied. It keeps the sensitivity of its operand, as every conversion does.

TRY_CAST suppresses only the failure of the conversion it performs. Every other failure of its operand still fails the message with its own error:

• TRY_CAST(100 / input.divisor AS STRING) reports division_by_zero for a zero divisor.
• TRY_CAST(input.raw AS I64 AS STRING) converts input.raw AS I64, which reports cast_failed for text that is not an integer.
• A UDF called in the operand reports its own per-message errors, and a failure of the whole batch still fails the batch.

A conversion of a TRY_CAST result is an ordinary one: TRY_CAST(input.raw AS I64) AS U8 fails a message whose number does not fit U8, and yields null without an error for one whose text is not an integer. Inside a conditional, a TRY_CAST converts only the messages that select its arm, as every operation does.

The operand of TRY_CAST is the whole expression before its final AS, so TRY_CAST(input.low + input.high AS STRING) converts the sum, while in input.low + input.high AS STRING the AS applies to input.high alone.

A conversion between scalar types other than BYTES succeeds for every value, except for the values the table below lists. Converting a value to its own type returns it unchanged.

• Every value other than BYTES converts to STRING. An integer is written in decimal, and a BOOL as true or false. A float is written in decimal without an exponent, with the fewest digits that read back as the same value: 1.0 is written 1, 1e21 as 1 and 21 zeros, NaN as NaN, the infinities as inf and -inf, and negative zero as -0. A DATETIME is written in RFC 3339 with a +00:00 offset and a fraction of three, six, or nine digits when its fraction is not zero, such as 2024-02-29T12:00:00+00:00 and 2024-02-29T12:00:00.500+00:00.
• A number converts to BOOL as false for zero and true for every other value, including NaN, and a BOOL converts to a number as 0 or 1.
• A number converts to F32 or F64 as the nearest value of that type, so an F64 beyond the F32 range becomes an infinity.
• A DATETIME converts to I64 as its count of nanoseconds since 1970-01-01T00:00:00Z, and to F32 or F64 as the nearest value to that count. An integer converts to the DATETIME that many nanoseconds after that instant, and a float to the DATETIME its count of nanoseconds names, cut toward zero, so 1.5 AS DATETIME is one nanosecond after the epoch.

JSON Documents

A STRING value holding a JSON document is read into typed values explicitly. Three forms read it, each naming a path to one value in the document:

<document> is any STRING expression; any other type rejects the statement when it is applied, with an error such as JSON_VALUE document must be STRING, found Int64. A null document yields null in all three forms and reports nothing. <path> is a string literal in single or double quotes, parsed and checked when the statement is parsed, so a malformed path rejects the statement; see Paths. JSON_VALUE, TRY_JSON_VALUE, and JSON_EXISTS are reserved.

SET customer_id = JSON_VALUE(input.payload, '$.customer.id' AS I64),
    tags = JSON_VALUE(input.payload, '$.tags' AS VEC<STRING>),
    first_quantity = TRY_JSON_VALUE(input.payload, '$.items[0].qty' AS U32),
    has_note = JSON_EXISTS(input.payload, '$.note')

A value read from a document keeps the document’s sensitivity, as every function result does.

Paths

A path starts with $, which names the whole document, followed by any number of steps, at most 64:

A path holds no whitespace, and has no wildcards, slices, filters, recursive descent, negative indexes, or single-quoted names. Member names are compared exactly, letter case included, with no Unicode normalization. Where an object repeats a member name, JSON_VALUE reads the last of them, and JSON_EXISTS finds any of them. A path finds no value when an object lacks the member, an array is shorter than the index, a member step meets an array, an index step meets an object, or a step leads into a value that is neither: $.a.b finds nothing where a is a number, a string, JSON null, or an array, and $[0] finds nothing in an object.

A malformed path rejects the statement with invalid JSON path '<path>': followed by the defect, whose byte positions count from zero:

• a path starts with '$'
• expected '.' or '[' at byte <n>
• expected a member name of letters, digits and underscores not starting with a digit at byte <n>; write any other name as ["name"]
• expected an array index or a double-quoted member name at byte <n>
• array index at byte <n> is not an integer from 0 to 4294967295 without leading zeros
• member name at byte <n> is not a valid JSON string
• expected ']' at byte <n>
• a path takes at most 64 steps

A message error writes its path in one form, with .name where a name allows it and ["name"] otherwise, so $["plain"] appears as $.plain.

Declared Types

<type> is a scalar type written with the same spellings as in Conversions, or a VEC<...> or ARRAY<..., n> of declared types written as a schema field declares them, nested to any depth, such as VEC<VEC<I32>> or ARRAY<F32, 2, 3>, where ARRAY<F32, 2, 3> is two arrays of three and every fixed length is from 1 to 2,147,483,647. JSON has no date or byte type, so DATETIME and BYTES, including as elements, reject the statement with an error such as JSON_VALUE cannot read DATETIME, which no JSON value is; read the text as STRING and convert it explicitly; read the text as a STRING and convert it with parse_datetime or base64_decode. A value is never converted between kinds: a number is not read as text, and text is not read as a number.

VEC and ARRAY elements are never null, so an array holding JSON null fails as any other element of the wrong kind does. A number written as digits with an optional -, and no fraction or exponent, is read exactly across the whole 64-bit range. Every other number is read as the nearest F64 first, and an integer type accepts it when that F64 is an integer in its range: 9007199254740993.0 reads as 9007199254740992, and 1.0000000000000001 reads as 1. An integer written as digits beyond the 64-bit range reads as the nearest F64 too, so it is out of range for every integer type, except that the negative integers down to -9223372036854776832 read as the F64 -2^63, which is the smallest I64. A number whose magnitude is beyond the F64 range, such as 1e400, makes the document unreadable. -0 reads as 0 for every type, and -0.0 reads as 0 for an integer type and as -0.0 for F64.

Missing Values, JSON Null, And Failures

What each form yields depends on what the path finds:

A number with a fraction where an integer is declared is a value of another kind, reported as JSON_VALUE found a fractional JSON number at $.count where I64 is declared. A defect inside a collection names the collection with in and the innermost declared element type, such as JSON_VALUE found JSON null in $.tags where I64 elements are declared or JSON_VALUE array in $.p has 1 elements where 2 are declared. An error names the path and the declared type but never a value from the document, so it can be reported for a sensitive document.

JSON_VALUE and TRY_JSON_VALUE yield null both where the path finds nothing and where it finds JSON null; JSON_EXISTS tells the two apart. Test the forms together to classify a document without failing the message:

SET amount = TRY_JSON_VALUE(input.payload, '$.amount' AS F64),
    amount_state = CASE
      WHEN is_null(input.payload) THEN 'no document'
      WHEN NOT is_null(TRY_JSON_VALUE(input.payload, '$.amount' AS F64)) THEN 'read'
      WHEN NOT is_null(TRY_JSON_VALUE(input.payload, '$.amount' AS STRING)) THEN 'text'
      ELSE 'missing, null, or unreadable'
    END

To tell a malformed document from a missing value, route the message through JSON_EXISTS or JSON_VALUE and read the error in ON MESSAGE ERROR, where the error names the defect.

As with TRY_CAST, the result of TRY_JSON_VALUE and JSON_VALUE is optional, so it initializes a required field only through an expression that is never null, such as coalesce(TRY_JSON_VALUE(input.payload, '$.qty' AS U32), 0 AS U32), and a statement that assigns it to a required field directly is rejected when it is applied. TRY_JSON_VALUE suppresses only the failures of reading its document: a failure of its document expression still fails the message.

Document Limits

A document is read only when it holds at most 16,777,216 bytes and nests objects and arrays at most 128 deep. A larger or deeper document fails JSON_VALUE and JSON_EXISTS with an invalid_argument error, such as JSON_VALUE document exceeds 16777216 bytes or JSON_VALUE document nests deeper than 128 levels, and yields null from TRY_JSON_VALUE. A result whose text or elements do not fit one column, as with repeat, reports an overflow error such as JSON_VALUE result exceeds what one VEC<STRING> column holds, from TRY_JSON_VALUE too, as TRY_JSON_VALUE result exceeds ..., since it is a limit of the batch rather than a defect of the document. JSON_EXISTS builds no text and never reports it.

Reading a document is bounded by these limits. Like every builtin, an extraction runs to completion for the batch it is evaluating, so stopping a node or a processor takes effect between batches.

Reading A Document Once

Every extraction a route makes from the same document field reads one parse of each document, whether the extractions are in one SET assignment or several, in WHERE, or a mix of JSON_VALUE, TRY_JSON_VALUE, and JSON_EXISTS, so reading ten fields costs one parse rather than ten. A document computed by an expression, such as coalesce(input.payload, '{}'), shares one parse among the extractions of one assignment, and is parsed again for each assignment that reads it. A document is parsed with SIMD instructions that find its structure, chosen at run time from the ones the node’s CPU offers, and each path is then followed and its value written straight into a typed column of the declared type; no document is held as an untyped value. A document field that an earlier SET assignment rewrites is a new column, whose documents are parsed again.

Inside a conditional arm, an extraction parses only the documents of the messages that select the arm, and an extraction in the arm does not share its parse with one outside it. A document written as a literal is parsed once for each batch and shared by every message of it, so a malformed literal document fails every message that evaluates it.

Null Handling

coalesce is optional only when every argument is, so a required last argument makes its result required: coalesce(input.nickname, input.name) initializes a required field when name is required. It evaluates every argument for every message, including the arguments after the first present one, so a failing later argument fails the message; guard such an argument with a conditional. There is no IS NULL operator and no is_not_null function: write is_null(x) and NOT is_null(x). A bare NULL is not an argument of any of these functions; see Literals.

Extrema

greatest and least take one or more arguments of one exact scalar type: any numeric type, BOOL, STRING, DATETIME, or BYTES. They skip null arguments, so their result is required when any argument is. They order values the way the window MIN and MAX aggregates do: BOOL orders false before true, STRING orders by Unicode code point, BYTES orders octet by octet, and floating-point values order NaN above every other value and treat both zeros as equal. Among equal values the earliest argument is returned, so greatest(-0.0, 0.0) is -0.0 and greatest(0.0, -0.0) is 0.0. Every argument is evaluated, whichever one is returned.

clamp takes three arguments of one exact type: any numeric type, STRING, or DATETIME. It compares exactly as < and > do, so it returns a NaN value unchanged and keeps -0.0 inside a range that starts at 0.0. A null argument produces a null result. A message whose low bound is above its high bound, or whose floating-point bound is NaN, reports an invalid_argument error, clamp lower bound is above its upper bound or clamp bound is NaN, and yields null, so give a route whose bounds can cross an ON MESSAGE ERROR policy. A message with a null argument is never failed.

Context And Identity

leak_sensitive takes exactly one argument and returns it unchanged, optional exactly when the argument is; it only changes what the statement may do with the value. now(), uuid_v4(), and uuid_v7() take no arguments and are never sensitive.

now() is one snapshot of the domain clock for each unit of work, shared by every expression of that unit: an ingested group of messages, a batch a processor accepts, and the timer, flush, or wait release that resumes work. It is logical time in a paced domain, which can be before 1970, and actual UTC in an unpaced one. See Domain Clock for how snapshots are taken.

Both UUID functions return the canonical 36-character lowercase form, such as 0192f2b5-6c1d-7e3a-9f4b-2a7c1e5d8b90, and every occurrence of a call in an expression returns its own value. A version 7 UUID encodes its time as milliseconds since 1970-01-01T00:00:00Z and fills the remaining 74 bits at random, so UUIDs of different milliseconds order by time, while UUIDs of one millisecond, such as those of one batch, have no order among themselves. In a paced domain whose logical time is earlier than the epoch, such as one started with START AT '1969-07-20T20:17:00Z', uuid_v7() reports uuid_v7 execution time is before the Unix epoch for every message that evaluates it until domain time reaches the epoch. It never encodes another instant instead.

Header Functions

Header names may be dynamic STRING expressions, and a name matches exactly, letter case included, the names the connector recorded. A null name reads as absent. Header reads are available on HTTP ENDPOINT, WEBSOCKETS ENDPOINT, HTTP REQUEST, KAFKA TOPIC, NATS SUBJECT, PULSAR TOPIC, RABBITMQ QUEUE, and SQS QUEUE ingestors, in their FILTER WHERE and route construction, and in an error route’s construction for a failure on such an ingestor. Header writes are available on HTTP, Kafka, NATS, Pulsar, RabbitMQ, and SQS emitters. Anywhere else a statement is rejected when it is validated, with a message such as function 'read_header' is only available to ingestors whose connector supports headers, MQTT TOPIC ingestors do not support read_header or read_headers, or MQTT emitters do not support write_header.

write_header arguments must be statically non-null STRING expressions, and a sensitive argument requires leak_sensitive(...). They are evaluated after payload construction and route filtering. Calls are staged in source order in a route-local envelope; if any call fails, no payload or partial header envelope is published. See Emitters for each sink’s header rules.

Lookups And UDF Calls

The hash-map name and the field are string literals, checked when the statement is applied; a key expression that fails for any message fails its whole batch. Identical lookups of one program are answered once. Where Expressions Run lists the contexts that accept a lookup, and Lookups describes hash maps and their resource versions.

A UDF call is optional when the UDF declares an OPTIONAL result or when a required parameter receives an optional argument, is sensitive when any argument is, and is deterministic unless the UDF is declared VOLATILE. It never runs for a message whose required argument is null or whose earlier operation already failed, and yields null for it. See Nulls, errors, and volatility for its per-message and whole-batch errors.

String Functions

String functions count and select characters, meaning Unicode scalar values, rather than bytes or grapheme clusters. A combining mark counts as a separate character. Positions count from 1. Every text argument is exactly STRING: a BYTES value is rejected, so no string function measures, joins, or searches octets. Convert between the two with the bytes functions.

lower, upper, and initcap use Unicode case mappings, which never depend on the node’s locale. A mapping can change a value’s length: upper('Grüßen') is GRÜSSEN. A literal, a field, and a computed value holding the same text always convert to the same result. initcap starts a run at every letter or digit that follows a character that is neither, and maps each character on its own: a run that starts with ß starts with SS, no character takes a titlecase form, and a run may start with a digit, so initcap('3rd') is 3rd.

count, start, length, and index may be any integer type and are never narrowed to another: an unsigned count above the I64 range reaches past the end of any text, exactly as the largest I64 count does. A floating-point count is rejected.

substr treats a start at or before 1 as the first character and counts length from there. A start past the end, or a negative length, returns an empty string.

lpad and rpad shorten text longer than length to its first length characters, return an empty string when length is at most 0, and return shorter text unchanged when fill is empty.

split_part returns an empty string when index is at most 0 or past the last part; it never counts from the end. With an empty delimiter, the whole text is part 1.

split uses the same empty-delimiter rule: it returns one part containing the whole text. An empty input also produces one empty part. join on an empty list produces an empty string; concat_ws with no non-null values after the separator does the same. These functions preserve the written order.

concat never yields null for a message, but a call that has an optional argument has an optional result, so it initializes a required field only through an expression that is never null, such as concat(coalesce(input.first, ''), ' ', coalesce(input.last, '')). concat_ws follows the same rule.

Result Size

The values one call produces for a batch share one STRING column, which holds at most 2,147,483,647 bytes of text. A function whose result can be longer than its arguments computes how long each result is before it builds it, and a result that does not fit in what its column has left reports an overflow error and yields null instead of being built:

Inside a conditional arm the column holds only the results of the messages that select the arm, so a message that selects another arm uses none of its text. A call whose arguments are all literals computes one value that every message in the batch holds, so that value must fit once for each of them: repeat('ab', 600000000) fits a batch of one message but reports the error on every message of a batch of two. JSON extraction, URL and IP address functions, and format_datetime, bound their results in the same column limit.

concat, replace, regexp_replace, translate, lower, upper, and initcap build their column without this check, so no message reports an overflow error for them. Keep the text they produce for one batch within the column limit: for example, a replace with an empty from multiplies the length of its text.

String Predicates

Plain substring matching is exact and case-sensitive, and compares UTF-8 bytes, so it never normalizes text.

like and ilike match the entire text. A trailing backslash is a literal backslash. ilike follows Arrow’s Unicode loose matching: it ignores case without expanding characters, so ß does not equal SS. For full Unicode case mapping, apply lower or upper explicitly; neither matching function normalizes text. Each LIKE pattern is limited to 4,096 bytes of UTF-8 text: a longer pattern reports an invalid_argument error, LIKE pattern exceeds 4 KiB, on every message that evaluates it, whatever its text holds.

contains_any compares exact case-sensitive text, including combining marks. A set written in the call as array(...), vec(...), or [...] whose elements are all non-null STRING constants is prepared once with the program. Every other set is read for each message, and the distinct sets of one batch are prepared once each, keeping at most 64 of them for the batch and replacing the one prepared first when more are read. A set has at most 128 non-null patterns and 65,536 bytes of combined pattern text; a larger set reports an invalid_argument error, contains_any pattern set exceeds 128 patterns or 64 KiB, on each message with a non-null text and set that uses it, even when the set is a constant.

Regular Expressions

Regular-expression functions take STRING arguments and use Rust regex syntax. A pattern that does not compile reports a per-message invalid_argument error whose message is invalid regular expression: followed by the parser’s description of the defect.

A pattern written as a literal, or an expression that compiles to a constant, such as a CASE with constant conditions or lower, upper, trim, or coalesce over literals, is compiled once when the node is activated and reused by every batch. It is still not a configuration error: a constant pattern that does not compile reports its per-message error only for the messages that evaluate it, so an invalid pattern in a conditional arm no message selects reports nothing. Any other pattern, including one built with concat, is compiled when a message first uses it and kept in a cache of the 64 most recently compiled patterns per call, which evicts the pattern compiled longest ago and keeps the outcome of a pattern that did not compile. A compiled pattern is limited to 10 MiB; a pattern that compiles past that limit reports a per-message error like any other invalid pattern. A message whose text, replacement, or group is null yields null without compiling its pattern, so an invalid pattern reports nothing for it.

regexp_extract accepts any integer type for group. A negative index produces null. Regex syntax uses Unicode classes by default, while POSIX classes such as [[:alpha:]] are ASCII only. Matching is leftmost-first and supports no backreferences or look-around; the engine keeps linear-time search guarantees rather than enabling backtracking features. In a replacement, a group name runs as far as letters, digits, and underscores continue, so $1a names a group 1a; write ${1}a to follow group 1 with a.

regexp_substr and regexp_extract are null for a message the pattern does not match even when every argument is required, so assign them to an OPTIONAL field or give them a value with coalesce.

The description of an invalid pattern quotes the pattern. A pattern read from a field is part of the message, so the error message of such a pattern carries its text: validate patterns before they reach a route whose error records leave the node, or write patterns as literals.

Bytes, Encodings And Hashes

BYTES values hold arbitrary octets, including zero and non UTF-8 bytes. These functions accept exact types, propagate nulls, and preserve sensitivity. An encoded or hashed sensitive input stays sensitive; emitting it still requires explicit leakage. A cast never converts between BYTES and STRING: input.raw AS BYTES is rejected with BYTES conversions require bytes_from_utf8, bytes_to_utf8, base64 or hex functions.

An empty input encodes and decodes to an empty output. md5 reads STRING text and returns hexadecimal text, while sha256 reads BYTES and returns raw bytes: hash text with sha256(bytes_from_utf8(input.text)) and write the digest with hex_encode.

xxh3_64 hashes the input octets in their given order and returns the algorithm’s unsigned 64-bit number. The value is independent of host byte order and stays the same across nodes and restarts. It is a noncryptographic hash, so use sha256 where collision resistance matters.

A decoding failure reports a cast_failed error: bytes_to_utf8 input is not valid UTF-8, base64_decode input is not valid encoded bytes, or hex_decode input is not valid encoded bytes. Like every message error, it names the failed function without exposing its input.

IP Addresses And Networks

An IP address is a BYTES value in network byte order: four octets for an IPv4 address and sixteen for an IPv6 address, so its length is its family. ip_from_string and is_ip_address read an address from text, ip_in_network reads its network from text, and every other address function reads the octets as one 32-bit or 128-bit number. Parse an address once into a BYTES field and mask and test that field, so each further test costs no second parse: ip_from_string can fail, so two calls of it are two parses even in one expression. A function over an address that is not a constant reports its own errors and is evaluated at each occurrence.

ip_from_string reads an IPv4 address as four decimal numbers from 0 to 255 separated by dots, each without leading zeros, so 010.0.0.1 is rejected rather than read as octal. It reads an IPv6 address in the text forms of RFC 4291: eight groups of one to four hexadecimal digits in either letter case, :: in place of one run of zero groups, and optionally the last two groups written as an IPv4 address, as in ::ffff:192.0.2.1. The text is the address alone: surrounding whitespace, brackets, a port, a prefix length, and an IPv6 zone index such as %eth0 are rejected. No function resolves a name, so ip_from_string('localhost') fails like any other text that is not an address.

ip_to_string writes an IPv4 address in dotted decimal and an IPv6 address in the canonical form of RFC 5952: lowercase hexadecimal groups without leading zeros, with the longest run of two or more zero groups, or the first of two equally long runs, written as ::. An IPv4-mapped address is written with its IPv4 address in dotted decimal. ip_to_string(ip_from_string('2001:DB8:0:0:0:0:0:1')) is 2001:db8::1, and ip_to_string(ip_from_string('::FFFF:C000:201')) is ::ffff:192.0.2.1. A BYTES address renders as base64 in subscriptions and JSON payloads, so write it with ip_to_string to show it as text.

A network is written as an address, /, and a prefix length in decimal without leading zeros: 0 to 32 for an IPv4 network and 0 to 128 for an IPv6 network. The address may set no bit after the prefix, so '10.0.0.1/8' is rejected rather than read as '10.0.0.0/8'. '0.0.0.0/0' holds every IPv4 address and '::/0' every IPv6 address. A network written as a literal, or an expression that compiles to a constant as a constant pattern does, is read once when the statement is applied, and one that does not read rejects the statement with a message that names its defect, such as function 'ip_in_network' network '10.0.0.1/8' has host bits set past its prefix length. Any other network, including one built with concat, is read for each message, a message whose network is the text last read reuses that reading, and a network that does not read fails its message.

Each address has exactly one family, and no function converts between families unless it says so:

• ip_in_network is false for an address of the other family than its network, so no IPv6 address lies in an IPv4 network.
• ip_from_string('::ffff:10.0.0.1') is a 16-octet IPv6 address, the IPv4-mapped form of 10.0.0.1 that dual-stack sockets report for IPv4 clients. It does not lie in '10.0.0.0/8', and ip_unmap of it does. Test ip_in_network(ip_unmap(address), '10.0.0.0/8') to treat such clients as IPv4.
• ip_unmap converts only IPv4-mapped addresses, the ::ffff:0:0/96 range. An IPv4-compatible address such as ::a09:807, and every other IPv6 or IPv4 address, is returned unchanged.
• A prefix length counts bits at the address’s own width, so ip_trunc(address, 24) keeps the first 24 of the 32 bits of an IPv4 address and the first 24 of the 128 bits of an IPv6 address. Where both families occur, choose the length by family: ip_trunc(address, IF ip_family(address) = 4 THEN 24 ELSE 48 END).

A null argument produces a null result. Otherwise a function fails only the messages it cannot answer:

ip_trunc checks its prefix_length first, so a null prefix length yields null whatever the address holds. An address function over a literal, such as ip_from_string('192.0.2.300'), is computed once for each batch, so a literal that does not read fails every message that evaluates it rather than the statement. A statement that passes an argument of another type is rejected, such as function 'ip_in_network' requires BYTES input, found Utf8.

To route malformed text explicitly instead of failing the message, test it first: CASE WHEN is_ip_address(input.client) THEN ip_from_string(input.client) END reads only the messages that hold an address and is null for the others. Address functions keep the sensitivity of their arguments, so whether a sensitive address lies in a network is sensitive.

SET client = ip_from_string(input.client_ip),
    client_subnet = ip_to_string(ip_trunc(output.client, IF ip_family(output.client) = 4 THEN 24 ELSE 48 END)),
    internal = ip_in_network(ip_unmap(output.client), '10.0.0.0/8')
WHERE NOT output.internal

URLs

URL functions read their STRING argument as an absolute URL under the WHATWG URL Standard, the rules web browsers apply, through the Rust url crate. They compute only from the text: none fetches a URL, resolves a host, or consults the public suffix list.

A URL is read and normalized as the URL Standard specifies:

• Leading and trailing spaces and control characters are removed, and so are tabs and newlines anywhere in the text.
• The scheme is lowercased. For the schemes http, https, ws, wss, ftp, and file, the host is lowercased and an internationalized domain name is written in its ASCII form, so the host of http://Bücher.example/ is xn--bcher-kva.example. An IPv4 host is written in dotted decimal, including the forms browsers accept, so the host of http://0x7f.1/ is 127.0.0.1.
• An IPv6 host is written as the URL Standard writes it, lowercase, compressed, and never in dotted decimal, and url_host returns it without its brackets: the host of http://[::FFFF:192.0.2.1]/ is ::ffff:c000:201, which ip_from_string reads.
• . and .. path segments are resolved, and a space or any other character a path cannot hold is percent-encoded: url_path('https://example.com/a/./b/../c d') is /a/c%20d. The path of a URL of those six schemes starts with /.
• A port equal to the scheme’s default is removed, so url_port answers 80 for http://example.com:80/ as for http://example.com/. The defaults are 80 for http and ws, 443 for https and wss, and 21 for ftp. A URL of any other scheme that names no port has a null port.
• Other schemes have no default port and may have no host: the path of mailto:ops@example.com is ops@example.com, and its host is null. Their hosts are kept as written, letter case included, without the ASCII form of an internationalized name.

A component the URL lacks is null: the host of a mailto: or urn: URL and of a file: URL with an empty host, the query of a URL without ?, and the fragment of a URL without #. A URL that ends in ? or # has an empty query or fragment rather than a null one.

The query is read as application/x-www-form-urlencoded parameters. It is split at every &, an empty parameter is skipped, and each parameter is split at its first = into a name and a value; a parameter without = has an empty value. Names and values are percent-decoded with + read as a space, so the query q=hello+world%21&tag=x&tag=y%26z has the value hello world! for q and the values x and y&z for tag. A parameter matches when its decoded name equals name exactly, letter case included. A parameter whose name does not decode matches no name. url_query_value reads only the first matching parameter, so only its value must decode, while url_query_values fails the message when any matching value does not decode.

url_decode replaces each % followed by two hexadecimal digits of either case with the octet they name, and keeps every other character as it is, + included, so url_decode(url_path(input.url)) is the readable path. Rather than guess, it fails a message whose text has a % not followed by two hexadecimal digits, or whose decoded octets are not UTF-8.

A null argument produces a null result. Otherwise a function fails only the messages it cannot answer:

A relative reference, such as the request target /search?q=x of an HTTP request line, is not an absolute URL. Prefix it with a base explicitly: url_query_value(concat('http://localhost', input.target), 'q'). To route text that may not be a URL, test it first: CASE WHEN is_url(input.referrer) THEN url_host(input.referrer) END is null for the messages whose referrer is not a URL.

Each call reads its own URL, so url_host(input.url) and url_path(input.url) each parse it, while a URL that every message shares, such as a literal, is read once per batch, and url_query_value and url_query_values reuse one reading while consecutive messages hold the same URL. is_url over a constant is answered when the statement is applied. Percent-encoding and ASCII domain names can make a component longer than the text it came from, and like the results of repeat, a component that does not fit in what its STRING column has left reports an overflow error. URL functions keep the sensitivity of their arguments, so the host of a sensitive URL is sensitive.

SET scheme = url_scheme(input.referrer),
    referrer_host = url_host(input.referrer),
    campaign = url_query_value(input.referrer, 'utm_campaign'),
    tags = url_query_values(input.referrer, 'tag'),
    landing_path = url_decode(url_path(input.referrer))

Numeric Functions

Numeric functions accept every integer and floating-point type unless a description below narrows it. A function that returns F64 reads an integer argument as the nearest F64, which is exact for every type up to 32 bits and rounds I64 and U64 values beyond 2^53, and reads an F32 argument exactly, so its result follows the F32’s stored value. atan2, log(base, x), and pow take two arguments that may have different numeric types, and always return F64: pow(-8, 3) is the F64 -512.0. A floating-point result that is not finite, such as sqrt(-1.0), ln(0.0), or exp(1000.0), reports a per-message invalid_argument error and yields null instead of producing NaN or an infinity. The error names the function by its canonical name, such as pow produced a non-finite result for a call written power(...).

abs, ceil, floor, round, sign, sqrt, and trunc are exact: each returns the correctly rounded result, which is the same on every node. Rounding keeps the sign of a zero result, so ceil(-0.4), round(-0.4), and trunc(-0.5) are -0.0, and sqrt(-0.0) is -0.0 without an error. radians and degrees multiply by the F64 nearest to π/180 and to 180/π, so their result is the same on every node and within two units in the last place of the exact conversion.

acos, asin, atan, atan2, cos, exp, ln, log(x), log2, pow, sin, and tan evaluate in IEEE 754 double precision through the C math library of the platform a node runs on, which is glibc for the published Linux builds. Their precision is that library’s: Nervix states no bound of its own, and a node with another C library, another version of it, or a CPU for which the library selects another implementation can differ in the last places. log(base, x) computes ln(x) / ln(base), so it carries the rounding of two logarithms and a division, which exceeds two units in the last place for some arguments.

A function reports an error exactly where its result is not a finite value of its type. For finite arguments, that is:

A NaN or infinite argument reports an error unless a finite result is defined for it, as IEEE 754 defines, for example, for atan of an infinity, atan2 of any arguments that are not NaN, exp of negative infinity, log(base, x) with an infinite base and a finite positive x, and these pow cases: pow(1, y) is 1 for every y, NaN included; pow(x, 0) and pow(x, -0.0) are 1; pow(-1, ±inf) is 1; pow(x, -inf) is 0 where |x| > 1 and pow(x, inf) is 0 where |x| < 1; and pow(±inf, y) is a zero for a negative y. sign of an infinity is also defined. abs, ceil, floor, round, and trunc report an invalid_argument error for a NaN or infinite argument, such as floating-point absolute value produced a non-finite result or round produced a non-finite result.

Precision Rounding

round(x, digits) takes any integer type for digits, independently of the numeric type of x, and returns x’s type. A positive digits counts decimal places after the point, 0 rounds to the nearest integer as round(x) does, and a negative digits rounds to a multiple of a power of ten: round(1250, -2) is 1300. Halves round away from zero at every position, so round(-0.125, 2) is -0.13. Every count is accepted. When 10^-digits is finer than the smallest step between values of x’s type near x, the result is x itself, and when x is less than half of 10^-digits in magnitude, the result is zero.

A float is rounded exactly. The result is the value of x’s type nearest to the stored value of x rounded to digits decimal places, so it is the same on every node. The stored value of a decimal literal is the nearest binary float, which can lie on either side of a decimal tie:

• round(0.125, 2) is 0.13, because 0.125 is stored exactly and is a tie.
• round(2.675, 2) is 2.67, because the F64 nearest to 2.675 is slightly below it.
• An F32 rounds its own stored value: the F32 nearest to 0.15 is slightly above 0.15, so round(x, 1) of that F32 is 0.2.

A float result that is zero keeps the sign of x, as round(-0.004, 2) is -0.0. Rounding to a multiple of a power of ten can exceed the largest finite value, as round(1.7976931348623157e308, -308) does, and reports an invalid_argument error.

An integer has no decimal places, so a digits of 0 or more returns it unchanged. A negative digits rounds it to a multiple of 10^-digits, and a multiple that does not fit its type reports an overflow error: round(x, -1) over the I32 value 2147483647 would be 2147483650.

Floating-Point Classification

Classification functions take an F32 or F64 argument. An integer argument is rejected when the statement is applied, since no integer is NaN or infinite. A null argument produces a null result, and no value makes them fail.

A decoded float or a cast from STRING can hold NaN or an infinity, so a route can test for them before calling a function that would report an error: IF is_finite(input.reading) THEN sqrt(abs(input.reading)) ELSE 0.0 END.

Bitwise Functions

Bitwise functions take integer arguments and read each value as its two’s complement bits at the width of its type, so bitwise_not over the U8 value 0 is 255 and over the I8 value 0 is -1. A null argument produces a null result.

bitwise_and, bitwise_or, bitwise_xor, bitwise_not, and bit_count never fail.

A shift takes count from any integer type, independently of the type of value, and a negative count reports an invalid_argument error. Shifts are checked like arithmetic:

• shift_left reports an overflow error when the product does not fit the type of value, including a signed value whose sign would change: shift_left of the I8 value 64 by 1 fails, and of the I8 value -1 by 7 is -128. A count at or beyond the type’s width moves every bit out, so it returns 0 for a zero value and fails for any other.
• shift_right never overflows. A signed value keeps its sign, so shift_right(-5, 1) is -3, and a count at or beyond the type’s width returns -1 for a negative value and 0 for any other.

Datetime Functions

A DATETIME is a UTC instant with nanosecond precision. Its range is the signed Unix-nanosecond range, 1677-09-21T00:12:43.145224192Z through 2262-04-11T23:47:16.854775807Z. Datetime functions compute exactly from the values they are given and never read a clock, so a call gives the same result for the same arguments whenever and on whichever node it runs. The current time enters an expression as a value only through now(), which returns the execution-local domain time: date_trunc('day', now(), 'Europe/Berlin') follows a paced domain’s logical clock at any TIME RATE, while the work a call does, and how long it takes, never depends on the domain’s pace.

unit, part, width, zone, format, and disambiguation are literals written in the call, not expressions, and they are checked when the statement is applied: a zone is resolved and a format is compiled once then, never for each message. unit, part, zone, and disambiguation are STRING literals whose names are case-insensitive, and format is a STRING literal. width is a positive integer literal, and width units must not exceed 9,223,372,036,854,775,807 nanoseconds, about 292 years. A name must match exactly apart from letter case, so plurals and abbreviations such as days or ms are unknown. A call with an unknown name, a non-literal argument, an invalid format, or a width that is not positive is rejected, and its message names what the call accepts, such as function 'date_bin' does not accept time unit 'month'; expected one of nanosecond, microsecond, millisecond, second, minute, hour, day, week or function 'date_part' requires its date part to be a STRING literal. A call that names no zone reads in UTC; see Time Zones for the zones a call can name.

The units nanosecond through week have a fixed length. A DATETIME has no leap seconds, so every UTC day is exactly 86,400 seconds long. month, quarter, and year are calendar units, whose length depends on the month they count from. date_trunc, date_add, and date_diff accept every unit; date_bin, to_unix, and from_unix accept only units of fixed length.

A date part reads value’s local date and time in zone:

Results are exact to the nanosecond, and each function rounds in one fixed direction:

• date_trunc, date_bin, and to_unix round toward negative infinity, including before the Unix epoch and before an origin, so a value belongs to the unit or bin that starts at or before it. date_trunc('day', ...) of 1969-12-31T23:59:59.999999999Z is 1969-12-31T00:00:00Z, and to_unix('millisecond', ...) of the same value is -1.
• In UTC, a day, and every shorter unit, starts a whole number of units after the Unix epoch. A week starts on Monday in date_trunc, while to_unix('week', ...) counts whole weeks from the epoch itself, which was a Thursday.
• date_bin accepts an origin before or after value. A value exactly on a bin boundary starts its own bin.
• date_diff rounds toward zero. For units that count elapsed time, exchanging start and end only changes the sign of the result, and date_diff('second', start, end) is 0 when the two values are less than a second apart in either direction.

A null argument produces a null result. date_part, to_unix, and format_datetime never fail a message; see Writing Values for the one batch-wide limit of format_datetime. Another function reports a per-message error and yields null exactly where it cannot produce a result:

The error’s message names the function, such as date_add result is outside the DATETIME range, date_diff result does not fit I64, or parse_datetime local time is ambiguous in America/New_York.

SET hour = date_part('hour', input.occurred_at),
    local_hour = date_part('hour', input.occurred_at, 'America/New_York'),
    quarter_hour = date_bin('minute', 15, input.occurred_at, from_unix('second', 0)),
    local_day = date_trunc('day', input.occurred_at, 'Europe/Berlin'),
    renewal = date_add('month', 1, input.subscribed_at),
    deadline = date_add('millisecond', input.timeout_ms, input.occurred_at),
    age_seconds = date_diff('second', input.occurred_at, now()),
    received_at = from_unix('millisecond', input.epoch_ms),
    label = format_datetime('%a %d %b %Y %H:%M %Z', input.occurred_at, 'Asia/Tokyo'),
    logged_at = parse_datetime('%d/%b/%Y:%H:%M:%S %z', input.log_time)

Calendar Arithmetic

date_trunc, date_add, and date_diff work on the local calendar of their zone. In UTC and at a fixed offset every day is 24 hours long. Under the rules of an IANA time zone a local day can be shorter or longer, because daylight saving time and other transitions skip or repeat local times. An hour or any shorter unit is always elapsed time: date_add('hour', 1, ...) is one hour later in every zone.

date_trunc returns the first instant of the local unit that holds value: the earliest instant from which the zone’s clock showed times inside that unit without interruption until value. A day starts at local midnight, a week on Monday, a month on its first day, a quarter on the first day of January, April, July, or October, and a year on January 1.

• date_trunc('day', ...) of 2024-03-10T11:00:00Z in America/New_York is 2024-03-10T05:00:00Z, midnight in New York, even though that day is only 23 hours long.
• A unit whose local start a transition skips starts when the skipped span ends. America/Sao_Paulo skipped midnight on 2018-11-04, so that day starts at 2018-11-04T03:00:00Z, local 01:00.
• A local time a transition repeats stays in one unit. New York showed 01:00 through 02:00 twice on 2024-11-03, and date_trunc('hour', ...) of both 2024-11-03T05:30:00Z and 2024-11-03T06:30:00Z is 2024-11-03T05:00:00Z, where the repeated hour began.
• In an IANA zone every unit follows the zone’s clock, including local mean time before standard time: New York ran 4:56:02 behind UTC until 1883-11-18T17:00:00Z, when its clocks went back from 12:03:58 local mean time to 12:00 Eastern Standard Time, so date_trunc('day', ...) of 1883-11-18T17:01:00Z there is 1883-11-18T04:56:02Z.

date_add moves value in local time:

• An hour and every shorter unit move by elapsed time.
• A day or a week moves by 24 hours or 7 days in UTC and at a fixed offset. In an IANA zone it moves the local date and keeps the local time of day, so date_add('day', 1, ...) of 2024-03-09T12:00:00Z in America/New_York is 2024-03-10T11:00:00Z, 23 hours later.
• A month, quarter, or year moves the local month and keeps the day of the month and the local time of day, unless the new month is shorter, in which case the result is on its last day: date_add('month', 1, ...) of 2024-01-31T23:30:00Z is 2024-02-29T23:30:00Z, and date_add('year', 1, ...) of 2024-02-29T12:00:00Z is 2025-02-28T12:00:00Z. Each call moves once from value, so adding one month twice to January 31, 2024 lands on March 29, while adding two months at once lands on March 31.
• When the moved local time falls in a span the zone skips, the result moves forward by the length of that span, and when the zone shows the moved local time twice, the result is the earlier instant. Adding a day to 2024-03-09T07:30:00Z in New York lands on the skipped 02:30, so the result is 2024-03-10T07:30:00Z, local 03:30.
• An amount of 0 returns value itself.

date_diff counts elapsed time for an hour and every shorter unit, and for a day or a week in UTC or at a fixed offset. It counts whole calendar units for a day or a week in an IANA zone and for a month, quarter, or year in every zone. A calendar count measures from start:

1. The count runs to end’s local date, moved toward start by as few days as it takes for start’s local time of day on that date to not lie past end. date_diff('day', ...) from 2024-03-09T12:00:00Z to 2024-03-10T11:00:00Z in America/New_York is 1, because the start’s local time of day, 07:00, on 2024-03-10 in New York is 11:00 in UTC, and it is 0 in UTC, where the two instants are 23 hours apart.
2. Days count the dates between. Weeks are whole sevens of those days.
3. Months count from start’s local date, and a month is complete once the date has reached start’s day of the month. date_diff('month', ...) from 2024-01-31T00:00:00Z to 2024-02-29T00:00:00Z is 0, even though date_add('month', 1, ...) of the start is the end. Quarters and years are whole threes and twelves of those months.

Because a calendar count measures from start, exchanging start and end can change its magnitude as well as its sign. Two instants on the same local date are 0 days apart.

Time Zones

A zone is one of:

• 'UTC'.
• An IANA time zone name, such as 'Europe/Berlin', 'America/New_York', or 'Asia/Kolkata', matched without regard to letter case.
• A fixed UTC offset written '+HH:MM' or '-HH:MM', from '-23:59' to '+23:59'. '-00:00' is the same zone as '+00:00', which reads as UTC does but is written +00:00 by %Z and %Q.

Anything else, including an abbreviation such as 'CEST', 'PST', or 'EDT' that is not also an IANA name, the host’s local zone, or an offset written another way, is rejected when the statement is applied, with function '<name>' does not accept time zone '<zone>'; expected an IANA time zone name, UTC, or a UTC offset such as '+05:30'. Some names that look like abbreviations are IANA names, and are accepted with the rules the database gives them: 'EST', 'MST', 'HST', 'CET', 'EET', 'WET', 'MET', 'GMT', 'UCT', 'Universal', and 'Zulu', as well as the 'Etc/GMT+5' family, whose sign is the reverse of the offset’s. A zone only decides how an instant reads as a local date and time: every DATETIME a function returns is a UTC instant.

Time zone rules come from the IANA Time Zone Database bundled into Nervix, release 2026c in this version. Nervix never reads the time zone database, the time zone, or the locale of the host it runs on, so every node of a cluster computes the same local times. A Nervix upgrade can bundle a newer release, and a zone whose rules the release changed then reads differently in every computation after the upgrade, including computations over instants in the past.

An IANA zone keeps the name the database gives it: %Q writes America/New_York for 'america/new_york', and US/Eastern for the alias 'US/Eastern'. A fixed offset is written in its +HH:MM form by both %Q and %Z, and UTC as UTC.

Datetime Formats

format_datetime writes a local date and time in a format, and parse_datetime reads one. A format is a STRING literal in which % starts a directive and every other character, including whitespace, is literal text written as it is and read only where it appears exactly. Names are English and never depend on a locale.

The - flag writes a number without padding: %-m, %-d, %-j, %-V, %-H, %-I, %-M, and %-S. Any other directive, including a two-digit year, a locale’s date or time such as %c, a fraction written %.3f rather than %3f, and a flag on a directive that does not take it, such as %-e, is rejected when the statement is applied, and the message names the directive and the byte of the format it starts at, such as unknown directive '%q' at byte 3. A format that ends inside a directive, such as a trailing % or %-, is rejected with incomplete directive at byte <n>. Offsets from local mean time can have seconds, as New York’s -04:56:02 before 1883 does. %s counts whole seconds rounded down, so %s%.f writes 1969-12-31T23:59:59.5Z as -1.5: one second before the epoch plus half a second.

Every value a format describes must fit in 256 bytes, counting every directive at its longest in the call’s zone. A format that could describe a longer value is rejected when the statement is applied, so each value of a formatted column holds at most 256 bytes.

Writing Values

format_datetime writes value’s local date and time in zone, and writes a null value as null. It never fails a message. format_datetime('%FT%T%:z', ...) of 2024-11-03T06:30:00Z in America/New_York is 2024-11-03T01:30:00-05:00, and an empty format writes an empty string.

A call sizes its column for every message it formats at the format’s longest value before it writes any, so a batch whose messages could together exceed the 2,147,483,647 bytes one STRING column holds fails as a whole with format_datetime values for <n> messages of up to <m> bytes each could exceed the text one STRING column holds. At the 256-byte maximum that takes more than 8,388,607 formatted messages in one batch.

Reading Text

parse_datetime reads text from its first byte to its last and never guesses or normalizes what it reads:

• Literal text must appear exactly, and a directive reads exactly its field: %m reads two digits, and %e reads a space and a digit, or two digits. A - flag reads as many digits as the field’s width allows, with or without a leading zero. %.f reads nothing, or . and one to nine digits; a . without a digit after it does not match. %s reads an optional -, never a +, and one to nineteen digits. %Y and %G read any four digits, and a year outside the DATETIME range fails as that range does.
• Month and weekday names, and AM and PM, are read without regard to letter case. %z, %:z, and %::z read the forms they write, and also read an uppercase Z as UTC. Each part of an offset is at most 23:59:59.
• Every field must lie in its range: a 13th month, hour 24, and second 60 are rejected, since a DATETIME has no leap seconds. The date must exist, so 2023-02-29 is rejected rather than read as March 1, and a day of the week read with a calendar or ordinal date must be that date’s day.

The first field that fails is reported, checking the time of day before the date: a text such as 2023-02-29 24:00:00 reports its hour. A day of the year 366 in a common year and an ISO week 53 in a year of 52 weeks are dates that do not exist.

A readable format reads each field at most once and names exactly one instant. An empty format writes an empty string but reads no instant:

• A date, as %Y with a month and a day of the month, %Y with %j, %G with %V and a day of the week, or %s with nothing but a fraction of a second. %Z and %Q cannot be read.
• Optionally a time of day, as %H, or %I with %p. %M requires an hour, %S requires %M, and a fraction of a second requires %S. A time of day the format does not read is midnight.
• Optionally a UTC offset. A format that reads %z, %:z, or %::z places its local date and time at that offset, and one that reads %s names its instant directly: both take no zone. Every other format reads a local date and time and requires a zone to place it.

disambiguation decides the instant of a local date and time that zone skips or repeats:

A call without disambiguation rejects. In America/New_York, 2024-03-10 02:30:00 does not exist and 2024-11-03 01:30:00 happens twice: earlier reads them as 2024-03-10T06:30:00Z and 2024-11-03T05:30:00Z, and later as 2024-03-10T07:30:00Z and 2024-11-03T06:30:00Z.

A null text produces a null result. Every other failure fails only its message:

A message never quotes the text it could not read. It names byte positions, the format’s own literal text and directives, field names, and the zone.

Array And Vector Functions

[a, b, ...] and array(a, b, ...) construct an ARRAY whose fixed width is the number of arguments. vec(a, b, ...) constructs a VEC; vec() constructs an empty vector when it is the whole value assigned to a declared VEC field, which supplies its element type. Constructor elements must have exactly the same declared type, which may be any type, BYTES, ARRAY, and VEC included, so a literal element beside a narrower field is cast: [input.low, 0 AS I32]. If any element is null, the constructed container is null; schema elements themselves remain required. A fixed ARRAY has at least one element, so [] and array() are rejected.

The functions below take ARRAY or VEC values described in Schemas And Codecs, and a function of two lists accepts an ARRAY and a VEC, or fixed arrays of different widths, together. The elements of a multidimensional ARRAY are its outermost items. A null container produces a null result, including for binary functions when either container is null.

nth counts from 0, unlike string positions: nth(input.values, 0) is the same element as first(input.values). A function whose elements the table narrows rejects any other element type when the statement is validated, such as a list whose elements are themselves ARRAY or VEC values, with function 'first' requires ARRAY or VEC elements of a scalar type. first, last, nth, min, and max do not take BYTES elements.

min and max order floating-point elements by the IEEE 754 total order, in which -0.0 is below 0.0, a NaN with the sign bit set is below every other value, and any other NaN is above every other value. This differs from greatest and least and from the window MIN and MAX aggregates, which treat both zeros as equal and order every NaN above every other value. Among equal elements, the first is returned.

sum follows the arithmetic operators: an integer sum that overflows its type reports integer sum overflowed with the kind overflow, and a floating-point sum that is not finite reports floating-point sum produced a non-finite result with the kind invalid_argument. dot checks its products and their sum at the element type, so a dot product of two U8 lists fails once it reaches 256, with integer dot product overflowed. dot and distance require equal lengths in every message; a mismatch reports invalid_argument, vector lengths differ: left has 3, right has 2, for that message. A non-finite mean, dot, or distance reports invalid_argument, such as mean produced a non-finite result; mean sums its elements in F64 before it divides, so a sum beyond the F64 range fails even where the mean itself would be finite. contains and overlap use the scalar equality contract: NaN equals no element, and positive and negative zero are equal. These functions compare exact element types; they never cast or stringify list elements.

In a window route, count, sum, first, last, min, and max are always window aggregates, like every other aggregate name. They take a per-row expression over input and aggregate it across the rows the window retained, so COUNT(input.values) aggregates retained rows rather than counting the elements of one list. A window route therefore cannot use these six list functions, even inside an aggregate’s argument, where SUM(count(input.values)) is rejected as a nested aggregate. Everywhere else these names are the list functions above.

Window Aggregates