> ## Documentation Index
> Fetch the complete documentation index at: https://developer.kodexa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Locate

> Use kdx document locate to find nodes with character match positions, designed for agent workflows that need precise tagging and data linking.

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

```bash theme={null}
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

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

```json theme={null}
{"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

```bash theme={null}
kdx document locate report.kddb --pattern "revenue" --page 5 --pretty
```

```json theme={null}
{
  "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

```bash theme={null}
# 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"
```

<Tip>
  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.
</Tip>

<Tip>
  Filter by `--type word` for precise single-token matches, or `--type line` for broader context.
</Tip>