> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/xql-command-reference-guide/readme/functions/xql-json-functions-reference.md).

# XQL JSON Functions Reference

***

## Core Concept: When the four standard extraction functions are not enough

The four standard extraction functions, `json_extract()`, `json_extract_scalar()`, `json_extract_array()`, and `json_extract_scalar_array()`, each resolve **one fully-qualified path** to **one** location in a JSON document. They cannot search by key name, they cannot match conditionally, and they cannot collect multiple results.

The `json_path_extract()` function runs a **full JSONPath engine** over the document and returns **every** node that matches:

* **`json_extract()`** : Use when extracting a JSON **object** at a known path.
* **`json_extract_scalar()`** : Use when extracting a **primitive value** at a known path, especially for `filter` comparisons.
* **`json_extract_array()`** : Use when extracting a **JSON array** at a known path.
* **`json_extract_scalar_array()`** : Use when extracting a **JSON array of primitives** at a known path.
* **`json_path_extract()`** : Use when standard dot-notation or simple array indexing is **insufficient**: recursive descent (`$..key`), wildcards (`$.a[*].b`), filter expressions (`$..*[?(@.priority==22.99)]`), script expressions (`[(@.length-1)]`), slices (`[-1:]`, `[:2]`), and index unions (`[0,1]`). Available in search queries only, and subject to the limitations listed below.

***

## json\_path\_extract()

The `json_path_extract()` function retrieves values from a JSON string based on a specified JSONPath expression. The `json_path_extract()` function walks the entire document and returns a string representation of every matching node.

The `json_path_extract()` function implements the original Goessner JSONPath specification. Behavior may differ from other JSONPath implementations, the limitations documented on this page take precedence.

> **Constraint:** This function performs a **"very heavy" operation** and requires significant resources to run. Use the `json_path_extract()` function only when standard dot-notation or simple array indexing is insufficient for your data extraction needs.

