/drasi

ContinuousQueries bundle

Use this bundle for query authoring, query-language selection, result contracts, joins, static validation, and query troubleshooting.

Query authoring rules

1. Set mode: query when authoring Drasi for Kubernetes ContinuousQuery resources unless current docs say otherwise.
2. Set queryLanguage explicitly for every query when the schema supports it. Do not rely on defaults.
3. Prefer Cypher for new queries. Use GQL only when ISO compliance or multi-platform GQL interoperability is an explicit requirement and the pinned runtime's GQL parser/function support is verified.
4. Define the result contract before attaching reactions.
5. Use labels and property names that match the source data model exactly.
6. Avoid implicit Cartesian joins. Use provider-supported join configuration for cross-source relationships.
7. Keep queries small, observable, and testable.
8. Do not mix examples from Drasi Server REST payloads with Drasi for Kubernetes YAML without adapting shape.
9. Validate query behavior with expected added, updated, and deleted result changes.
10. Avoid comma-separated node patterns in MATCH for portability. Prefer one MATCH per pattern and explicit WHERE joins.
11. For enum-like string states, prefer exact equality (=) over pattern operators unless operator support is proven on the pinned runtime version.

Parser-compatibility preflight (required)

Before applying full production queries, compile a minimal query using the same operator classes (=, IN, CONTAINS, date/window functions) on the pinned runtime.

If the minimal query fails parser validation, do not keep retrying full manifests. Replace the unsupported operator/function with a runtime-supported alternative and re-apply.

Result contract

Every query should declare or document:

• Query id/name.
• Runtime form: Server API payload or Kubernetes resource.
• Query language.
• Source names and expected labels.
• Returned fields and types.
• Meaning of an added result.
• Meaning of an updated result.
• Meaning of a deleted result.
• Reaction consumers and downstream schema expectations.
• Known latency, window, or aggregation assumptions.

Join guardrails

For cross-source or relational joins:

• Define synthetic relationships or join mappings explicitly where Drasi requires them.
• Avoid MATCH (a), (b) WHERE a.id = b.id patterns unless current docs confirm the runtime supports the form.
• Keep join keys stable, indexed in source systems where applicable, and consistently typed.
• Test with missing keys, duplicate keys, and late-arriving changes.

Function and language verification

Before using a function, window, duration, aggregation, or temporal expression:

1. Check current Drasi Continuous Query syntax docs for the selected language.
2. Prefer a documented Drasi function over a similar Cypher/GQL function from another engine.
3. Create a minimal query proving the function compiles.
4. Add a small input-change test proving the runtime result.

Do not assume Neo4j, openCypher, ISO GQL, or another graph engine has identical function support.

Static review checklist

Reject or revise queries with:

• Missing queryLanguage when supported.
• Source names that do not exist.
• Labels that do not match the source model.
• Reactions expecting fields not returned by the query.
• Broad unbounded queries without a clear reason.
• Implicit joins where explicit join configuration is required.
• Non-deterministic result shape.
• No test data or expected output.

Validation commands

For Drasi for Kubernetes:

drasi list query -n "$DRASI_NAMESPACE"
drasi describe query "$QUERY_NAME" -n "$DRASI_NAMESPACE"

For Drasi Server, use the documented REST endpoints for listing queries, creating queries, retrieving query details, and polling query results.

Cross-runtime portability

When a ContinuousQuery is intended to run unchanged across more than one Drasi runtime form (for example, a query developed against drasi-lib for low-latency in-process evaluation that must later run on Drasi Server or Drasi for Kubernetes), restrict authoring to the runtime-neutral feature subset and verify with a smoke test on each target before pinning.

Portability matrix

Runtime-neutral query authoring pattern

1. Project only scalar fields (RETURN n.id AS id, n.email AS email); avoid runtime-specific projections (paths, list-valued aggregations) until you have confirmed support on every target.
2. Pin language explicitly (queryLanguage: Cypher or queryLanguage: GQL) - never rely on defaults that may differ across runtimes.
3. Run a smoke test that asserts identical result rows for the same source change on each target runtime before promoting the query.
4. If a target runtime cannot evaluate the query, prefer re-modelling the query over forking it. A forked query becomes two queries to maintain, and divergence is hard to detect from telemetry.

This portability discipline pairs with the mixed-runtime guidance in SKILL.md and the cross-runtime compatibility section in templates/drasi-version-pinning.md.

