SignalQL

Appearance

SignalQL v0.2 specification ​

SignalQL v0.2 defines a domain-agnostic language for retrieving and shaping structured evidence. Interpretation belongs to AI or higher application layers, not SignalQL itself.

Core principle ​

SignalQL retrieves evidence; it does not apply business opinion.

  • No domain-specific semantics in core grammar.
  • No action/mutation language.
  • No built-in labels like "blocked", "priority", or workflow states.

Core constructs ​

  • Entities: durable objects such as work_item, person, repo, thread.
  • Events: timestamped activity attached to entities and actors.
  • Relationships: traversable links between entities.
  • Signals: externally computed values exposed as queryable fields.
  • Probability fields: likelihood/confidence values from external models.

Grammar (EBNF) ​

ebnf
query              ::= retrieve_query | sequence_query

retrieve_query      ::= "FROM" source where_clause? traverse_clause? trend_clause? select_clause
source              ::= entity_source | event_source
entity_source       ::= "entity" "(" identifier ")"
event_source        ::= "events"

where_clause        ::= "WHERE" predicate_list
predicate_list      ::= predicate ( "AND" predicate )*
predicate           ::= field_path comparator value
comparator          ::= "=" | ">" | "<" | ">=" | "<="
field_path          ::= identifier ( "." identifier )*
                     | "signal" "(" identifier ")"
                     | "probability" "(" identifier ")"

traverse_clause     ::= "TRAVERSE" identifier "DEPTH" "<=" integer
trend_clause        ::= "TREND" trend_dir "OVER" integer time_unit
trend_dir           ::= "UP" | "DOWN" | "FLAT"
time_unit           ::= "d" | "h" | "w"

sequence_query      ::= "FIND" "sequence" "WHERE" sequence_steps "WITHIN" integer time_unit
sequence_steps      ::= sequence_step ( "->" sequence_step )+
sequence_step       ::= identifier | string_literal

select_clause       ::= "RETURN" return_field ( "," return_field )*
return_field        ::= field_path | "count" | "entity_id" | "timestamp"

identifier          ::= [a-zA-Z_] [a-zA-Z0-9_]*
integer             ::= [0-9]+
value               ::= string_literal | integer | decimal
string_literal      ::= '"' { character } '"'
decimal             ::= [0-9]+ "." [0-9]+

Execution model ​

  1. Parse SignalQL to AST and reject unknown constructs.
  2. Bind references to source metadata (entities/events/relationships/signal catalog).
  3. Build deterministic execution plan (traversal, filters, sequence windows, return fields).
  4. Execute retrieval path in adapter/runtime.
  5. Return structured evidence + execution metadata.

SignalQL does not score, classify, prioritize, or decide outcomes.

Determinism contract ​

  • Canonical formatting produces stable clause ordering.
  • Equivalent AST input yields equivalent execution plan output.
  • Output includes machine-readable metadata for explainability.

Example queries ​

Entity retrieval with derived signal

signalql
FROM entity(work_item)
WHERE signal(risk_score) > 0.7 AND probability(delay) > 0.6
RETURN entity_id, signal(risk_score), probability(delay)

Graph traversal

signalql
FROM entity(work_item)
TRAVERSE depends_on DEPTH <= 2
RETURN entity_id, count

Sequence pattern

signalql
FIND sequence
WHERE pr_opened -> no_activity -> stale
WITHIN 3d

Temporal trend

signalql
FROM entity(repo)
TREND DOWN OVER 5d
RETURN entity_id, count

Non-goals ​

  • No domain nouns (sprint, epic, story_points, workflow_status) in core grammar.
  • No mutating commands (ASSIGN, EXECUTE, UPDATE, DELETE).
  • No embedded business policy interpretation.

Normative references ​