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

{
  "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

{
  "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

Raw input schema

{
  "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"
}

Raw output schema

{
  "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"
}