Common anti-patterns (don't / do instead)

Cypher and GQL feature support

Drasi ContinuousQueries are a subset of openCypher 9, not the full language. The same engine also accepts GQL (ISO/IEC 39075:2024 - the ISO graph query language, not GraphQL); both parsers are peers over a shared AST in drasi-core/query-ast/. Selection: Query::cypher(id) / Query::gql(id) for drasi-lib, queryLanguage: Cypher | GQL for Drasi Server REST and Drasi for Kubernetes CRDs.

New-project default: start with Cypher for all new Drasi ContinuousQuery work, unless you have a specific reason for GQL (ISO compliance requirement, multi-system GQL interoperability). Reasoning:

1. Cypher is the primary target for new features. The drasi.* temporal namespace, custom-plugin authoring patterns, and all official Drasi examples use Cypher. GQL support was added later (drasi-platform PR #289) and may lag on function registration parity.
2. Separate function registries (drasi-core issue #217): A function registered in functions-cypher is invisible from GQL mode. Custom function authors must register in both registries, and GQL-only queries may silently resolve to a no-op for functions the author forgot to dual-register.
3. Drasi is pre-1.0 and GQL support is also pre-1.0. ISO GQL 39075:2024 is a new standard; Drasi's implementation is a subset. Cypher (openCypher 9) syntax is stable, with years of battle-tested parsing.
4. All Drasi documentation, learning materials, and community examples use Cypher. A developer starting with Cypher will have friction-free access to the full reference corpus.
5. Syntax differences are cosmetic (elementId vs element_id, datetime() vs current_datetime()). No material advantage to GQL for single-platform use.

Use GQL only when ISO compliance or multi-platform GQL interoperability is an explicit requirement. Record the language choice in versions.md.

AST surface - what the parsers actually accept

From drasi-core/query-ast/src/ast.rs on main:

That the AST has dedicated nodes for Case, List, and Iterator is the strongest single signal of which Cypher subset is parseable. Whether the evaluator supports every shape on main is a separate question - verify against the SDK version pinned in versions.md.

Clauses

Predicates and operators

Pattern syntax

• Nodes: (v:Label {prop: value}).
• Relations: -[:TYPE]->; anonymous middle nodes (:Building) and multi-segment paths joined with commas in MATCH are supported.
• Identifier escaping with backticks for special characters: MATCH (n:`Special-Label`).
• Element identity:
  • Cypher mode: elementId(e)
  • GQL mode: element_id(e)
• Both modes share the same MATCH / WHERE / RETURN shape.

Aggregating functions (eight built-ins on main)

From drasi-core/core/src/evaluation/functions/aggregation/:

Aggregators are incremental, not batch - see bundles/custom-plugins/guide.md for the AggregatingFunction trait (initialize_accumulator / apply / revert / snapshot / accumulator_is_lazy). Values are individually applied when a row newly matches and reverted when a row newly stops matching; the engine does not recompute from scratch.

Note on third-party "unsupported features" lists. Some community guides list collect() as "not in the supported subset". The repo contradicts this - aggregation/collect.rs is implemented with the full apply / revert lifecycle. Treat third-party subset lists as starting hypotheses, not facts; verify against the repo.

drasi.* namespace (temporal logic via functions, not new clauses)

Names and signatures below are verified against the official Drasi Custom Functions reference (checked 2026-07-21). This is the authoritative list, do not invent drasi.* names (e.g. drasi.age, drasi.minutes, drasi.now do not exist; express elapsed-time logic with drasi.trueFor or by comparing drasi.changeDateTime() to datetime()).

Code-registered but not yet in the official docs page (verified against both functions-cypher/src/lib.rs and functions-gql/src/lib.rs on drasi-core main, 2026-08-24). Treat as undocumented surface: verify behaviour against source before relying on it, and re-check whether the docs page has caught up:

drasi.trueLater returns the special value drasi.awaiting while it waits for the scheduled timestamp, reactions must treat "no row yet" as a valid pending state, not an error. These are dispatched through FunctionExpression AST nodes in the same way as Cypher built-ins; they are registered against the same FunctionRegistry. New temporal logic should follow this pattern

• it is materially easier than adding a clause (see bundles/custom-plugins/guide.md query-language extension points).

GQL mode differences

• Identity function naming: elementId(e) (Cypher) vs element_id(e) (GQL).
• Same MATCH / WHERE / RETURN shape; same pattern syntax.
• Separate function set (functions-gql crate). A function registered in functions-cypher is invisible from GQL mode unless also registered in functions-gql (drasi-core issue #217).
• GQL was added to drasi-platform via PR #289.

Known unsupported or hedged features

Function reference

The following tables document the built-in functions available in Drasi's Cypher and GQL parsers, sourced from the drasi-core evaluation engine. Each function is registered in the FunctionRegistry and dispatched through FunctionExpression AST nodes.

All functions shown below are available in both Cypher and GQL modes unless noted. The aggregating functions (already documented above) and drasi.* temporal namespace (also above) are not repeated here.

[VERIFY] EvidenceType = Source WhereToCheck = drasi-core/core/src/evaluation/functions/, function registry by category; verify function names and signatures against the pinned drasi-core commit [/VERIFY]

Cypher scalar functions

Numeric functions

Trigonometric functions

Text/string functions

Text functions are registered from core/src/evaluation/functions/text/text.rs and include string inspection, transformation, and pattern matching. Verify the exact function name and argument count against the pinned release before authoring. Common patterns include:

• Lowercase/uppercase conversion
• Substring extraction
• String trimming
• Pattern matching (CONTAINS, STARTS WITH, ENDS WITH are supported as operators, see predicates table above)

[VERIFY] EvidenceType = Source WhereToCheck = drasi-core/core/src/evaluation/functions/text/text.rs, exact function names and signatures [/VERIFY]

List functions

Temporal instant functions

Functions for creating, parsing, and comparing date/time instants. Verify exact signatures against the pinned release as the temporal function surface is actively evolving alongside the drasi.* temporal namespace.

[VERIFY] EvidenceType = Source WhereToCheck = drasi-core/core/src/evaluation/functions/temporal_instant/, constructor and accessor function signatures [/VERIFY]

Temporal duration functions

Functions for creating durations and computing time between instants.

[VERIFY] EvidenceType = Source WhereToCheck = drasi-core/core/src/evaluation/functions/temporal_duration/, duration function names and accessors [/VERIFY]

Metadata functions

The element identity functions are the canonical way to reference individual graph elements across changes. changeDateTime is useful for recency-checking without maintaining a separate timestamp property, it reads the Drasi-internal effective_from metadata on the element.

Context mutator functions

[VERIFY] EvidenceType = Source WhereToCheck = drasi-core/core/src/evaluation/functions/context_mutators.rs, context mutation function signatures [/VERIFY]

Context mutators allow queries to influence the evaluation context for downstream query parts. Verify exact function names against the pinned release.

Future / pending temporal functions

Functions from core/src/evaluation/functions/future/ that complement the drasi.* temporal namespace. These overlap with the drasi.* functions already documented above and are registered under both paths. Key additional functions not documented in the drasi.* table:

Past / historical temporal functions

Functions from core/src/evaluation/functions/past/ for querying element state history. These enable queries over the temporal index when it is configured on the Source.

Re-verify each function against query-cypher/src/ and the functions-* crate on the drasi-core commit pinned in versions.md before authoring around the limitation. The list is conservative - features may have landed since the last currency check.

Common symptoms

Join cardinality and result-contract example

Cardinality budgets

ContinuousQueries materialize joined state. Plan cardinality before authoring:

If you exceed the ceiling for your runtime form, expect:

• Query evaluation latency degrading at the p99 first, then p95.
• Memory pressure on the query container; possible OOM kills.
• Inconsistent result updates as the engine prioritises new changes over backfill.

Stress-test with realistic cardinalities before pinning a production query.

Result contract - annotated example

Source (PostgreSQL users table):

Query:

MATCH (u:User)
WHERE u.tier = 'gold' AND u.status = 'active'
RETURN u.id AS userId, u.email AS userEmail

Result contract documented for downstream reactions:

queryId: gold-active-users
queryLanguage: Cypher
sources: [users-pg]
fields:
  - name: userId
    type: string
    classification: Internal
    nullable: false
  - name: userEmail
    type: string
    classification: Confidential       # see security/guide.md classification matrix
    nullable: false
changeKinds: [added, updated, deleted]
ordering: best-effort (not strictly ordered across keys)
duplicateSemantics: at-least-once     # reactions must be idempotent

Publish this contract alongside the query YAML so reaction authors know exactly what to expect and what redaction is required.

Non-events / absence-of-change pattern

Drasi can detect when expected changes do not occur within a defined time window. This is the "absence of change" or "non-events" pattern, a common requirement for watchdog, heartbeat, and deadline monitoring.

When to use

• Alert when a sensor stops reporting (temperature, pressure, motion).
• Notify when a process has not completed by a deadline.
• Trigger escalation when expected state transitions do not happen (order not shipped, payment not received).
• Detect stale connections or silent components in a distributed system.

How it works

The pattern uses a two-query approach:

1. State query: Captures the current state of entities with their last-known timestamps or sequence numbers.
2. Absence query: Projects the state through a time window and filters for entities whose last activity timestamp is older than the threshold.

Cypher example

// Step 1: State query -- track sensors and their last heartbeat
MATCH (s:Sensor)
RETURN s.id AS sensorId, s.name AS sensorName, s.lastHeartbeat AS lastHeartbeat

// Step 2: Absence query -- sensors with no heartbeat in the last 5 minutes
MATCH (s:Sensor)
WHERE s.lastHeartbeat < datetime() - duration('PT5M')
RETURN s.id AS sensorId, s.name AS sensorName, s.lastHeartbeat AS lastHeartbeat,
       datetime() AS currentTime

GQL example

MATCH (s:Sensor)
WHERE s.lastHeartbeat < current_datetime() - INTERVAL '5' MINUTE
RETURN s.id AS sensorId, s.name AS sensorName, s.lastHeartbeat AS lastHeartbeat,
       current_datetime() AS currentTime

Non-events via drasi.* temporal functions

The idiomatic Drasi way to react to absence of change is drasi.trueFor, it emits an added result only when a condition has held continuously for a duration, which is exactly "this has been true (silent / over threshold) long enough to act on". Do not reach for invented helpers like drasi.age() or drasi.minutes(), those functions do not exist (see the verified drasi.* table above).

// Freezer temperature over threshold continuously for 10 seconds
// (canonical drasi.trueFor pattern from the official reference)
MATCH (f:Freezer)
WHERE drasi.trueFor(f.temp > 32, duration({ seconds: 10 }))
RETURN f.id AS id, f.temp AS temp

If instead you track a lastHeartbeat timestamp on the entity, compare it against the current time with real functions (no drasi.age): drasi.changeDateTime() gives the element's last-change time, and datetime() / duration() express the window.

// Sensors whose last change is older than 5 minutes
MATCH (s:Sensor)
WHERE s.lastHeartbeat < datetime() - duration({ minutes: 5 })
RETURN s.id AS sensorId, s.name AS sensorName, s.lastHeartbeat AS lastHeartbeat

Confirm drasi.trueFor / duration() availability and exact duration() map syntax against the pinned runtime; both are documented in the Drasi Custom Functions reference (checked 2026-07-21).

Result contract for non-event queries

queryId: stale-sensors
queryLanguage: Cypher
sources: [sensors-source]
fields:
  - name: sensorId
    type: string
    nullable: false
  - name: sensorName
    type: string
    nullable: false
  - name: lastHeartbeat
    type: datetime
    nullable: false
changeKinds: [added, deleted]   # added when a sensor falls behind threshold; deleted when it recovers
ordering: best-effort

The result contract is unusual because the query fires on a time-based evaluation rather than a data change. Results are:

• added: A sensor crossed the staleness threshold (was reporting, now silent).
• deleted: A sensor recovered (started reporting again, so it no longer matches the absence condition).
• updated: Rare, a sensor that is already in the stale set gets an even older timestamp.

Design considerations

• Evaluation cadence: Absence queries rely on periodic re-evaluation by the Drasi runtime. Confirm the evaluation interval is appropriate for your deadline requirements. A 5-minute staleness check evaluated every 60 seconds is safe; a 5-second staleness check evaluated every 60 seconds will miss transitions.
• Threshold tuning: Set the absence window to at least 2x the expected heartbeat interval to avoid flapping from clock skew or transient delays.
• Recovery handling: When a stale entity recovers (sends a heartbeat again), it is removed from the result set (deleted). Reactions should handle the delete event by clearing the alert or notifying that the entity is back online.
• False positives: Test absence queries with realistic data patterns to verify that normal processing delays do not trigger false alerts.
• Cross-reference: See tutorial/absence-of-change in the drasi-project/learning repository for a full worked example with deployment instructions.

Known runtime limitations

[VERIFY] EvidenceType = Docs + ReleaseNotes WhereToCheck = drasi-platform release notes and drasi-context.yaml for time-window function support at the pinned version Claim = drasi.trueFor / drasi.trueUntil / drasi.slidingWindow, duration() map syntax, and GQL INTERVAL syntax behave identically at the pinned runtime version [/VERIFY]

• The temporal drasi.* functions and duration() are documented (see the verified drasi.* table above), but availability and exact duration() argument shape can differ across pre-1.0 releases, verify against the pinned release before relying on absence-of-change queries in production.
• The datetime() (Cypher) / current_datetime() (GQL) constructor availability varies. Test on the target runtime.