Use field aliases

This is for:

Developer

This is useful when you need to retrieve several values from the same dictionary field at once, which isn’t possible with the dictionaryFieldContext 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, you can retrieve both values simultaneously.

You can also use field aliases like non-dictionary fields in advanced query expressions (aq) for filtering and in ranking functions for boosting.

Example scenario

Suppose your index contains products with a price_list dictionary field that stores different prices for different customer types:

{
  "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 
// Token
{
  "dictionaryFieldContext": { "price_list": "vip" }
}

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

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

With field aliases, 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 
// 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
      }
    }
  ]
}

Comparison with dictionaryFieldContext

The dictionaryFieldContext parameter is the traditional way to retrieve dictionary field values. field aliases offer more flexibility but require search token authentication and are only supported by the Search API.

Aspect dictionaryFieldContext field aliases

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 only

Limitations

  • Wildcard access only: Currently, allowedDictionaryFieldKeys only supports the wildcard (["*"]) to grant access to all keys in a dictionary field. Fine-grained access control for specific keys (for example, ["regular", "vip"]) isn’t currently available.

  • Search tokens only: field aliases require search token authentication. API keys and platform tokens don’t support allowedDictionaryFieldKeys.

  • Search API only: field aliases are only supported in the Search API, not the Commerce API.

  • 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 can’t retrieve the default empty key ("") of a dictionary field.

How field aliases work

field aliases use a two-part model:

  1. Authorization: The search token defines which dictionary field keys users are allowed to access using the allowedDictionaryFieldKeys property.

  2. 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.

This separation gives you fine-grained control over access while keeping queries flexible.

Authorize access to dictionary field keys

Before users can query dictionary field keys with field aliases, you must authorize access in their search token.

Use the allowedDictionaryFieldKeys property to specify which dictionary fields and keys users can access.

{
  "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.
2 The wildcard ["*"] grants access to all keys in the price_list dictionary field.

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:

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

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

{
  "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 just like normal fields. For example, you can use @regular_price in a result template, in an aq expression to filter results, or in a ranking function to boost results.

Use aliases in query expressions

field aliases are designed to work like non-dictionary fields. Once defined, you can reference them with the @ prefix in query expressions and ranking functions.

Filter with aq

Suppose your index contains products with an inventory dictionary field that stores stock quantities for different store locations:

{
  "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:

{
  "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 in ranking functions to boost items based on dictionary field values.

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

{
  "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.