SemQL query language

SemQL is the query language for expressing subscriptions and searches over Semantik. Queries describe geometric regions in embedding space rather than named topics: a subscriber receives messages whose meaning falls inside the declared region, regardless of what words were used to say it. SemQL has two equivalent, losslessly interconvertible representations:

Text syntax — SQL-like, human-readable
JSON wire format — canonical format used by the Noetive API

Either format can be submitted to the broker. The JSON serializer always emits ISO 8601 durations.

Query structure

A query has one required clause and three optional modifiers:

MATCH <expression>
[ NAMESPACE <namespace_selector> ]
[ WINDOW <duration> ]
[ LIMIT <integer> ]

Clauses

DISTANCE

Nearest-neighbor sphere in embedding space. Matches messages whose embedding is at least as similar to the anchor as the within floor you set.

MATCH DISTANCE("payment reconciliation failure") WITHIN 0.8
NAMESPACE "org:acme-corp"
LIMIT 20

{
  "match": {
    "distance": { "anchor": "payment reconciliation failure", "within": 0.8 }
  },
  "namespace": { "include": ["org:acme-corp"] },
  "limit": 20
}

Field	Type	Required	Default	Description
`anchor`	string \| float[]	yes	—	Center point — natural language text or raw embedding vector
`within`	number	no	—	Minimum cosine similarity (0.0–1.0); 0 means no floor
`top_k`	integer	no	—	Return top-k nearest neighbors, 1–1000. Search only; `/v1/subscribe` rejects it
`metric`	string	no	`"cosine"`	Distance metric: `"cosine"`, `"euclidean"`, or `"dot"`. JSON only; the text syntax has no equivalent keyword

within is a similarity floor, not a distance ceiling. A message matches when its similarity to the anchor is at least within, so a higher value is stricter. WITHIN 0.9 is near-exact; WITHIN 0.3 lets almost everything through. Values above 1.0 are rejected.

Provide either within or top_k. If neither is set, the clause acts as a scoring signal without a hard threshold.

DIRECTION

Cone search in embedding space. Matches messages aligned with one or more concept directions, regardless of distance from the origin.

MATCH DIRECTION(["customer frustration", "billing complaint"]) CONE 0.4
NAMESPACE "org:acme-corp"

{
  "match": {
    "direction": {
      "toward": ["customer frustration", "billing complaint"],
      "cone": 0.4
    }
  },
  "namespace": { "include": ["org:acme-corp"] }
}

Field	Type	Required	Default	Description
`toward`	string \| string[]	yes	—	Direction concept(s) — the broker embeds and averages multiple values
`cone`	number	no	`0.3`	Half-angle in radians

When toward is an array, the direction vector is the normalized mean of all embedded concepts.

CONTRAST

Attract/repel vector arithmetic. Matches messages semantically close to the attract concepts and far from the repel concepts.

MATCH CONTRAST(
  ATTRACT ["enterprise", "high-value account"],
  REPEL   ["self-serve", "free tier"]
)
WITHIN 0.7
NAMESPACE "org:acme-corp"

{
  "match": {
    "contrast": {
      "attract": ["enterprise", "high-value account"],
      "repel": ["self-serve", "free tier"],
      "within": 0.7
    }
  },
  "namespace": { "include": ["org:acme-corp"] }
}

Field	Type	Required	Default	Description
`attract`	string[]	yes	—	Concepts to attract toward
`repel`	string[]	no	—	Concepts to repel from
`within`	number	no	—	Minimum cosine similarity to the composite vector (0.0–1.0); 0 means no floor

The composite vector is normalize(mean(embed(attract)) − mean(embed(repel))). With repel absent it is normalize(mean(embed(attract))).

Boolean composition

Combine clauses with AND, OR, and NOT. Use parentheses to control precedence.

MATCH DIRECTION("payment gateway") CONE 0.3
  AND DISTANCE("timeout error") WITHIN 0.8
NAMESPACE "org:acme-corp"

