> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omni.co/llms.txt
> Use this file to discover all available pages before exploring further.

# fields

> Curates which fields each sub-topic contributes to the field picker.

Curates which fields each sub-topic contributes to the field picker. Use the `@topic`-scoped syntax to include or exclude specific fields, views, or tags from individual sub-topics — or apply global directives across all sub-topics.

The `fields:` parameter addresses the "too many filterable dimensions" noise that can occur when combining multiple topics. It filters which fields appear in the field picker, but doesn't restrict queries — queries against excluded fields still execute, so existing saved queries don't break.

<Note>
  The `fields:` parameter intersects with each sub-topic's own `fields:` directive — it can only narrow what a sub-topic already exposes, not add fields the sub-topic has already excluded.
</Note>

## Syntax

```yaml theme={null}
fields:
  - "@<topic_name>.<view>.<field>"       # include a specific field from one topic
  - "@<topic_name>.<view>.*"             # include all fields from a view in one topic
  - "@<topic_name>.<view>"               # include all fields from a view in one topic
  - "@<topic_name>.<view>:tag:<tag>"     # include fields by tag from one topic
  - "-@<topic_name>.<view>.<field>"      # exclude a specific field from one topic
  - "-@<topic_name>.<view>"              # exclude an entire view from one topic
  - "<view>.<field>"                     # global: applies to all sub-topics
  - "-tag:<tag>"                         # global: exclude tagged fields from all sub-topics
```

## Properties

<ParamField path="fields" type="string[]">
  A list of field directives. Each directive either includes or excludes fields from the field picker.

  **`@topic`-scoped directives** apply to a single sub-topic:

  * `@<topic_name>.<view>.<field>` — include a specific field
  * `@<topic_name>.<view>.*` or `@<topic_name>.<view>` — include all fields from a view
  * `@<topic_name>.<view>:tag:<tag>` — include fields by tag
  * `-@<topic_name>.<view>.<field>` — exclude a specific field
  * `-@<topic_name>.<view>` — exclude an entire view

  **Global directives** (without `@topic`) apply to every sub-topic:

  * `<view>.<field>`, `tag:<tag>`, `set:<set>` — include patterns across all topics
  * `-tag:<tag>`, `-<view>.<field>` — exclude patterns across all topics

  **Include vs. exclude behavior:**

  * If all directives are excludes (start with `-`), everything else is included
  * If any directive is an include (no `-`), the list becomes a whitelist — only explicitly included fields appear

  **A sub-topic with no matching `@topic`-scoped directive is left untouched** — so scoping to topic A never hides fields from topic B.
</ParamField>

## Examples

The following examples assume a composite topic that combines sub-topics named `sales` and `marketing`.

```yaml title="Include specific views from each topic" theme={null}
fields:
  - "@sales.orders.*"              # include all orders fields from sales
  - "@marketing.campaigns.*"       # include all campaigns fields from marketing
```

```yaml title="Exclude specific fields" theme={null}
fields:
  - "-@sales.orders.internal_id"   # exclude one field from sales' orders view
  - "-@marketing.campaigns"        # drop the entire campaigns view from marketing
```

```yaml title="Global exclusions across all topics" theme={null}
fields:
  - "-tag:pii"                     # exclude PII-tagged fields from all topics
```

```yaml title="Mix scoped includes with global excludes" theme={null}
fields:
  - "@sales.orders.*"              # include all of orders from sales
  - "-@sales.orders.internal_id"   # but exclude one specific field
  - "-@marketing.campaigns"        # drop campaigns view from marketing
  - "-tag:pii"                     # global: exclude PII fields everywhere
```

## Intersection with sub-topic `fields:`

The composite topic's `fields:` parameter is applied **on top of** each sub-topic's own `fields:` directive. The result is an intersection — the composite can only narrow what the sub-topic already exposes.

If a sub-topic has:

```yaml theme={null}
fields:
  - orders.*
  - -orders.internal_notes
```

And the composite topic has:

```yaml theme={null}
fields:
  - "@sales_topic.orders.total_revenue"
```

The field picker shows only `orders.total_revenue` from that topic — the intersection of the sub-topic's `orders.*` (minus `internal_notes`) and the composite's scoped include.

## Picker-only filtering

The `fields:` parameter only affects which fields appear in the field picker. Queries against excluded fields still execute — this ensures existing saved queries and dashboards don't break when you refine the field list.

If a user has a saved query that references `@sales.orders.internal_id`, that query continues to run even after you add `-@sales.orders.internal_id` to the composite topic's `fields:` list.