Skip to content

find.mdx

Latest commit

 

History

History
253 lines (231 loc) · 5.2 KB

find.mdx

File metadata and controls

253 lines (231 loc) · 5.2 KB
Raw
title find
sidebarTitle find
description Search the document for text or node matches using SDM/1 selectors. Returns discovery-grade results — for mutation targeting, use query.match instead.

{/* GENERATED FILE: DO NOT EDIT. Regenerate via pnpm run docapi:sync. */}

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

Summary

Search the document for text or node matches using SDM/1 selectors. Returns discovery-grade results — for mutation targeting, use query.match instead.

  • Operation ID: find
  • API member path: editor.doc.find(...)
  • Mutates document: no
  • Idempotency: idempotent
  • Supports tracked mode: no
  • Supports dry run: no
  • Deterministic target resolution: no

Expected result

Returns an SDFindResult envelope ({ total, limit, offset, items }). Each item is an SDNodeResult ({ node, address }).

Input fields

Field Type Required Description
in StoryLocator no StoryLocator
limit integer no
offset integer no
options object no
options.includeContext boolean no
options.includeProvenance boolean no
options.includeResolved boolean no
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
items object[] yes
limit integer yes
offset integer yes
total integer yes

Example response

{
  "items": [
    {
      "address": {
        "kind": "block",
        "nodeId": "node-def456",
        "nodeType": "paragraph"
      },
      "context": {},
      "node": {}
    }
  ],
  "limit": 50,
  "offset": 0,
  "total": 1
}

Pre-apply throws

  • CAPABILITY_UNAVAILABLE
  • INVALID_INPUT
  • ADDRESS_STALE
  • STORY_NOT_FOUND
  • STORY_MISMATCH
  • STORY_NOT_SUPPORTED
  • CROSS_STORY_PLAN
  • MATERIALIZATION_FAILED

Non-applied failure codes

  • None

Raw schemas

```json { "additionalProperties": false, "properties": { "in": { "$ref": "#/$defs/StoryLocator" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "options": { "additionalProperties": false, "properties": { "includeContext": { "type": "boolean" }, "includeProvenance": { "type": "boolean" }, "includeResolved": { "type": "boolean" } }, "type": "object" }, "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": { "type": "string" }, "type": { "const": "node" } }, "required": [ "type" ], "type": "object" } ] }, "within": { "$ref": "#/$defs/BlockNodeAddress" } }, "required": [ "select" ], "type": "object" } ``` ```json { "additionalProperties": false, "properties": { "items": { "items": { "additionalProperties": false, "properties": { "address": { "$ref": "#/$defs/NodeAddress" }, "context": { "type": "object" }, "node": { "type": "object" } }, "required": [ "node", "address" ], "type": "object" }, "type": "array" }, "limit": { "minimum": 0, "type": "integer" }, "offset": { "minimum": 0, "type": "integer" }, "total": { "minimum": 0, "type": "integer" } }, "required": [ "total", "limit", "offset", "items" ], "type": "object" } ```