MATCH (
    DIRECTION("infrastructure") CONE 0.3
  AND DISTANCE("connection failure") WITHIN 0.8
)
OR (
    DIRECTION("database") CONE 0.3
  AND CONTRAST(
      ATTRACT ["connection pool", "resource exhaustion"],
      REPEL   ["query optimization"]
    )
)
NAMESPACE "org:acme-corp"

MATCH DIRECTION("infrastructure security") CONE 0.3
  AND NOT DISTANCE("routine monitoring") WITHIN 0.75

NOT narrows a result set but cannot say where to look, so a query whose top level is a bare NOT is rejected. Pair it with a positive clause, as above.

/v1/subscribe accepts a narrower query set than /v1/search: any use of TOP returns 400 invalid_request. TOP ranks a message against the others in a result set. A stream has no result set, since each message is scored on its own as it is published, so the clause has no meaning there and is refused rather than quietly ignored. Use WITHIN to set a score floor instead. The query is legal SemQL, so /v1/lint reports it as valid. This restriction belongs to the subscribe endpoint, not to the language. Subscribe also refuses a query that would match every message, since that delivers the namespace’s entire stream rather than a subscription. In practice a query that constrains nothing — an empty toward or attract list — is already rejected as invalid SemQL before it reaches that check.

Modifiers

NAMESPACE

Restates the namespace the query was written for, so the server can check it. Scope itself comes from the namespace field in the request body — that field is required, it is what your API key is authorized against, and there is no default to fall back on. See Namespaces. NAMESPACE does not change where a query runs; it declares where the query expects to run, and the request is refused with 400 invalid_request if the two disagree. That is worth having when a query outlives the call site: a query stored in a config file, generated by an agent, or copied between environments carries its intended namespace with it, and sending it against the wrong one fails immediately instead of quietly answering from somewhere else. Namespace names match exactly — wildcards are not supported.

NAMESPACE "org:acme-corp"   -- asserts the request names org:acme-corp
NAMESPACE GLOBAL            -- asserts the request names the global namespace

{
  "include": ["org:acme-corp"]
}

Selecting several namespaces is not supported yet. Multiple names, NOT exclusions and ALL are valid SemQL, so /v1/lint parses them, but /v1/search and /v1/subscribe reject them with 400 invalid_request. They are refused rather than ignored: a clause written to exclude a namespace must never return the messages it was meant to leave out.To search several namespaces today, issue one request per namespace and merge the results yourself. Note that each namespace pins its own embedding model and dimensionality, so scores are only comparable across namespaces configured identically.

WINDOW

Restricts results to messages published within a time window ending now.

WINDOW 7d
WINDOW 48h
WINDOW 30m

JSON form uses ISO 8601 durations: "P7D", "PT48H", "PT30M".

LIMIT

Caps the number of results returned. Defaults to 100 when omitted, and is clamped to a maximum of 1000. A larger value succeeds and returns 1000 rather than failing. See Limits.

LIMIT 100

Anchors

An anchor is the reference point for a clause. Two forms are accepted: Natural language string — the broker embeds it automatically:

DISTANCE("payment reconciliation failure")

Raw float vector — skip embedding, use the vector directly:

DISTANCE([0.182, -0.041, 0.389, 0.057])

A query carries at most 32 anchors in total, and at most 8 anchors in a single list — the toward list of a DIRECTION clause, or either list of a CONTRAST clause. Anchor text across the whole query is capped at 4 KB, and vector anchors at 8192 floats. Over any of these, the query is rejected before anything is embedded. Full table in Limits.

Duration format

Text syntax	JSON (ISO 8601)
`30s`	`"PT30S"`
`15m`	`"PT15M"`
`24h`	`"PT24H"`
`7d`	`"P7D"`
`4w`	`"P28D"`

The text parser accepts both formats. The JSON serializer always emits ISO 8601.

Full examples

MATCH DIRECTION(["sovereign debt concern", "emerging market stress"]) CONE 0.4
  AND CONTRAST(
        ATTRACT ["credit spreads", "bond yields"],
        REPEL   ["routine monetary policy", "scheduled rate decision"]
      )
NAMESPACE "org:hedgefund"

