> 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/cortex-agentix/reference-and-developer-docs/cortex-agentix-xql/get-started-with-xql/json-functions.md).
# JSON functions
The Cortex Query Language (XQL) includes a number of JSON functions. Before using any of these functions, it's important to understand how Cortex AgentiX treats a JSON so you can accurately formulate your queries using the correct syntax.
{% hint style="info" %}
### Important
JSON field names are case sensitive, so the key to field pairing must be identical in an XQL query for results to be found. For example, if a field value is `"TIMESTAMP"` and your query is defined to look for "timestamp", no results will be found.
{% endhint %}
<json_path>
Each JSON function includes defining a `` in both the regular syntax and when using the syntatic sugar format. The `` argument identifies the data of the JSON object you want to extract using dot-notation. When using the regular syntax, the beginning of the object is represented by a `$`. This `$` is not required when using the syntatic sugar format.
Example
If you have the following object:
```programlisting
{
"a_field" : "This is a_field value",
"b_field" : {
"c_field" : "This is c_field value"
}
}
```
Then the path using the regular syntax:
```programlisting
$.a_field
```
Returns `"This is a_field value"`, while the path using the regular syntax:
```programlisting
$.b_field.c_field
```
Returns `"This is c_field value"`.
Field in <json_path> contains characters
#### In the regular syntax
When using the regular syntax to write your XQL queries and a field in the `` contains characters, such as a dot (.) or colon (:), the syntax needs to be tweaked slightly to account for the ``.
For example, when using the `json_extract` function, the previous regular syntax would need to be changed to an updated syntax to account for the field in the `` containing characters.
Previous regular syntax for the `json_extract` function:
```programlisting
json_extract(, )
```
Updated regular syntax for the `json_extract` function, where the `` now includes single quotation marks as `''`:
```programlisting
json_extract(, "['']")
```
For each JSON function, the regular syntax can change slightly, but the `"['']"` format is the same. The `"['']"` identifies the data you want to extract using dot-notation, where the data extracted is dependent on your syntax.
Example
If you have the following JSON object defined:
```programlisting
{"a.b":
{"inn":
{"one":1}
}
}
```
To extract the data `{"one":1}`, the `"['']"` would need to be defined as `"$['a.b'].inn"` for all JSON functions. For example, when using the `json_extract` function, the regular syntax is:
```programlisting
json_extract(field_json_1, "$['a.b'].inn")
```
To extract the data `{"inn": {"one":1}}`, the `"['']"` would need to be defined as `"$['a.b']"` for all JSON functions. For example, when using the `json_extract` function, the regular syntax is:
```programlisting
json_extract(field_json_1, "$['a.b']")
```
Example
If you have the following JSON object defined:
```programlisting
{"a.b":
{"inn.inn":
{"one":1}
}
}
```
To extract the data `{"one":1}`, the `"['']"` would need to be defined as `"$['a.b']['inn.inn']"` for all JSON functions. For example, when using the `json_extract` function, the regular syntax is:
```programlisting
json_extract(json_field, "$['a.b']['inn.inn']")
```
#### In the syntatic sugar format
To make it easier for you to write your XQL queries, each JSON function includes an optional syntatic sugar format as opposed to using the regular syntax. When defining the syntatic sugar format and a field in the `` contains characters, such as a dot (.) or colon (:), the syntax needs to be tweaked slightly to account for the ``.
For example, when using the `json_extract` function, the previous syntatic sugar format would need to be changed to an updated syntax to account for the field in the `` containing characters.
Previous syntatic sugar format for the `json_extract` function:
```programlisting
-> {}
```
Updated syntatic sugar format for the `json_extract` function, where the `` now includes quotations as `""`:
```programlisting
-> [""]{}
```
For each JSON function, the syntax of the syntatic sugar format can change slightly, but the `[""]` format is the same. The `[""]` identifies the data you want to extract using dot-notation, where the data extracted is dependent on your syntax.
Example
If you have the following JSON object defined:
```programlisting
{"a.b":
{"inn":
{"one":1}
}
}
```
To extract the data `{"one":1}`, the `[""]` would need to be defined as `["a.b"].inn` for all JSON functions. For example, when using the `json_extract` function, the syntatic sugar format is:
```programlisting
json_field -> ["a.b"].inn{}
```
To extract the data `{"inn": {"one":1}}`, the `[""]` would need to be defined as `["a.b"]` for all JSON functions. For example, when using the `json_extract` function, the syntatic sugar format is:
```programlisting
json_field -> ["a.b"]{}
```
Example
If you have the following `json_object` defined:
```programlisting
{"a.b":
{"inn.inn":
{"one":1}
}
}
```
To extract the data `{"one":1}`, the `[""]` would need to be defined as `["a.b"]["inn.inn"]` for all JSON functions. For example, when using the `json_extract` function, the syntatic sugar format is:
```programlisting
json_field -> ["a.b"]["inn.inn"]{}
```
---
# 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 dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://cortex-docs.paloaltonetworks.com/cortex-agentix/reference-and-developer-docs/cortex-agentix-xql/get-started-with-xql/json-functions.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.