fields ↗

Use the fields stage to precisely define the columns that are returned in your XQL query result set. Use this stage, to ensure that all subsequent query stages operate exclusively on the columns you have explicitly declared.

Syntax

fields [-] <field_1> [as <alias_1>], <field_2> [as <alias_2>], ...

Parameters

Name Type Required Description
field_n string Yes The name of the field to include in the results.
alias_n string No The alias name to assign to the field using the as clause.
- operator No The minus character used to exclude a specific field from the result set.
as clause No The clause used to assign an alias to an existing field.

Returns

The fields stage returns specific columns, which are then utilized as fields in all subsequent stages of the query.

Usage notes

  • In Cortex Data Model (XDM) queries, the syntax is as follows: fields [-] fieldset.xdm_<fieldset name1>, fieldset.xdm_<fieldset name2>, ..., where the field names are replaced by dataset_name.field_name. For example, fields amazon_eks_raw.logStream.
  • In dataset queries, the following system fields cannot be excluded and are always displayed if they exist in the results: _time, _insert_time, _raw_log, _product, _vendor, _tag, _snapshot_id, _snapshot_log_count, _snapshot_collection_ts, and _id.
  • In XDM queries, the _time field cannot be excluded and is always displayed if it exists in the results.
  • The fields stage does not allow the use of any functions.
  • New fields and field values cannot be created within the fields stage; they must be created within the alter stage.
  • If you use the as clause, all subsequent stages in the query must refer to the field by its new alias.
  • To perform exclusion from a wider set of selected fields, you must use multiple fields stages: one for initial inclusion, followed by one or more for exclusion.
  • Employing the fields stage early in your query, immediately after any primary filtering, significantly reduces the amount of data processed.
  • Avoid using fields (or omitting the fields stage when running dataset queries) with large datasets like xdr_data, as this can vastly impact performance.

Examples

Example 1: Basic field selection

Goal: Explicitly list the field names you wish to include in your results.

XQL code:

config timeframe = 1d
| dataset = sample_xql_raw
| fields event_id, event_description
| limit 2

Explanation: The query selects only the event_id and event_description columns from the dataset.

Output:

event_id event_description
101 "User login successful"
102 "File access attempt"

Example 2: Aliasing fields

Goal: Rename fields for clarity or brevity in your result set using the as clause.

XQL code:

config timeframe = 1d
| dataset = sample_xql_raw
| fields event_id as EventIdentifier, is_successful as Status
| limit 2

Explanation: The query renames event_id to EventIdentifier and is_successful to Status in the output.

Output:

EventIdentifier Status
101 true
102 false

Example 3: Including fields with wildcards

Goal: Include all fields that match a specified pattern using a wildcard (*).

XQL code:

config timeframe = 1d
| dataset = sample_xql_raw
| fields event_* | limit 2

Explanation: The query selects all fields starting with the string "event_", such as event_id and event_description.

Output:

event_id event_description
101 "User login successful"
102 "File access attempt"

Example 4: Excluding fields

Goal: Exclude a specific field from the result set using the minus character (-).

XQL code:

config timeframe = 1d
| dataset = sample_xql_raw
| fields event_*, _time, is_successful 
| fields - event_id 
| limit 2

Explanation: The query first selects a broad set of fields including event_*, _time, and is_successful. A second fields stage then explicitly excludes event_id from that selection.

Output:

_time event_description is_successful
2023-10-26 10:00:00 UTC "User login successful" true
2023-10-26 10:05:30 UTC "File access attempt" false