> 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/stages/config.md).

# config

Use the `config` stage to configure the behavior of your query, specifically controlling case sensitivity and the execution time frame. This stage is crucial for query optimization and must always be the very first stage in your XQL query.

## Syntax

```sql
config case_sensitive = true | false
config timeframe = <number><time unit>
config timeframe between <start> and <end>
```

## Parameters

| Name             | Type    | Required                | Description                                                                                                 |
| ---------------- | ------- | ----------------------- | ----------------------------------------------------------------------------------------------------------- |
| `case_sensitive` | boolean | No                      | Controls whether field values are evaluated in a case-sensitive manner. Default is `false`.                 |
| `timeframe`      | string  | No                      | Defines the specific time range for the query's execution.                                                  |
| `number`         | integer | Yes (if timeframe used) | The duration value for the timeframe.                                                                       |
| `time_unit`      | string  | Yes (if timeframe used) | The unit of time (S, M, H, D, W, MO, Y). Not case-sensitive.                                                |
| `start`          | string  | Yes (if between used)   | The start of the time range. Can be a relative offset (for example, "-1h"), "begin", or an exact timestamp. |
| `end`            | string  | Yes (if between used)   | The end of the time range. Can be a relative offset, "now", or an exact timestamp.                          |

## Returns

The `config` stage does not return a value itself but sets the execution context (rules and scope) for the subsequent query stages.

## Usage notes

* The `config` stage must always be the first stage in your XQL query.
* For `case_sensitive`, if not explicitly set, XQL queries operate with case-insensitivity (`false`) by default.
* For `timeframe`, available time units are: S (seconds), M (minutes), H (hours), D (days), W (weeks), MO (months), Y (years). These are not case-sensitive.
* While the Query Builder's time picker automatically sets the timeframe, it will only appear in your query text if you manually type the `config timeframe` command.

## Examples

### Example 1: Case-sensitive search

**Goal**: Configure the query to strictly match the case of string values during filtering.

**XQL code**:

```sql
config case_sensitive = true
| dataset = sample_xql_raw
| filter event_description = "user login successful"
| fields event_id, event_description
| limit 5
```

**Explanation**: The query attempts to find records where `event_description` is exactly "user login successful" (lowercase). Given the dataset contains "User login successful" (uppercase 'U'), this query yields no results because `case_sensitive` is set to `true`.

**Output**:

| EVENT\_ID | EVENT\_DESCRIPTION |
| --------- | ------------------ |
|           | (No results)       |

### Example 2: Case-insensitive search

**Goal**: Configure the query to ignore case differences when matching string values.

**XQL code**:

```sql
config case_sensitive = false
| dataset = sample_xql_raw
| filter event_description = "user login successful"
| fields event_id, event_description
| limit 5
```

**Explanation**: With `case_sensitive` set to `false`, the query successfully matches the lowercase string "user login successful" to the dataset's "User login successful", retrieving the record.

**Output**:

| EVENT\_ID | EVENT\_DESCRIPTION    |
| --------- | --------------------- |
| 101       | User login successful |

### Example 3: Relative time (simple duration)

**Goal**: Retrieve records from the specified duration counting back from the current query execution time.

**XQL code**:

```sql
config timeframe = 1h
| dataset = sample_xql_raw
| fields _time, event_id, event_description
| limit 10
```

**Explanation**: If executed at `2023-10-26 10:30:00 UTC`, this query retrieves events from the last hour (09:30:00 to 10:30:00 UTC), essentially capturing events 101 through 105 from the sample data.

**Output**:

| \_TIME                  | EVENT\_ID | EVENT\_DESCRIPTION             |
| ----------------------- | --------- | ------------------------------ |
| 2023-10-26 10:00:00 UTC | 101       | User login successful          |
| 2023-10-26 10:05:30 UTC | 102       | File access attempt            |
| 2023-10-26 10:15:15 UTC | 103       | Network connection established |
| 2023-10-26 10:20:00 UTC | 104       | System heartbeat               |
| 2023-10-26 10:30:45 UTC | 105       | Data transformation            |

