> ## Documentation Index
> Fetch the complete documentation index at: https://superdoc-caio-pizzol-docs-ai-core-preset.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# query.match
> Deterministic selector-based search returning mutation-grade addresses and text ranges. Use this to discover targets before any mutation.
## Summary
Deterministic selector-based search returning mutation-grade addresses and text ranges. Use this to discover targets before any mutation.
* Operation ID: `query.match`
* API member path: `editor.doc.query.match(...)`
* Mutates document: `no`
* Idempotency: `idempotent`
* Supports tracked mode: `no`
* Supports dry run: `no`
* Deterministic target resolution: `yes`
## Expected result
Returns a QueryMatchOutput with the resolved target address and cardinality metadata.
## Input fields
| Field | Type | Required | Description |
| ----------------- | ------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------- |
| `in` | StoryLocator | no | StoryLocator |
| `includeNodes` | boolean | no | |
| `limit` | integer | no | |
| `mode` | enum | no | `"strict"`, `"candidates"` |
| `offset` | integer | no | |
| `require` | enum | no | `"any"`, `"first"`, `"exactlyOne"`, `"all"` |
| `select` | object(type="text") \| object(type="node") | yes | One of: object(type="text"), object(type="node") |
| `within` | BlockNodeAddress | no | BlockNodeAddress |
| `within.kind` | `"block"` | no | Constant: `"block"` |
| `within.nodeId` | string | no | |
| `within.nodeType` | enum | no | `"paragraph"`, `"heading"`, `"listItem"`, `"table"`, `"tableRow"`, `"tableCell"`, `"tableOfContents"`, `"image"`, `"sdt"` |
### Example request
```json theme={null}
{
"in": {
"kind": "story",
"storyType": "body"
},
"select": {
"caseSensitive": true,
"mode": "contains",
"pattern": "hello world",
"type": "text"
},
"within": {
"kind": "block",
"nodeId": "node-def456",
"nodeType": "paragraph"
}
}
```
## Output fields
| Field | Type | Required | Description |
| ------------------------ | ------------------------------------------------------- | -------- | ----------- |
| `evaluatedRevision` | string | yes | |
| `items` | object(matchKind="text") \| object(matchKind="node")\[] | yes | |
| `meta` | object | yes | |
| `meta.effectiveResolved` | boolean | yes | |
| `page` | PageInfo | yes | PageInfo |
| `page.limit` | integer | yes | |
| `page.offset` | integer | yes | |
| `page.returned` | integer | yes | |
| `total` | integer | yes | |
### Example response
```json theme={null}
{
"evaluatedRevision": "rev-001",
"items": [
{
"address": {
"kind": "block",
"nodeId": "node-def456",
"nodeType": "paragraph"
},
"blocks": [
{
"blockId": "block-abc123",
"nodeType": "paragraph",
"paragraphStyle": {
"isListItem": true,
"styleId": "style-001"
},
"range": {
"end": 10,
"start": 0
},
"ref": "handle:abc123",
"runs": [
{
"range": {
"end": 10,
"start": 0
},
"ref": "handle:abc123",
"styleId": "style-001",
"styles": {
"color": "example",
"direct": {
"bold": "on",
"italic": "on",
"strike": "on",
"underline": "on"
},
"effective": {
"bold": true,
"italic": true,
"strike": true,
"underline": true
},
"highlight": "example"
},
"text": "Hello, world."
}
],
"text": "Hello, world."
}
],
"handle": {
"ref": "handle:abc123",
"refStability": "stable",
"targetKind": "text"
},
"highlightRange": {
"end": 10,
"start": 0
},
"id": "id-001",
"matchKind": "text",
"snippet": "...the quick brown fox...",
"target": {
"end": {
"blockId": "block-abc123",
"kind": "text",
"offset": 0
},
"kind": "selection",
"start": {
"blockId": "block-abc123",
"kind": "text",
"offset": 0
}
}
}
],
"meta": {
"effectiveResolved": true
},
"page": {
"limit": 50,
"offset": 0,
"returned": 1
},
"total": 1
}
```
## Pre-apply throws
* `MATCH_NOT_FOUND`
* `AMBIGUOUS_MATCH`
* `INVALID_INPUT`
* `INTERNAL_ERROR`
* `STORY_NOT_FOUND`
* `STORY_MISMATCH`
* `STORY_NOT_SUPPORTED`
* `CROSS_STORY_PLAN`
* `MATERIALIZATION_FAILED`
## Non-applied failure codes
* None
## Raw schemas
```json theme={null}
{
"additionalProperties": false,
"properties": {
"in": {
"$ref": "#/$defs/StoryLocator"
},
"includeNodes": {
"description": "When true, includes full node data in results. Default: false.",
"type": "boolean"
},
"limit": {
"description": "Maximum number of matches to return.",
"minimum": 1,
"type": "integer"
},
"mode": {
"description": "Search mode: 'strict' (default, exact matching) or 'candidates' (returns scored potential matches).",
"enum": [
"strict",
"candidates"
]
},
"offset": {
"description": "Number of matches to skip for pagination.",
"minimum": 0,
"type": "integer"
},
"require": {
"description": "Match cardinality: 'any' (all matches), 'first' (only first), 'exactlyOne' (fail if != 1), 'all' (fail if 0).",
"enum": [
"any",
"first",
"exactlyOne",
"all"
]
},
"select": {
"description": "Search selector. Use {type:'text', pattern:'...'} for text search or {type:'node', nodeType:'paragraph'|'heading'|...} for node search.",
"oneOf": [
{
"additionalProperties": false,
"properties": {
"caseSensitive": {
"description": "Case-sensitive matching. Default: false.",
"type": "boolean"
},
"mode": {
"description": "Match mode: 'contains' (substring) or 'regex'.",
"enum": [
"contains",
"regex"
]
},
"pattern": {
"description": "Text or regex pattern to match.",
"type": "string"
},
"type": {
"const": "text",
"description": "Must be 'text' for text pattern search."
}
},
"required": [
"type",
"pattern"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"kind": {
"description": "Filter: 'block' or 'inline'.",
"enum": [
"block",
"inline"
]
},
"nodeType": {
"description": "Block type to match (paragraph, heading, table, listItem, etc.).",
"enum": [
"paragraph",
"heading",
"listItem",
"table",
"tableRow",
"tableCell",
"tableOfContents",
"image",
"sdt",
"run",
"bookmark",
"comment",
"hyperlink",
"footnoteRef",
"endnoteRef",
"crossRef",
"indexEntry",
"citation",
"authorityEntry",
"sequenceField",
"tab",
"lineBreak"
]
},
"type": {
"const": "node",
"description": "Must be 'node' for node type search."
}
},
"required": [
"type"
],
"type": "object"
}
]
},
"within": {
"$ref": "#/$defs/BlockNodeAddress",
"description": "Limit search scope to within a specific block: {kind:'block', nodeType:'...', nodeId:'...'}."
}
},
"required": [
"select"
],
"type": "object"
}
```
```json theme={null}
{
"additionalProperties": false,
"properties": {
"evaluatedRevision": {
"type": "string"
},
"items": {
"items": {
"oneOf": [
{
"additionalProperties": false,
"properties": {
"address": {
"$ref": "#/$defs/BlockNodeAddress"
},
"blocks": {
"items": {
"$ref": "#/$defs/MatchBlock"
},
"minItems": 1,
"type": "array"
},
"handle": {
"$ref": "#/$defs/ResolvedHandle"
},
"highlightRange": {
"$ref": "#/$defs/Range"
},
"id": {
"type": "string"
},
"matchKind": {
"const": "text"
},
"snippet": {
"type": "string"
},
"target": {
"$ref": "#/$defs/SelectionTarget"
}
},
"required": [
"id",
"handle",
"matchKind",
"address",
"target",
"snippet",
"highlightRange",
"blocks"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"address": {
"$ref": "#/$defs/NodeAddress"
},
"blocks": {
"items": {
"$ref": "#/$defs/MatchBlock"
},
"maxItems": 0,
"type": "array"
},
"handle": {
"$ref": "#/$defs/ResolvedHandle"
},
"id": {
"type": "string"
},
"matchKind": {
"const": "node"
}
},
"required": [
"id",
"handle",
"matchKind",
"address",
"blocks"
],
"type": "object"
}
]
},
"type": "array"
},
"meta": {
"additionalProperties": false,
"properties": {
"effectiveResolved": {
"type": "boolean"
}
},
"required": [
"effectiveResolved"
],
"type": "object"
},
"page": {
"$ref": "#/$defs/PageInfo"
},
"total": {
"minimum": 0,
"type": "integer"
}
},
"required": [
"evaluatedRevision",
"total",
"items",
"page",
"meta"
],
"type": "object"
}
```