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.