### Example 4: Relative time (range ending now)

**Goal**: Retrieve records within a range starting from a relative point in the past and ending at the current time.

**XQL code**:

```sql
config timeframe between "-30m" and "now"
| dataset = sample_xql_raw
| fields _time, event_id, event_description
| limit 10
```

**Explanation**: If executed at `2023-10-26 10:45:00 UTC`, this returns events from `10:15:00 UTC` to `10:45:00 UTC`. This window captures events 103 through 107 (conceptual match based on sample data timing).

**Output**:

| \_TIME                  | EVENT\_ID | EVENT\_DESCRIPTION             |
| ----------------------- | --------- | ------------------------------ |
| 2023-10-26 10:15:15 UTC | 103       | Network connection established |
| 2023-10-26 10:20:00 UTC | 104       | System heartbeat               |
| 2023-10-26 10:30:45 UTC | 105       | Data transformation            |
| 2023-10-26 10:40:10 UTC | 106       | Unauthorized access detected   |
| 2023-10-26 10:45:00 UTC | 107       | Cloud resource modification    |

### Example 5: Relative time (from beginning to past offset)

**Goal**: Retrieve records from the Unix epoch up to a specific relative point in the past.

**XQL code**:

```sql
config timeframe between "begin" and "-1y"
| dataset = sample_xql_raw
| fields _time, event_id, event_description
| limit 10
```

**Explanation**: This queries data from `1970-01-01` up to one year ago from the current execution time. If "now" is significantly in the future relative to the sample data (for example, late 2024), this would successfully retrieve the 2023 records.

**Output**:

| \_TIME                  | EVENT\_ID | EVENT\_DESCRIPTION    |
| ----------------------- | --------- | --------------------- |
| 2023-10-26 10:00:00 UTC | 101       | User login successful |
| 2023-10-26 10:05:30 UTC | 102       | File access attempt   |
| ...                     | ...       | ...                   |

### Example 6: Relative time (between two offsets)

**Goal**: Define a relative window spanning between two points in the past relative to the current execution time.

**XQL code**:

```sql
config timeframe between "-2h" and "-1h"
| dataset = sample_xql_raw
| fields _time, event_id, event_description
| limit 10
```

**Explanation**: If executed at `2023-10-26 11:00:00 UTC`, the window is `09:00:00` to `10:00:00`. Only event 101 (at exactly 10:00:00) fits this window.

**Output**:

| \_TIME                  | EVENT\_ID | EVENT\_DESCRIPTION    |
| ----------------------- | --------- | --------------------- |
| 2023-10-26 10:00:00 UTC | 101       | User login successful |

### Example 7: Exact timeframe

**Goal**: Define a precise, static start and end timestamp for the query.

**XQL code**:

```sql
config timeframe between "2023-10-26 10:00:00 UTC" and "2023-10-26 10:30:00 UTC"
| dataset = sample_xql_raw
| fields _time, event_id, event_description
| limit 100
```

**Explanation**: This query explicitly selects records between 10:00:00 and 10:30:00 UTC on the specified date.

**Output**:

| \_TIME                  | EVENT\_ID | EVENT\_DESCRIPTION             |
| ----------------------- | --------- | ------------------------------ |
| 2023-10-26 10:00:00 UTC | 101       | User login successful          |
| 2023-10-26 10:05:30 UTC | 102       | File access attempt            |
| 2023-10-26 10:15:15 UTC | 103       | Network connection established |
| 2023-10-26 10:20:00 UTC | 104       | System heartbeat               |
| 2023-10-26 10:30:45 UTC | 105       | Data transformation            |

## Related articles

* **Stages**: [`dataset`](/xql-command-reference-guide/readme/stages/dataset.md), [`filter`](/xql-command-reference-guide/readme/stages/filter.md), [`fields`](/xql-command-reference-guide/readme/stages/fields.md)


---

# 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/xql-command-reference-guide/readme/stages/config.md?ask=<question>&goal=<endgoal>
```

`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.