---
title: Use field aliases
slug: q1k90356
canonical_url: https://docs.coveo.com/en/q1k90356/
collection: build-a-search-ui
source_format: adoc
---
# Use field aliases

This is useful when you need to retrieve several values from the same dictionary field at once, which isn't possible with the [`dictionaryFieldContext`](https://docs.coveo.com/en/56.md#dictionaryfieldcontext-object-optional) parameter.

For example, in a commerce scenario, you can display both the regular price and a discounted price for a product in the same result.
With `dictionaryFieldContext`, you would have to choose one.
With [field aliases](https://docs.coveo.com/en/q1q94008.md), you can retrieve both values simultaneously.

You can also use [field aliases](https://docs.coveo.com/en/q1q94008.md) like non-dictionary fields in advanced query expressions (`aq`) for filtering and in [ranking functions](https://docs.coveo.com/en/237.md) for boosting.

## Example scenario

Suppose your [index](https://docs.coveo.com/en/204.md) contains products with a `price_list` dictionary field that stores different prices for different customer types:

```json
{
  "documentId": "product://alternator-001",
  "title": "Mercury Alternator",
  "price_list": {
    "regular": 4000.00,
    "vip": 3750.00,
    "wholesale": 3500.00
  }
  [...]
}
```

With `dictionaryFieldContext`, you can only retrieve one of these prices per query.

.`dictionaryFieldContext` example
<details><summary>Details</summary>

```json
// Token
{
  "dictionaryFieldContext": { "price_list": "vip" }
}

// Query - uses original field name
{
  "q": "boots"
}

// Response - only one price available
{
  [...]
  "results": [
    {
      [...]
      "raw": {
        [...]
        "price_list": 3750.00
      }
    }
  ]
}
```

</details>
With [field aliases](https://docs.coveo.com/en/q1q94008.md), you can retrieve multiple prices in a single request.
For example, you could display both the regular and VIP prices side by side in search results.

**Example using [field aliases](https://docs.coveo.com/en/q1q94008.md)**
<details><summary>Details</summary>

```json
// Token
{
  "allowedDictionaryFieldKeys": { "price_list": ["*"] }
}

// Query - uses custom alias names
{
  "fieldAliases": {
    "regular_price": "price_list.regular",
    "vip_price": "price_list.vip"
  },
  "q": "boots"
}

// Response - multiple prices available via aliases
{
  [...]
  "results": [
    {
      [...]
      "raw": {
        [...]
        "regular_price": 4000.00,
        "vip_price": 3750.00
      }
    }
  ]
}
```

</details>
## Comparison with `dictionaryFieldContext`

The `dictionaryFieldContext` parameter is the traditional way to retrieve dictionary field values.
[field aliases](https://docs.coveo.com/en/q1q94008.md) offer more flexibility but require [search token](https://docs.coveo.com/en/1346.md) authentication.
You can set them per query with the `fieldAliases` parameter in the Search API only.
Commerce API implementations configure them through [context mappings](https://docs.coveo.com/en/q3bc0472.md#destination-examples) instead.

| Aspect | `dictionaryFieldContext` | [field aliases](https://docs.coveo.com/en/q1q94008.md) |
|---|---|---|
| Keys per request | One key per dictionary field | Multiple keys per dictionary field |
| Authorization | Can be set in token or Search API query | Requires `allowedDictionaryFieldKeys` in token |
| Query parameter | `dictionaryFieldContext` | `fieldAliases` |
| Alias support | No (uses original field name) | Yes (custom alias names) |
| API support | Search API and Commerce API | Search API directly; Commerce API through context mappings |

## Limitations

* **Search tokens only**: [field aliases](https://docs.coveo.com/en/q1q94008.md) require [search token](https://docs.coveo.com/en/1346.md) authentication.
API keys and platform tokens don't support `allowedDictionaryFieldKeys`.

* **Set per query in the Search API only**: You can pass the `fieldAliases` query parameter with the Search API only.
Commerce API implementations don't set [field aliases](https://docs.coveo.com/en/q1q94008.md) per request.
They configure a [context mapping](https://docs.coveo.com/en/q3bc0472.md#destination-examples) with the `FIELD_ALIASES` destination, and the Commerce API resolves the alias at query time from a context value the shopper provides.

* **Mutually exclusive with `dictionaryFieldContext`**: You can't use both `fieldAliases` and `dictionaryFieldContext` in the same request.
Doing so returns an error.

* **No empty key access**: [field aliases](https://docs.coveo.com/en/q1q94008.md) can't retrieve the default empty key (`""`) of a dictionary field.
If you need a fallback value, use an explicitly named key such as `"default"` in your dictionary data instead of an empty key.

## How field aliases work

[field aliases](https://docs.coveo.com/en/q1q94008.md) use a two-part model:

1. **Authorization**: The [search token](https://docs.coveo.com/en/1346.md) defines which dictionary field keys users are allowed to access using the `allowedDictionaryFieldKeys` property.

1. **Selection**: At query time, you use the `fieldAliases` parameter to specify which keys to retrieve.
Each alias maps a custom name (that you choose) to an actual `field.key` reference in the [index](https://docs.coveo.com/en/204.md).

This separation gives you fine-grained control over access while keeping [queries](https://docs.coveo.com/en/231.md) flexible.

### Authorize access to dictionary field keys

Before users can query dictionary field keys with [field aliases](https://docs.coveo.com/en/q1q94008.md), you must authorize access in their [search token](https://docs.coveo.com/en/1346.md).

Use the [`allowedDictionaryFieldKeys`](https://docs.coveo.com/en/56.md#alloweddictionaryfieldkeys-object-optional) property to specify which dictionary fields and keys users can access.

```json
{
  "userIds": [
    {
      "name": "asmith@example.com",
      "type": "User",
      "provider": "Email Security Provider"
    }
  ],
  "allowedDictionaryFieldKeys": { <1>
    "price_list": ["*"] <2>
  }
}
```

<1> The `allowedDictionaryFieldKeys` property defines which dictionary field keys the user can access with [field aliases](https://docs.coveo.com/en/q1q94008.md).

<2> The wildcard `["*"]` grants access to all keys in the `price_list` dictionary field.

To limit access to specific keys, list those keys instead of the wildcard.
For example, `"price_list": ["regular", "vip"]` lets users create [field aliases](https://docs.coveo.com/en/q1q94008.md) for the `regular` and `vip` keys only, and denies access to the `wholesale` key.

### Query with field aliases

Once authorization is configured in the token, use the `fieldAliases` parameter in your query to map dictionary field keys to alias names.

The format in your query is:

```json
{
  "fieldAliases": {
    "<ALIAS_NAME>": "<FIELD>.<KEY>"
  }
  [...]
}
```

For example, to retrieve both the regular and VIP prices from a `price_list` dictionary field:

```json
{
  "q": "alternator",
  "fieldAliases": {
    "regular_price": "price_list.regular", <1>
    "vip_price": "price_list.vip" <2>
  }
}
```

<1> Creates an alias `regular_price` that returns the value of the `regular` key.

<2> Creates an alias `vip_price` that returns the value of the `vip` key.

Once defined, you can reference these [field aliases](https://docs.coveo.com/en/q1q94008.md) just like normal fields.
For example, you can use `@regular_price` in a [result template](https://docs.coveo.com/en/atomic/latest/usage/displaying-results#defining-a-result-template), in an `aq` expression to filter results, or in a [ranking function](https://docs.coveo.com/en/237.md) to boost results.

## Use aliases in query expressions

[field aliases](https://docs.coveo.com/en/q1q94008.md) are designed to work like non-dictionary fields.
Once defined, you can reference them with the `@` prefix in query expressions and [ranking functions](https://docs.coveo.com/en/237.md).

### Filter with `aq`

Suppose your [index](https://docs.coveo.com/en/204.md) contains products with an `inventory` dictionary field that stores stock quantities for different store locations:

```json
{
  "documentId": "product://winter-jacket-001",
  "title": "Winter Jacket",
  "inventory": {
    "storeA": 12,
    "storeB": 1,
    "storeC": 5
  },
  [...]
}
```

You can define aliases for specific store keys and use them in an `aq` expression to filter results by store availability:

```json
{
  "q": "winter jacket",
  "fieldAliases": {
    "burlington": "inventory.storeA", <1>
    "plattsburgh": "inventory.storeB"
  },
  "aq": "@burlington>0 AND @plattsburgh>0" <2>
}
```

<1> Maps the `burlington` name to the `storeA` key of the `inventory` dictionary field.

<2> Filters results to only include items in stock at both locations.

### Boost with ranking functions

You can also use [field aliases](https://docs.coveo.com/en/q1q94008.md) in [ranking functions](https://docs.coveo.com/en/237.md) to boost items based on dictionary field values.

For example, to boost products that have higher inventory at a specific store:

```json
{
  "q": "winter jacket",
  "fieldAliases": {
    "burlington": "inventory.storeA"
  },
  "rankingFunctions": [
    {
      "expression": "@burlington", <1>
      "normalizeWeight": true,
      "modifier": 200
    }
  ]
}
```

<1> Products with higher `inventory.storeA` values receive a ranking boost, surfacing items with more stock at the Burlington location.

> **Note**
>
> If you encounter a limitation in a specific use case, contact [Coveo Support](https://connect.coveo.com/s/case/Case/Default).