SignalQL

Appearance

Adapters (@signalql/adapters) ​

@signalql/adapters provides concrete compile/run behavior across the current language (v0.1 → v0.5):

  • postgresAdapter — compiles to parameterized SQL through @signalql/compiler (incl. v0.3 aggregates, v0.4 graph/lineage recursive SQL, and v0.5 object, dependency-state, and context-candidate SQL).
  • csvAdapter — evaluates SignalQL AST in-memory against demo events (v0.1–v0.3); no database required.
  • evalGraph / evalTrace / evalContext … — in-memory evaluators for v0.4 graph statements over a demo graph.
  • createObjectRuntime(store) — in-memory reference runtime for every v0.5 statement (objects, revisions, representations, dependency state, lineage, CONTEXT FOR "task", EXPLAIN CONTEXT, SHOW CAPABILITIES), and for v0.4 graph statements over objects and entities. Accepts a relevance provider, a token estimator, and a context store.
  • clickHouseAdapter — minimal SQL mapping for count/group/funnel.
  • bigQueryAdapter — minimal SQL mapping for count/group/funnel.

Interface ​

Each adapter exposes:

  • describe()
  • setup() instructions
  • compile(query, context?)
  • optional run(query, context?)

context.tableMap binds logical sources (events, users, sessions) to physical tables.

Setup and limitations ​

CSV adapter ​

  • Requires context.demoEvents rows (events). Graph and object statements run through the evaluator functions and createObjectRuntime, not through csvAdapter.
  • Supports local sample/demo workflows.
  • Evaluator supports FROM events retrieve/aggregates/funnels against bundled fixtures.

Postgres adapter ​

  • Uses safe source binding and parameterized SQL.
  • Pair with CLI or your own postgres client execution path.

ClickHouse / BigQuery adapters ​

  • Provide minimal mapped SQL for v0.1 shapes.
  • String literals are escaped in generated SQL (single quote ' becomes '').
  • Adapters are compile-focused and currently return params: []; they do not emit prepared-statement placeholders.
  • This is a different safety contract than the Postgres reference compiler: safety here relies on escaping plus identifier checks, not bound-value placeholders.
  • Review generated SQL and adapt JSON/time semantics before production rollout.

Smoke coverage ​

See packages/adapters/test/adapters.test.ts.