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

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

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

XQL code:

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)

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

XQL code:

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:

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:

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:

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:

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:

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