{
  "match": {
    "and": [
      {
        "direction": {
          "toward": ["sovereign debt concern", "emerging market stress"],
          "cone": 0.4
        }
      },
      {
        "contrast": {
          "attract": ["credit spreads", "bond yields"],
          "repel": ["routine monetary policy", "scheduled rate decision"]
        }
      }
    ]
  },
  "namespace": { "include": ["org:hedgefund"] }
}

MATCH DIRECTION(["unmet need", "product frustration"]) CONE 0.4
  AND CONTRAST(
        ATTRACT ["home kitchen", "small appliance"],
        REPEL   ["professional equipment", "commercial grade"]
      )
NAMESPACE "org:retailco-eu"
WINDOW 30d

{
  "match": {
    "and": [
      {
        "direction": {
          "toward": ["unmet need", "product frustration"],
          "cone": 0.4
        }
      },
      {
        "contrast": {
          "attract": ["home kitchen", "small appliance"],
          "repel": ["professional equipment", "commercial grade"]
        }
      }
    ]
  },
  "namespace": { "include": ["org:retailco-eu"] },
  "window": "P30D"
}

Reserved words

MATCH AND OR NOT DISTANCE DIRECTION CONTRAST ATTRACT REPEL
WITHIN TOP CONE WINDOW NAMESPACE ALL GLOBAL LIMIT

Reserved words are case-insensitive in text syntax. JSON uses lowercase keys exclusively.

Grammar reference

EBNF grammar

query            = match_clause
                   [ namespace_clause ]
                   [ window_clause ]
                   [ limit_clause ] ;

match_clause     = "MATCH" expression ;

expression       = term { "OR" term } ;
term             = factor { "AND" factor } ;
factor           = [ "NOT" ] atom ;
atom             = clause | "(" expression ")" ;

clause           = distance_clause
                 | direction_clause
                 | contrast_clause ;

distance_clause  = "DISTANCE" "(" anchor ")" [ distance_opts ] ;
distance_opts    = "WITHIN" number | "TOP" integer ;

direction_clause = "DIRECTION" "(" anchor_list ")" [ direction_opts ] ;
direction_opts   = "CONE" number ;

contrast_clause  = "CONTRAST" "("
                     "ATTRACT" anchor_list ","
                     "REPEL"   anchor_list
                   ")" [ "WITHIN" number ] ;

(* The plural forms below parse but are rejected by /v1/search and
   /v1/subscribe — see the NAMESPACE modifier above. *)
namespace_clause  = "NAMESPACE" namespace_selector ;
namespace_selector = namespace_item { "," namespace_item } ;
namespace_item    = namespace_ref | "ALL" | "GLOBAL" ;
namespace_ref     = [ "NOT" ] string_literal ;

window_clause     = "WINDOW" duration ;
limit_clause      = "LIMIT" integer ;

anchor            = string_literal | vector_literal ;
anchor_list       = "[" anchor { "," anchor } "]" | anchor ;
vector_literal    = "[" number { "," number } "]" ;
string_literal    = '"' { character } '"' ;
duration          = integer time_unit ;
time_unit         = "s" | "m" | "h" | "d" | "w" ;
number            = float | integer ;

Getting started

Guides

SemQL

Reference

Dashboard

MCP

Skills

SemQL query language

Query structure

Clauses

DISTANCE

DIRECTION

CONTRAST

Boolean composition

Modifiers

NAMESPACE

WINDOW

LIMIT

Anchors

Duration format

Full examples

Reserved words

Grammar reference

​Query structure

​Clauses

​DISTANCE

​DIRECTION

​CONTRAST

​Boolean composition

​What subscribe rejects

​Modifiers

​NAMESPACE

​WINDOW

​LIMIT

​Anchors

​Duration format

​Full examples

​Reserved words

​Grammar reference

Query structure

Clauses

DISTANCE

DIRECTION

CONTRAST

Boolean composition

What subscribe rejects

Modifiers

NAMESPACE

WINDOW

LIMIT

Anchors

Duration format

Full examples

Reserved words

Grammar reference