> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noetive.io/llms.txt
> Use this file to discover all available pages before exploring further.

# SemQL query language

> Geometric predicate language for querying Semantik in high-dimensional embedding space.

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:

```sql theme={null}
MATCH <expression>
[ PARTITION <partition_selector> ]
[ WINDOW <duration> ]
[ LIMIT <integer> ]
```

## Clauses

### DISTANCE

Nearest-neighbor sphere in embedding space. Matches messages whose embedding falls within a given cosine distance of the anchor.

<CodeGroup>
  ```sql SemQL theme={null}
  MATCH DISTANCE("payment reconciliation failure") WITHIN 0.3
  PARTITION "org:acme-corp"
  LIMIT 20
  ```

  ```json JSON theme={null}
  {
    "match": {
      "distance": { "anchor": "payment reconciliation failure", "within": 0.3 }
    },
    "partition": { "include": ["org:acme-corp"] },
    "limit": 20
  }
  ```
</CodeGroup>

| Field    | Type               | Required | Default    | Description                                                  |
| -------- | ------------------ | -------- | ---------- | ------------------------------------------------------------ |
| `anchor` | string \| float\[] | yes      | —          | Center point — natural language text or raw embedding vector |
| `within` | number             | no       | —          | Maximum cosine distance (0.0–2.0)                            |
| `top_k`  | integer            | no       | —          | Return top-k nearest neighbors                               |
| `metric` | string             | no       | `"cosine"` | Distance metric: `"cosine"`, `"euclidean"`, or `"dot"`       |

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.

<CodeGroup>
  ```sql SemQL theme={null}
  MATCH DIRECTION(["customer frustration", "billing complaint"]) CONE 0.4
  PARTITION "org:acme-corp"
  ```

  ```json JSON theme={null}
  {
    "match": {
      "direction": {
        "toward": ["customer frustration", "billing complaint"],
        "cone": 0.4
      }
    },
    "partition": { "include": ["org:acme-corp"] }
  }
  ```
</CodeGroup>

| 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.

<CodeGroup>
  ```sql SemQL theme={null}
  MATCH CONTRAST(
    ATTRACT ["enterprise", "high-value account"],
    REPEL   ["self-serve", "free tier"]
  )
  WITHIN 0.4
  PARTITION "org:acme-corp"
  ```

  ```json JSON theme={null}
  {
    "match": {
      "contrast": {
        "attract": ["enterprise", "high-value account"],
        "repel": ["self-serve", "free tier"],
        "within": 0.4
      }
    },
    "partition": { "include": ["org:acme-corp"] }
  }
  ```
</CodeGroup>

| Field     | Type      | Required | Default | Description                            |
| --------- | --------- | -------- | ------- | -------------------------------------- |
| `attract` | string\[] | yes      | —       | Concepts to attract toward             |
| `repel`   | string\[] | yes      | —       | Concepts to repel from                 |
| `within`  | number    | no       | —       | Max distance from the composite vector |

The composite vector is `normalize(mean(embed(attract)) − mean(embed(repel)))`.

***

## Boolean composition

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

```sql theme={null}
MATCH DIRECTION("payment gateway") CONE 0.3
  AND DISTANCE("timeout error") WITHIN 0.2
PARTITION "org:acme-corp"
```

```sql theme={null}
MATCH (
    DIRECTION("infrastructure") CONE 0.3
  AND DISTANCE("connection failure") WITHIN 0.2
)
OR (
    DIRECTION("database") CONE 0.3
  AND CONTRAST(
      ATTRACT ["connection pool", "resource exhaustion"],
      REPEL   ["query optimization"]
    )
)
PARTITION "org:acme-corp"
```

```sql theme={null}
MATCH DIRECTION("infrastructure security") CONE 0.3
  AND NOT DISTANCE("routine monitoring") WITHIN 0.2
```

***

## Modifiers

### PARTITION

Scopes the query to one or more namespaces. Without a `PARTITION` clause, the query searches the default namespace only.

<CodeGroup>
  ```sql SemQL theme={null}
  PARTITION "org:acme-corp"                         -- single namespace
  PARTITION "org:acme-corp", "org:acme-staging"     -- multiple
  PARTITION "org:acme-*"                            -- glob pattern
  PARTITION "org:acme-*", NOT "org:acme-internal"   -- exclusion
  PARTITION ALL                                     -- all accessible namespaces
  PARTITION GLOBAL                                  -- global shared namespace
  ```

  ```json JSON theme={null}
  {
    "include": ["org:acme-corp", "org:acme-*"],
    "exclude": ["org:acme-internal"],
    "global": true
  }
  ```
</CodeGroup>

### WINDOW

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

```sql theme={null}
WINDOW 7d
WINDOW 48h
WINDOW 30m
```

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

### LIMIT

Caps the number of results returned.

```sql theme={null}
LIMIT 100
```

***

## Anchors

An anchor is the reference point for a clause. Two forms are accepted:

**Natural language string** — the broker embeds it automatically:

```sql theme={null}
DISTANCE("payment reconciliation failure")
```

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

```sql theme={null}
DISTANCE([0.182, -0.041, 0.389, 0.057])
```

***

## 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

<CodeGroup>
  ```sql Finance: risk signal detection (text) theme={null}
  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"]
        )
  PARTITION "org:hedgefund", GLOBAL
  ```

  ```json Finance: risk signal detection (JSON) theme={null}
  {
    "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"]
          }
        }
      ]
    },
    "partition": { "include": ["org:hedgefund"], "global": true }
  }
  ```
</CodeGroup>

<CodeGroup>
  ```sql Retail: demand signal (text) theme={null}
  MATCH DIRECTION(["unmet need", "product frustration"]) CONE 0.4
    AND CONTRAST(
          ATTRACT ["home kitchen", "small appliance"],
          REPEL   ["professional equipment", "commercial grade"]
        )
  PARTITION "org:retailco-*", NOT "org:retailco-internal"
  WINDOW 30d
  ```

  ```json Retail: demand signal (JSON) theme={null}
  {
    "match": {
      "and": [
        {
          "direction": {
            "toward": ["unmet need", "product frustration"],
            "cone": 0.4
          }
        },
        {
          "contrast": {
            "attract": ["home kitchen", "small appliance"],
            "repel": ["professional equipment", "commercial grade"]
          }
        }
      ]
    },
    "partition": {
      "include": ["org:retailco-*"],
      "exclude": ["org:retailco-internal"]
    },
    "window": "P30D"
  }
  ```
</CodeGroup>

***

## Reserved words

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

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

***

## Grammar reference

<Accordion title="EBNF grammar">
  ```ebnf theme={null}
  query            = match_clause
                     [ partition_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 ] ;

  partition_clause  = "PARTITION" partition_selector ;
  partition_selector = partition_ref { "," partition_ref }
                     | "ALL"
                     | "GLOBAL" ;
  partition_ref     = [ "NOT" ] ( string_literal | glob_pattern ) ;

  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 } '"' ;
  glob_pattern      = string_literal ;
  duration          = integer time_unit ;
  time_unit         = "s" | "m" | "h" | "d" | "w" ;
  number            = float | integer ;
  ```
</Accordion>