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

# Json Path

> Extract data using JSONPath expressions

The Json Path command (Command Type: 1002) enables you to extract specific data from JSON structures using JSONPath expressions. This command is essential for querying and extracting data from complex JSON objects and arrays.

## Overview

The Json Path command provides functionality for:

* Extracting data using JSONPath query expressions
* Querying nested JSON structures
* Extracting arrays and individual elements
* Recursive searching through JSON data
* Mapping extracted data to output keys

## Command Type

**Command Type ID:** 1002

## Parameters

| Parameter    | Type   | Description                                       | Required |
| ------------ | ------ | ------------------------------------------------- | -------- |
| **jsonPath** | string | JSONPath expression for extraction                | Yes      |
| **input**    | string | Input data reference (e.g., `@{PREVIOUS_OUTPUT}`) | Yes      |
| **key**      | string | Key name for storing extracted result             | Yes      |
| **source**   | string | Source data key to query                          | No       |

## JSONPath Syntax

JSONPath is a query language for JSON data. Common patterns include:

### Basic Syntax

| Pattern               | Description                | Example              |
| --------------------- | -------------------------- | -------------------- |
| `$`                   | Root element               | `$`                  |
| `$.field`             | Access field at root       | `$.data`             |
| `$[*]`                | All array elements         | `$.items[*]`         |
| `$[0]`                | First array element        | `$.items[0]`         |
| `$[-1]`               | Last array element         | `$.items[-1]`        |
| `$.field[*].subfield` | Nested array access        | `$.data.items[*].id` |
| `$..field`            | Recursive search for field | `$..name`            |

### Common JSONPath Patterns

**Extract all IDs from items array:**

```json theme={null}
$.items[*].id
```

**Get first item:**

```json theme={null}
$[0]
```

**Nested access:**

```json theme={null}
$.data.events[*].id
```

**Recursive search for name field:**

```json theme={null}
$..name
```

**Extract specific array element:**

```json theme={null}
$.items[0].title
```

**Filter by condition:**

```json theme={null}
$.items[?(@.status == 'active')]
```

## Usage Examples

### Extract All IDs

```json theme={null}
{
  "command": "json-path",
  "params": {
    "jsonPath": "$.items[*].id",
    "input": "@{PREVIOUS_OUTPUT}",
    "key": "extracted_ids"
  }
}
```

### Extract First Item

```json theme={null}
{
  "command": "json-path",
  "params": {
    "jsonPath": "$[0]",
    "input": "@{PREVIOUS_OUTPUT}",
    "key": "first_item"
  }
}
```

### Nested Array Access

```json theme={null}
{
  "command": "json-path",
  "params": {
    "jsonPath": "$.data.events[*].id",
    "input": "@{PREVIOUS_OUTPUT}",
    "key": "event_ids"
  }
}
```

### Recursive Search

```json theme={null}
{
  "command": "json-path",
  "params": {
    "jsonPath": "$..name",
    "input": "@{PREVIOUS_OUTPUT}",
    "key": "all_names"
  }
}
```

### Extract from Specific Source

```json theme={null}
{
  "command": "json-path",
  "params": {
    "jsonPath": "$.items[*].title",
    "input": "@{PREVIOUS_OUTPUT}",
    "source": "parsed_data",
    "key": "extracted_titles"
  }
}
```

## Variable Support

The Json Path command supports variable interpolation in:

* **Input**: Use `@{VARIABLE}` to reference previous command output
* **Source**: Reference specific data keys from previous commands

### Common Variable Patterns

* **Previous Output**: `@{PREVIOUS_OUTPUT}` - Output from previous command
* **Parsed Data**: Reference parsed JSON from JSON Parse command
* **Step Output**: `@{STEP_OUTPUT}` - Output from previous step

## Output Structure

The Json Path command stores extracted data under the specified key:

### Single Value Output

```json theme={null}
{
  "extracted_ids": ["id1", "id2", "id3"]
}
```

### Object Output

```json theme={null}
{
  "first_item": {
    "id": "123",
    "name": "Example"
  }
}
```

### Using Extracted Data

Extracted data can be used by subsequent commands:

```json theme={null}
{
  "command": "object-mapper",
  "params": {
    "input": "@{PREVIOUS_OUTPUT}",
    "mapping": {
      "id": "$.extracted_ids[0]"
    }
  }
}
```

## Error Handling

The Json Path command handles various error scenarios:

* **Invalid JSONPath**: Returns error for malformed JSONPath expressions
* **Missing Data**: Handles cases where queried fields don't exist
* **Empty Results**: Returns empty array or null for queries with no matches

## Best Practices

* **Test JSONPath Queries**: Use the Test panel to validate JSONPath syntax
* **Verify Source Data Structure**: Check actual data structure before writing queries
* **Use Descriptive Keys**: Use clear, descriptive key names for extracted data
* **Handle Missing Data**: Account for missing fields or null values
* **Start Simple**: Begin with simple queries and build complexity gradually
* **Document Queries**: Document complex JSONPath expressions for maintainability

## Common Use Cases

* **API Response Parsing**: Extract specific fields from API responses
* **Data Extraction**: Extract data from nested JSON structures
* **Array Processing**: Extract arrays for iteration
* **Field Mapping**: Map specific fields to output structure

## Related Commands

* [JSON Parse](/stream/commands/parse/json-parse) - Parse JSON before extraction
* [HTTP Request](/stream/commands/http/http-request) - Fetch JSON data to extract
* [Object Mapper](/stream/commands/parse/object-mapper) - Transform extracted data

## Troubleshooting

### JSONPath Queries Not Working

If JSONPath queries return no results:

1. **Verify Source Data**: Check the actual structure of source data using the Test panel
2. **Test Syntax**: Validate JSONPath syntax matches the data structure
3. **Check Source Selection**: Ensure the correct source is selected
4. **Review Query Examples**: Start with simpler queries and build complexity

### Common Issues

* **Incorrect JSONPath Syntax**: Verify syntax matches JSONPath specification
* **Data Structure Mismatch**: Ensure query matches actual data structure
* **Missing Fields**: Handle cases where expected fields may not exist
* **Null Values**: Account for null or undefined values in data

### Testing JSONPath Queries

Use the Test panel to:

* View actual data structure
* Test JSONPath queries interactively
* Verify query results before deployment
* Debug query issues