Locate

Search for text patterns and return matching nodes with character positions and matched text. Designed for agent workflows that need to identify exactly which nodes to tag or link to data attributes.

Usage

kdx document locate <file.kddb> --pattern <regex> [flags]

Flags

Flag	Description	Default
`--pattern`	Regex pattern to search for (required)
`--type`	Comma-separated node types to match (e.g., word,line)	All types
`--page N`	Filter to page number (1-based)	All pages
`--max N`	Maximum number of results	0 (unlimited)
`--pretty`	Pretty-print JSON output	false

Output Fields

Field	Description
`nodeId`	Node ID for use with `tag` command
`type`	Node type (word, line, etc.)
`content`	Full node content
`page`	Page number (1-based)
`matchStart`	Character offset where match begins
`matchEnd`	Character offset where match ends
`matchText`	The actual matched text
`bbox`	Bounding box coordinates (if available)

Examples

Locate Words Matching a Pattern

kdx document locate invoice.kddb --pattern "\\$[\\d,]+\\.\\d{2}" --type word --max 5

{"nodeId":245,"type":"word","content":"$1,234.56","page":1,"matchStart":0,"matchEnd":9,"matchText":"$1,234.56"}
{"nodeId":302,"type":"word","content":"$500.00","page":1,"matchStart":0,"matchEnd":7,"matchText":"$500.00"}

Locate on a Specific Page

kdx document locate report.kddb --pattern "revenue" --page 5 --pretty

{
  "nodeId": 1042,
  "type": "line",
  "content": "Total revenue for fiscal year 2024",
  "page": 5,
  "matchStart": 6,
  "matchEnd": 13,
  "matchText": "revenue",
  "bbox": {"x1": 72.0, "y1": 340.2, "x2": 540.0, "y2": 352.8}
}

Agent Workflow: Locate then Tag

# Step 1: Find nodes containing amounts
kdx document locate invoice.kddb --pattern "\\$[\\d,]+" --type word

# Step 2: Tag a found node
kdx document tag invoice.kddb --node-id 245 --name "invoice/amount"

Use locate instead of grep when you need the nodeId for subsequent tag or data set-attribute operations. The matchText field confirms exactly what was matched.

Filter by --type word for precise single-token matches, or --type line for broader context.

Getting Started

Core Operations

Sync & GitOps

Operational Commands

Document Commands

Usage

Flags

Output Fields

Examples

Locate Words Matching a Pattern

Locate on a Specific Page

Agent Workflow: Locate then Tag

​Usage

​Flags

​Output Fields

​Examples

​Locate Words Matching a Pattern

​Locate on a Specific Page

​Agent Workflow: Locate then Tag

Usage

Flags

Output Fields

Examples

Locate Words Matching a Pattern

Locate on a Specific Page

Agent Workflow: Locate then Tag