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

```sql
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**:

```sql
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**:

```sql
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**:

```sql
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**:

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

## Related articles

* **Stages**: [`alter`](alter), [`config`](config), [`filter`](filter), [`limit`](limit)