> ## Documentation Index
> Fetch the complete documentation index at: https://superdoc-nick-sd-2070-add-content-controls-namespace-to-doc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# query.match

> Deterministic selector-based search with cardinality contracts for mutation targeting.

> Alpha: Document API is currently alpha and subject to breaking changes.

## Summary

Deterministic selector-based search with cardinality contracts for mutation targeting.

* 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                                 |                                                  |
| -------------- | ---------------------- | ------------------- | ------------------------------------------- | ------------------------------------------------ |
| `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`       | NodeAddress            | no                  | NodeAddress                                 |                                                  |

### Example request

```json theme={null}
{
  "require": "any",
  "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..."
    }
  ],
  "meta": {
    "effectiveResolved": true
  },
  "page": {
    "limit": 50,
    "offset": 0,
    "returned": 1
  },
  "total": 1
}
```

## Pre-apply throws

* `MATCH_NOT_FOUND`
* `AMBIGUOUS_MATCH`
* `INVALID_INPUT`
* `INTERNAL_ERROR`

## Non-applied failure codes

* None

## Raw schemas

<Accordion title="Raw input schema">
  ```json theme={null}
  {
    "additionalProperties": false,
    "properties": {
      "includeNodes": {
        "type": "boolean"
      },
      "limit": {
        "minimum": 1,
        "type": "integer"
      },
      "mode": {
        "enum": [
          "strict",
          "candidates"
        ]
      },
      "offset": {
        "minimum": 0,
        "type": "integer"
      },
      "require": {
        "enum": [
          "any",
          "first",
          "exactlyOne",
          "all"
        ]
      },
      "select": {
        "oneOf": [
          {
            "additionalProperties": false,
            "properties": {
              "caseSensitive": {
                "type": "boolean"
              },
              "mode": {
                "enum": [
                  "contains",
                  "regex"
                ]
              },
              "pattern": {
                "type": "string"
              },
              "type": {
                "const": "text"
              }
            },
            "required": [
              "type",
              "pattern"
            ],
            "type": "object"
          },
          {
            "additionalProperties": false,
            "properties": {
              "kind": {
                "enum": [
                  "block",
                  "inline"
                ]
              },
              "nodeType": {
                "enum": [
                  "paragraph",
                  "heading",
                  "listItem",
                  "table",
                  "tableRow",
                  "tableCell",
                  "tableOfContents",
                  "image",
                  "sdt",
                  "run",
                  "bookmark",
                  "comment",
                  "hyperlink",
                  "footnoteRef",
                  "tab",
                  "lineBreak"
                ]
              },
              "type": {
                "const": "node"
              }
            },
            "required": [
              "type"
            ],
            "type": "object"
          }
        ]
      },
      "within": {
        "$ref": "#/$defs/NodeAddress"
      }
    },
    "required": [
      "select"
    ],
    "type": "object"
  }
  ```
</Accordion>

<Accordion title="Raw output schema">
  ```json theme={null}
  {
    "additionalProperties": false,
    "properties": {
      "evaluatedRevision": {
        "type": "string"
      },
      "items": {
        "items": {
          "oneOf": [
            {
              "additionalProperties": false,
              "properties": {
                "address": {
                  "$ref": "#/$defs/NodeAddress"
                },
                "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"
                }
              },
              "required": [
                "id",
                "handle",
                "matchKind",
                "address",
                "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"
  }
  ```
</Accordion>