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

# 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`](/xql-command-reference-guide/readme/stages/alter.md), [`config`](/xql-command-reference-guide/readme/stages/config.md), [`filter`](/xql-command-reference-guide/readme/stages/filter.md), [`limit`](/xql-command-reference-guide/readme/stages/limit.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/fields.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.