> **Constraint:** JSON field names are **case-sensitive**. The key-to-field pairing in the XQL query must be identical to the JSON structure for results to be found. When no node matches, the function returns the **string** `false`, not `null` and not an empty value. See [No Matches Found](#no-matches-found).

> **Constraint:** The `<json_path>` must begin with the literal prefix `$.`. Paths such as `$['key']`, `$[0]`, or a bare `$` are rejected with `Json path must start with '$.'`.

> **Constraint:** This function is available in **search queries only**. It is not supported in ingestion rules (XIFs), streaming/correlation rules, or dataset SBAC expressions.

### Canonical Syntax

**Regular Syntax:**

The `<json_path>` must be enclosed in double quotes, and the root of the JSON object is represented by a dollar sign (`$`).

```xql
json_path_extract(field_name, "$.<json_path>")
```

**Special characters syntax:**

When a field name within the `<json_path>` contains a special character such as a colon (`:`), enclose the field name in **single quotes within brackets**:

```xql
json_path_extract(field_name, "$.['field_name']")
```

> **Important:** Bracket notation performs a **recursive descent**, not a direct child access. `$.['UserName']` matches a `UserName` key at *any* depth, not only at the root.

> **Limitation:** Keys containing a **dot** (`.`) cannot be addressed. In `$.['key.name']` the inner dot is interpreted as a path separator, so the expression searches for a key `key` containing a child `name`. A key literally named `key.name` is unreachable and the function returns `false`. Rename the key at ingestion time if you need to query it.

### Parameters

| Name         | Type     | Required | Description                                                              |
| ------------ | -------- | -------- | ------------------------------------------------------------------------ |
| `field_name` | `string` | Yes      | The source field or expression containing a valid JSON-formatted string. |
| `json_path`  | `string` | Yes      | The JSONPath expression identifying the data to extract.                 |

### Return Value

The `json_path_extract()` function returns a **string representation of the extracted JSON data**.

* **Scalar matches** → The `json_path_extract()` function returns them collected in a JSON array (e.g., `["NRees","EWaugh","HMelville","JTolkien"]`)
* **Numeric matches** → The `json_path_extract()` function preserves the numeric type (e.g., `[8.95,12.99,8.99,22.99]`)
* **Object matches** → The `json_path_extract()` function returns the full objects (e.g., `[{"UserName":"jdow","Role":"Admin"}]`)
* **Array matches** → The `json_path_extract()` function returns them nested inside the result (e.g., `[[{...},{...}],{...}]`)
* **A single match is still wrapped in an array** (e.g., `$.Reviewer.Role` returns `["Admin"]`, not `Admin`)

> **Note:** Integers are evaluated as double-precision floating point. Values above 2^53 lose precision, an input of `9007199254740993` is returned as `9007199254740992`. Extract large numeric identifiers as strings where exactness matters.

#### No Matches Found

When the JSONPath matches nothing, the function returns the **string** `false`. This value is not `null` and not empty, so a comparison such as `if(result = null, ...)` evaluates to `NOT_NULL`. Test for no-match explicitly:

```xql
| alter has_match = if(result = "false", "NO_MATCH", "MATCHED")
```

The same `false` value is returned for a case mismatch, an unreachable key, and a slice that selects no elements.

***

### Sample JSON document

All examples below operate on the same `field_name` value:

```json
{
  "Firewall": {
    "ServerAccessConfig": [
      { "category": "policy", "author": "NRees",     "name": "CustomerSuccess_NoAccess",  "priority": 8.95 },
      { "category": "rule",   "author": "EWaugh",    "name": "AllowAccess_10_10_10_10",   "id": "0-553-21311-3", "priority": 12.99 },
      { "category": "policy", "author": "HMelville", "name": "SOC_Access",                "priority": 8.99 },
      { "category": "rule",   "author": "JTolkien",  "name": "AllowAccess_JIT",           "id": "0-395-19395-8", "priority": 22.99 }
    ],
    "Reviewer": { "UserName": "jdow", "Role": "Admin" }
  }
}
```

In each example the document is assigned inline:

```xql
| alter field_name = "{\"Firewall\":{\"ServerAccessConfig\":[{\"category\":\"policy\",\"author\":\"NRees\",\"name\":\"CustomerSuccess_NoAccess\",\"priority\":8.95},{\"category\":\"rule\",\"author\":\"EWaugh\",\"name\":\"AllowAccess_10_10_10_10\",\"id\":\"0-553-21311-3\",\"priority\":12.99},{\"category\":\"policy\",\"author\":\"HMelville\",\"name\":\"SOC_Access\",\"priority\":8.99},{\"category\":\"rule\",\"author\":\"JTolkien\",\"name\":\"AllowAccess_JIT\",\"id\":\"0-395-19395-8\",\"priority\":22.99}],\"Reviewer\":{\"UserName\":\"jdow\",\"Role\":\"Admin\"}}}"
```

***

### Examples

#### Example 1: Extracting all authors from a nested array

**Goal:** Extract all `author` values from the `ServerAccessConfig` array within the `Firewall` object using the `[*]` wildcard.

**Explanation:** The query uses the `[*]` operator to iterate through all elements of the `ServerAccessConfig` array, extracting the `author` field from each.

```xql
config timeframe = 1d
| dataset = sample_xql_raw
| limit 1
| alter field_name = "{\"Firewall\":{\"ServerAccessConfig\":[...],\"Reviewer\":{...}}}"
| alter all_authors = json_path_extract(field_name, "$.Firewall.ServerAccessConfig[*].author")
| fields event_id, all_authors
```

**Output:**

| event\_id | all\_authors                                |
| --------- | ------------------------------------------- |
| 101       | `["NRees","EWaugh","HMelville","JTolkien"]` |

#### Example 2: Extracting authors with a specific priority

**Goal:** Use a filter expression within the JSONPath to find authors associated with a specific `priority` value.

**Explanation:** The query utilizes the filter expression `?(@.priority==22.99)` to match objects where the `priority` is exactly `22.99`, then extracts the `author` from those matching objects. The `@` symbol references the element currently under evaluation.

```xql
config timeframe = 1d
| dataset = sample_xql_raw
| limit 1
| alter field_name = "{\"Firewall\":{\"ServerAccessConfig\":[...],\"Reviewer\":{...}}}"
| alter specific_priority_author = json_path_extract(field_name, "$..*[?(@.priority==22.99)].author")
| fields event_id, specific_priority_author
```

**Output:**

| event\_id | specific\_priority\_author |
| --------- | -------------------------- |
| 101       | `["JTolkien"]`             |

#### Example 3: Deep scan for all occurrences of a key

**Goal:** Use the recursive descent operator to find all `author` values anywhere in the JSON structure.

**Explanation:** The query uses the `$..author` syntax to perform a deep scan of the entire JSON object, locating and extracting the value of every key named `author`, regardless of its nesting level.

```xql
config timeframe = 1d
| dataset = sample_xql_raw
| limit 1
| alter field_name = "{\"Firewall\":{\"ServerAccessConfig\":[...],\"Reviewer\":{...}}}"
| alter all_authors_deep_scan = json_path_extract(field_name, "$..author")
| fields event_id, all_authors_deep_scan
```

**Output:**

| event\_id | all\_authors\_deep\_scan                    |
| --------- | ------------------------------------------- |
| 101       | `["NRees","EWaugh","HMelville","JTolkien"]` |

#### Example 4: Extracting all direct properties of an object

**Goal:** Extract all direct properties (keys and values) of a specific object using the wildcard operator.

**Explanation:** The query uses `$.Firewall.*` to retrieve all child elements, both the `ServerAccessConfig` array and the `Reviewer` object, directly under the `Firewall` key.

```xql
config timeframe = 1d
| dataset = sample_xql_raw
| limit 1
| alter field_name = "{\"Firewall\":{\"ServerAccessConfig\":[...],\"Reviewer\":{...}}}"
| alter firewall_properties = json_path_extract(field_name, "$.Firewall.*")
| fields event_id, firewall_properties
```

**Output:**

| event\_id | firewall\_properties                                                                                                              |
| --------- | --------------------------------------------------------------------------------------------------------------------------------- |
| 101       | `[[{"category":"policy","author":"NRees",...},{"category":"rule","author":"EWaugh",...},...],{"UserName":"jdow","Role":"Admin"}]` |

> **Note:** The matched array is returned **nested** inside the result, producing a doubly-nested structure (`[[...],{...}]`).

#### Example 5: Deep scan for specific keys

**Goal:** Use recursive descent to find all values associated with a specific key anywhere in the JSON.

**Explanation:** The query uses `$.Firewall..priority` to recursively scan within the `Firewall` object and extract every value associated with the key `priority`.

```xql
config timeframe = 1d
| dataset = sample_xql_raw
| limit 1
| alter field_name = "{\"Firewall\":{\"ServerAccessConfig\":[...],\"Reviewer\":{...}}}"
| alter all_priorities = json_path_extract(field_name, "$.Firewall..priority")
| fields event_id, all_priorities
```

**Output:**

| event\_id | all\_priorities           |
| --------- | ------------------------- |
| 101       | `[8.95,12.99,8.99,22.99]` |

> **Note:** Numeric values retain their JSON numeric type, they are **not** converted to quoted strings.

#### Example 6: Extracting the last element of an array (length calculation)

**Goal:** Extract the last element of an array using the `length` property in a script expression.

**Explanation:** The query uses the script expression `(@.length-1)` to calculate the index of the last element in the `ServerAccessConfig` array and extract it.

```xql
config timeframe = 1d
| dataset = sample_xql_raw
| limit 1
| alter field_name = "{\"Firewall\":{\"ServerAccessConfig\":[...],\"Reviewer\":{...}}}"
| alter last_access_config_item = json_path_extract(field_name, "$..ServerAccessConfig[(@.length-1)]")
| fields event_id, last_access_config_item
```

**Output:**

| event\_id | last\_access\_config\_item                                                                                 |
| --------- | ---------------------------------------------------------------------------------------------------------- |
| 101       | `[{"category":"rule","author":"JTolkien","name":"AllowAccess_JIT","id":"0-395-19395-8","priority":22.99}]` |

#### Example 7: Extracting the last element of an array (slice notation)

**Goal:** Extract the last element of an array using Python-style slice notation.

**Explanation:** The query uses the slice notation `[-1:]` to grab the last item in the `ServerAccessConfig` array.

```xql
config timeframe = 1d
| dataset = sample_xql_raw
| limit 1
| alter field_name = "{\"Firewall\":{\"ServerAccessConfig\":[...],\"Reviewer\":{...}}}"
| alter last_access_config_slice = json_path_extract(field_name, "$..ServerAccessConfig[-1:]")
| fields event_id, last_access_config_slice
```

**Output:**

| event\_id | last\_access\_config\_slice                                                                                |
| --------- | ---------------------------------------------------------------------------------------------------------- |
| 101       | `[{"category":"rule","author":"JTolkien","name":"AllowAccess_JIT","id":"0-395-19395-8","priority":22.99}]` |

#### Example 8: Extracting elements by specific indices

**Goal:** Extract multiple elements from an array by specifying their indices.

**Explanation:** The query targets the `ServerAccessConfig` array and uses `[0,1]` to extract only the first and second elements.

```xql
config timeframe = 1d
| dataset = sample_xql_raw
| limit 1
| alter field_name = "{\"Firewall\":{\"ServerAccessConfig\":[...],\"Reviewer\":{...}}}"
| alter first_two_configs_by_index = json_path_extract(field_name, "$..ServerAccessConfig[0,1]")
| fields event_id, first_two_configs_by_index
```

**Output:**

| event\_id | first\_two\_configs\_by\_index                                                                                            |
| --------- | ------------------------------------------------------------------------------------------------------------------------- |
| 101       | `[{"category":"policy","author":"NRees",...,"priority":8.95},{"category":"rule","author":"EWaugh",...,"priority":12.99}]` |

#### Example 9: Extracting a slice from the beginning of an array

**Goal:** Extract a range of elements from the start of an array using slice notation.

**Explanation:** The query uses `[:2]` to extract a slice of the `ServerAccessConfig` array starting from the beginning up to, but not including, index `2`.

```xql
config timeframe = 1d
| dataset = sample_xql_raw
| limit 1
| alter field_name = "{\"Firewall\":{\"ServerAccessConfig\":[...],\"Reviewer\":{...}}}"
| alter slice_from_beginning = json_path_extract(field_name, "$..ServerAccessConfig[:2]")
| fields event_id, slice_from_beginning
```

**Output:**

| event\_id | slice\_from\_beginning                                                                                                    |
| --------- | ------------------------------------------------------------------------------------------------------------------------- |
| 101       | `[{"category":"policy","author":"NRees",...,"priority":8.95},{"category":"rule","author":"EWaugh",...,"priority":12.99}]` |

#### Example 10: Extract data using different JSONPath expressions

**Goal:** Apply multiple JSONPath configurations to a single JSON field in one query to compare their behavior side by side.

```xql
dataset = xdr_data | limit 1
| alter field_name = "{\"Firewall\":{\"ServerAccessConfig\":[...],\"Reviewer\":{...}}}"
| alter a = json_path_extract(field_name, "$.Firewall.ServerAccessConfig[*].author")
| alter b = json_path_extract(field_name, "$..*[?(@.priority==22.99)].author")
| alter c = json_path_extract(field_name, "$..author")
| alter d = json_path_extract(field_name, "$.Firewall.*")
| alter e = json_path_extract(field_name, "$.Firewall..priority")
| alter f = json_path_extract(field_name, "$..ServerAccessConfig[(@.length-1)]")
| alter g = json_path_extract(field_name, "$..ServerAccessConfig[-1:]")
| alter h = json_path_extract(field_name, "$..ServerAccessConfig[0,1]")
| alter i = json_path_extract(field_name, "$..ServerAccessConfig[:2]")
| fields field_name, a, b, c, d, e, f, g, h, i
```

**Explanation:**

| Field | JSONPath Expression                       | Result Description                                                                 |
| ----- | ----------------------------------------- | ---------------------------------------------------------------------------------- |
| `a`   | `$.Firewall.ServerAccessConfig[*].author` | All values for the `author` key in the `ServerAccessConfig` JSON array.            |
| `b`   | `$..*[?(@.priority==22.99)].author`       | All values for the `author` key where the value of the `priority` key is `22.99`.  |
| `c`   | `$..author`                               | All values for the `author` key anywhere found in the JSON.                        |
| `d`   | `$.Firewall.*`                            | All values under the `Firewall` key.                                               |
| `e`   | `$.Firewall..priority`                    | All values under the `Firewall` key for the `priority` key.                        |
| `f`   | `$..ServerAccessConfig[(@.length-1)]`     | The array index value from the end of the array.                                   |
| `g`   | `$..ServerAccessConfig[-1:]`              | All array index values according to index location from the end of the array.      |
| `h`   | `$..ServerAccessConfig[0,1]`              | A specific set of array index values (one or more) according to index location.    |
| `i`   | `$..ServerAccessConfig[:2]`               | All array index values from the start (index `0`) up to the mentioned index value. |

**Output:**

| \_time                 | a                                  | b        | c                                  | d                                                                                          |
| ---------------------- | ---------------------------------- | -------- | ---------------------------------- | ------------------------------------------------------------------------------------------ |
| Jan 20th 2025 18:51:42 | NRees, EWaugh, HMelville, JTolkien | JTolkien | NRees, EWaugh, HMelville, JTolkien | `[[{"category":"policy",...},{"category":"rule",...}],{"UserName":"jdow","Role":"Admin"}]` |

> **Note:** Columns `E` through `I`, `_PRODUCT`, `_VENDOR`, and `INSERT_TIMESTAMP` are also returned by the query but are omitted from this sample display for brevity.

***

### Syntactic Sugar alternative

For a more concise query, XQL supports a syntactic sugar format using the **double arrow** operator (`->->`). This compiles to the exact same `json_path_extract()` engine but improves human readability.

> **Important:** The `->->` operator is distinct from the single `->` operator. A single `->` compiles to `json_extract_scalar()`, to `json_extract()` when suffixed with `{}`, or to `json_extract_array()` when suffixed with `[]`. Only `->->` compiles to `json_path_extract()`.

**Syntactic Sugar format:**

The JSONPath still must begin with `$.`, exactly as in the regular syntax.

```xql
field_name ->-> "$.<json_path>"
```

**Special characters Syntactic Sugar format:**

When a field name contains a special character such as a colon (`:`), enclose the field name in **double quotes within brackets**. Because the path itself is already delimited by double quotes, use a triple-quoted string:

```xql
field_name ->-> """$.["field_name"]"""
```

**Syntactic Sugar Example:**

```xql
config timeframe = 1d
| dataset = sample_xql_raw
| limit 1
| alter all_authors = field_name ->-> "$..author"
| fields event_id, all_authors
```

***

### Notes

* The `json_path_extract()` function is the only XQL JSON function that supports **recursive descent** (`$..key`), **filter expressions** (`[?(@.key==value)]`), **script expressions** (`[(@.length-1)]`), **slices** (`[-1:]`, `[:2]`), and **index unions** (`[0,1]`).
* The `json_path_extract()` function performs a **very heavy** operation. Prefer `json_extract_scalar()` or the single-arrow (`->`) sugar whenever the path is known and fixed.
* JSON field names are **case-sensitive**; a case mismatch returns the string `false`, not an error and not a null value.
* The path must begin with `$.` in **both** the regular and the syntactic sugar syntax. `$['key']`, `$[0]`, and a bare `$` are rejected.
* Bracket notation (`['field']` / `["field"]`) performs a **recursive descent**, and cannot address keys containing a dot.
* Slice **steps** are accepted (`[::2]`), but a **negative** step (`[::-1]`) never matches. Use `[-1:]` to take from the end.
* The result is a **string representation** of the extracted JSON, not a native XQL array. Chain `json_extract_array()` or `json_extract_scalar_array()` before applying `array_contains()`, `array_length()`, or `arrayexpand`.
* The JSONPath argument must be a **literal string**; it cannot be a field reference or a computed expression.
* If the source field is not already a JSON-formatted string, convert it with `to_json_string()` before extraction. `ARRAY<JSON>` columns are converted automatically; `ARRAY` and integer columns are rejected.
* Invalid JSON supplied as a **literal** raises an error at query-compile time, whereas an unparseable **column** value yields `null` for that row.

***

## Comparison

| Function                      | Returns                              | Multiple Matches | Search by Key | Strips JSON Quotes | Syntactic Sugar format | Best For                                                 |
| ----------------------------- | ------------------------------------ | ---------------- | ------------- | ------------------ | ---------------------- | -------------------------------------------------------- |
| `json_extract()`              | String (always)                      | No               | No            | No                 | `field -> path{}`      | Extracting any value while preserving JSON formatting    |
| `json_extract_scalar()`       | Plain string (scalar only)           | No               | No            | Yes                | `field -> path`        | Extracting a single string/number/boolean for filters    |
| `json_extract_array()`        | XQL array (elements doubly-quoted)   | No               | No            | No                 | `field -> path[]`      | Extracting arrays (including arrays of objects)          |
| `json_extract_scalar_array()` | XQL array of plain strings           | No               | No            | Yes                | No Not supported       | Extracting arrays of scalar values for comparisons       |
| `json_path_extract()`         | String representation of all matches | Yes              | Yes           | No                 | `field ->-> "$.path"`  | Recursive search, wildcards, filters, slices, and unions |

***

## When to use which function

| Scenario                                          | Recommended Syntax                                    | Reason                                                                 | Example                                                         |
| ------------------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------- |
| Value at a known, fixed path                      | `json_extract_scalar()`                               | Native and far cheaper than the heavy JSONPath engine                  | `json_extract_scalar(data, "$.user.name")`                      |
| Key at an unknown depth                           | `json_path_extract()`                                 | Only function supporting recursive descent (`$..`)                     | `json_path_extract(data, "$..author")`                          |
| Same key across all elements of an array          | `json_path_extract()`                                 | Wildcard collects every match in a single call                         | `json_path_extract(data, "$.config[*].author")`                 |
| Array elements matching a predicate               | `json_path_extract()`                                 | Filter expression avoids a follow-up `arrayfilter`                     | `json_path_extract(data, "$..*[?(@.priority==22.99)])`          |
| Last element of an array                          | `json_path_extract()`                                 | Slice (`[-1:]`) and script (`[(@.length-1)]`) expressions supported    | `json_path_extract(data, "$..config[-1:]")`                     |
| First N elements of an array                      | `json_path_extract()`                                 | Slice notation `[:N]` is supported                                     | `json_path_extract(data, "$..config[:2]")`                      |
| A specific set of array indices                   | `json_path_extract()`                                 | Index union `[0,1]` is supported                                       | `json_path_extract(data, "$..config[0,1]")`                     |
| Array of complex objects to iterate               | `json_extract_array()`                                | Returns a native array for `arraymap`/`arrayfilter`                    | `json_extract_array(properties, "$.entities")`                  |
| Array of simple scalar values                     | `json_extract_scalar_array()`                         | Returns clean strings without quotes                                   | `json_extract_scalar_array(user, "$.rolegrants")`               |
| Result used in a `filter` equality comparison     | `json_extract_scalar()`                               | `json_path_extract()` output is collection-wrapped and will not match  | `filter json_extract_scalar(d, "$.type") = "AUDIT"`             |
| Result needed as a native XQL array               | `json_path_extract()` + `json_extract_scalar_array()` | `json_path_extract()` returns a string, not a native array             | `json_extract_scalar_array(json_path_extract(d, "$..ip"), "$")` |
| Key name contains a dot                           | `json_extract_scalar()`                               | `json_path_extract()` cannot address dotted keys at all                | `json_extract_scalar(d, "$.['key.name']")`                      |
| Inside an ingestion rule, streaming rule, or SBAC | `json_extract*()` family                              | `json_path_extract()` is not available outside search queries          | `json_extract_scalar(d, "$.user.name")`                         |
| Large numeric identifiers (above 2^53)            | `json_extract_scalar()`                               | `json_path_extract()` evaluates numbers as doubles and loses precision | `json_extract_scalar(d, "$.bigid")`                             |

***

## Known limitations summary

| #  | Limitation                                   | Affected Function     | Impact                                                             | Workaround                                                        |
| -- | -------------------------------------------- | --------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------- |
| 1  | Very heavy operation                         | `json_path_extract()` | Significant resource consumption at query time                     | Use `json_extract_scalar()` when the path is fixed and known      |
| 2  | Result is collection-wrapped                 | `json_path_extract()` | Breaks direct `filter` equality comparisons, even for one match    | Chain `json_extract_scalar_array(..., "$")` or `arrayindex()`     |
| 3  | Result is a string, not a native XQL array   | `json_path_extract()` | `array_contains()` / `arrayexpand` cannot be applied directly      | Wrap with `json_extract_array()` or `json_extract_scalar_array()` |
| 4  | No match returns the string `false`          | `json_path_extract()` | Not null and not empty, so null-checks report a value as present   | Compare explicitly against `"false"`                              |
| 5  | Field names are case-sensitive               | All JSON functions    | A case mismatch returns `false` instead of raising an error        | Match the JSON structure exactly                                  |
| 6  | Keys containing a dot are unreachable        | `json_path_extract()` | `$.['key.name']` is read as `key` → `name`, and returns `false`    | Rename the key at ingestion; no path syntax can address it        |
| 7  | Bracket notation is a recursive descent      | `json_path_extract()` | `$.['UserName']` also matches nested keys, not just the root child | Use an explicit dot path when a direct child is intended          |
| 8  | Path must start with `$.`                    | `json_path_extract()` | `$['key']`, `$[0]` and bare `$` fail with a validation error       | Always prefix the path with `$.`                                  |
| 9  | Negative slice step never matches            | `json_path_extract()` | `[::-1]` returns `false` rather than reversing the array           | Use `[-1:]`, or reverse after extraction                          |
| 10 | Integers lose precision above 2^53           | `json_path_extract()` | `9007199254740993` is returned as `9007199254740992`               | Extract large IDs as strings                                      |
| 11 | JSONPath must be a literal string            | `json_path_extract()` | The path cannot be built from a field or expression at query time  | Hard-code the path, or branch with `if()`                         |
| 12 | Search queries only                          | `json_path_extract()` | Unavailable in ingestion (XIF), streaming, and dataset SBAC        | Use `json_extract*()` functions in those contexts                 |
| 13 | Requires a valid JSON-formatted string input | All JSON functions    | A bad literal fails at compile time; a bad column value gives null | Wrap the input with `to_json_string()`                            |
| 14 | Wildcard on an object nests matched arrays   | `json_path_extract()` | `$.Firewall.*` yields a doubly-nested `[[...],{...}]` structure    | Target the array directly, or post-process the nested result      |

***

## JSONPath Quick Reference

| Expression              | Description                                            | `json_path_extract()` | `json_extract*()` |
| ----------------------- | ------------------------------------------------------ | --------------------- | ----------------- |
| `$`                     | Root element (alone, not a valid path, see `$.` rule)  | No                    | Yes               |
| `$.key`                 | Child element named `key`                              | Yes                   | Yes               |
| `$.a.b`                 | Nested child: `b` inside `a`                           | Yes                   | Yes               |
| `$.array[0]`            | First element of an array                              | Yes                   | Yes               |
| `$.array[*]`            | All elements of an array                               | Yes                   | Partial           |
| `$.object.*`            | All direct properties of an object                     | Yes                   | No                |
| `$..key`                | Recursive descent, `key` at any depth                  | Yes                   | No                |
| `$.a..key`              | Recursive descent scoped beneath `a`                   | Yes                   | No                |
| `$..*[?(@.k==v)]`       | Filter expression on matching elements                 | Yes                   | No                |
| `$.array[(@.length-1)]` | Script expression, last element by computed index      | Yes                   | No                |
| `$.array[-1:]`          | Slice from the end of an array                         | Yes                   | No                |
| `$.array[:2]`           | Slice from the beginning of an array                   | Yes                   | No                |
| `$.array[::2]`          | Slice with a positive step                             | Yes                   | No                |
| `$.array[::-1]`         | Slice with a negative step, **never matches**          | No                    | No                |
| `$.array[0,1]`          | Union of specific array indices                        | Yes                   | No                |
| `$.['key']`             | Bracket notation, behaves as a **recursive descent**   | Yes                   | Yes               |
| `$.['key.name']`        | Bracket notation for a key containing a **dot**        | No                    | Yes               |
| `$['key']`              | Bracket notation without the leading `$.`              | No                    | Yes               |
| `$[@field]`             | Root-level bracket notation for keys starting with `@` | No                    | Yes               |

***

## Related Articles

* **Stages:** `alter`
* **Functions:** `json_extract`, `json_extract_array`, `json_extract_scalar`, `json_extract_scalar_array`, `to_json_string`


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://cortex-docs.paloaltonetworks.com/xql-command-reference-guide/readme/functions/xql-json-functions-reference.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
