Field Aliases

Field aliases let you expose consumer-friendly field names in the API while keeping your Elasticsearch mapping unchanged. Translation is automatic and bidirectional — aliases are converted to real field names before querying Elasticsearch, and real field names are converted back to aliases in the response.

Configuration

Define aliases using the field property in the fields config for each index:

indexes:
  collections:
    engine: elasticsearch
    host: https://elasticsearch.example.com
    indexName: museum_collections
    fields:
      country:
        field: placeCountry
      region:
        field: placeRegion
      coords:
        field: placeCoordinates

With this config, API consumers use country and the API translates it to placeCountry for Elasticsearch.

Aliases can be combined with other field properties (weight, searchable):

fields:
  country:
    field: placeCountry
    weight: 5

How translation works

Inbound (request)

When a request comes in, alias field names in the following parameters are translated to Elasticsearch field names:

• sort keys — {"country":"asc"} → {"placeCountry":"asc"}
• facets values — country,region → placeCountry,placeRegion
• filters keys — {"country":"Scotland"} → {"placeCountry":"Scotland"}
• boosts keys — {"country":5} → {"placeCountry":5}
• fields values — country,title → placeCountry,title
• histogram keys — {"country":100} → {"placeCountry":100}
• geoGrid.field — coords → placeCoordinates
• Facet endpoint :field path parameter — /facets/country → queries placeCountry
• Facet endpoint filters keys

Outbound (response)

Elasticsearch field names are translated back to aliases in:

• facets keys — {"placeCountry":[...]} → {"country":[...]}
• histograms keys
• _highlights keys in each hit
• _highlights keys in geo map sample hits

Passthrough behavior

• Fields that are not aliases pass through unchanged in both directions
• When no fields with field are configured for an index, the alias map has zero overhead — no translation is performed
• Real ES field names can still be used alongside aliases (they pass through as-is)

Examples

Given the alias config above:

# Filter using an alias
curl "https://search-api-elysia-production.up.railway.app/collections/search?q=castle&filters=%7B%22country%22%3A%22Scotland%22%7D"

# Facets using aliases
curl "https://search-api-elysia-production.up.railway.app/collections/search?q=&facets=country,region"

# Facet search using an alias
curl "https://search-api-elysia-production.up.railway.app/collections/facets/country?q=sc"

# Sort using an alias
curl "https://search-api-elysia-production.up.railway.app/collections/search?q=&sort=%7B%22country%22%3A%22asc%22%7D"

In all cases, the response uses the alias names (country, region) rather than the Elasticsearch names (placeCountry, placeRegion).