Search icon

Field Name Mapping

What is Field Name Mapping?

Doofinder indexes every product under a fixed set of field names, the ones listed in the Field name mapping panel: id, title, price, link, image_link, brand, categories and so on. id and title are required.

Your data feed does not have to use those names. Field name mapping is where you tell Doofinder what each field is called in your feed, so that a feed sending the product name as nom_produit is still indexed as title.

Each field already accepts several names, so a feed using common ones is recognized without any mapping. You only add a name when the one your feed uses is not already listed.

How to Add Field Name Mappings

You can access the Field name mapping section through the Admin Panel. Here’s how:

  1. In your Admin Panel, go to Configuration > Search Engines and click See indices.
  2. On the Indices tab, click the three dots on the index card, next to the index name. A dropdown menu will appear.
  3. Click on Field name mapping.
  4. access field name mapping in the Admin Panel by clicking on Configuration > Search Engines > See indices > three dots on the index card > click on Field Name Mapping.
  5. The Field Name Mapping pop-up will appear with two sections:
    • Normalized Field Name: indicates how the field is indexed in Doofinder.
    • Field Aliases: indicates how the field appears in your feed.

      Each normalized field already has a list of aliases filled in, covering the most common names in English, Spanish, French, Italian and German. The price row, for example, already contains prix, precio, prezzo and preis.

      You only need to add an alias when the name your feed uses is not already listed in that row. The placeholders in the panel show which name goes where: my_indexed_field on the left, different_name_in_the_feed, other field name on the right.

      For example:

      • Your product data feed calls the fields pvp, fabricante, familia.
      • Doofinder indexes them as price, brand, categories.

      Add pvp to the Field Aliases of the price row, fabricante to brand and familia to categories.

    enter field normalized name and aliases
  6. Save and index.

    The aliases take effect in the next indexing. From then on, Doofinder reads that field from your feed under its normalized name.

Deleting a line stops that mapping from being applied in the next indexing.

Reset to defaults at the bottom of the panel restores the original alias list for every field and discards the aliases you added. A confirmation window appears before it is applied.

When You Need to Map a Field

Doofinder builds the result card from title, link, image_link, price and sale_price. If your feed calls any of these something else, add that name to the Field Aliases of the matching row. This is what field name mapping is for.

Three more are worth mapping:

  • mpn and gtin, when your feed carries the product reference or part number under another name. Doofinder treats both as reference fields, so a customer can search by part of the reference. See Search Fields.
  • categories, when your feed sends the category tree under another name. The category filters in the Layer read this field, and it expects the hierarchical format described in Category Attribute.

Anything else in your feed is indexed under the name it already has. A color or a size field works in filters and in search as it is, with no mapping.

If the value you need is inside a nested object, what you need is deep field mapping, not an alias.

How to Add New Fields

+Add new field creates a normalized field that is not in the list. You need it for deep field mapping, to take a value out of a nested object and index it as a first-level field. A field that is already a first-level field in your feed does not need this.

  1. Click the "+Add new field" button.
  2. Under Normalized Field Name, type the name you want the field indexed under in Doofinder.
  3. Under Field Aliases, type the path to the value in your feed, for example custom_fields.attributes.[name=color].value.

Field Name Mapping Types

Doofinder supports two types of field mapping:

Basic Field Mapping

Used for mapping simple fields:

  • id from product_id
  • title from name
  • price from base_price

xml in-feed field example:

<color> black </color> 

Deep Field Mapping

Used for mapping nested attributes within an object or list:

  • color from attributes.color
  • type from custom_fields.specifications.type
  • attributes from custom_fields.attributes

xml in-feed field example:

<attributes>
<color> black </color>
<size>L</size>
<category>clothing</category>
</attributes> 

With deep field mapping, you can access and extract attributes from their parent objects and create or assign aliases for them, just like first-level fields. This means they are no longer treated as nested attributes and can be used in filters, sorting, or rules.

How Does Deep Mapping Work?

There are three ways to map nested attributes:

  • Nested Fields

To access any nested attribute and use it as a first-level field, reference the full attribute path (there is no attribute level limitation): custom_fields.specifications.type

  • Indexing Arrays

To retrieve the first item from a list or array, use square brackets with a number (starting at 0): images.[0]

  • Filtering Arrays

To target specific items based on attribute values, use the following format: attributes.[name=color].value

This fetches the value of the item where name=color.

Your field name mapping will look like this:

Field Alias and Normalized Field Name example. Field Alias is custom_fields.images.[0], Normalized Field Name is main_image

Map all the nested values of an object that you want to use. Once saved and indexed, only the configured nested values will appear in the index, the remaining values, including the parent object itself, will no longer be included.

Learn by Example - How to Map Nested Values with Deep Field Mapping

Imagine you have a product data feed that looks like this:

{
  "id": "12345",
  "name": "Premium Wireless Headphones",
  "price": 299.99,
  "custom_fields": {
    "attributes": [
      {
        "name": "color",
        "value": "black"
      },
      {
        "name": "warranty",
        "value": "2 years"
      },
      {
        "name": "brand",
        "value": "AudioTech"
      }
    ],
    "specifications": [
      {
        "type": "battery_life",
        "value": "30 hours"
      },
      {
        "type": "connectivity",
        "value": "Bluetooth 5.0"
      }
    ],
    "images": [
      "https://example.com/headphones-1.jpg",
      "https://example.com/headphones-2.jpg",
      "https://example.com/headphones-3.jpg"
    ],
    "variants": [
      {
        "sku": "WH-001-BLK",
        "price": 299.99,
        "stock": 50
      },
      {
        "sku": "WH-001-WHT", 
        "price": 299.99,
        "stock": 25
      }
    ]
  }
}

You want to map:

  • The second image, using indexing: custom_fields.images.[1]

  • The Bluetooth 5.0 value using filter: custom_fields.specifications.[type=connectivity].value

Your field name mapping will look like this:

With the example, the field name mapping section shows, the Normalized Field Names which are connectivity and main_image and the Field Aliases which are custom_fields.specifications.[type=connectivity].value and custom_fields.images.[1]

This is the feed output:

{
  "id": "product_id",
  "name": "title",
  "price": "base_price",
  "custom_fields.attributes.[name=color].value": "product_color",
  "custom_fields.attributes.[name=brand].value": "brand_name", 
  "custom_fields.images.[1]": "main_image",
  "custom_fields.variants.[0].sku": "primary_sku",
  "custom_fields.specifications.[type=connectivity].value": "connectivity"
}

This is the output in Results Preview in the product information box:

{
  "product_id": "12345",
  "title": "Premium Wireless Headphones",
  "base_price": 299.99,
  "product_color": "black",
  "brand_name": "AudioTech",
  "main_image": "https://example.com/headphones-1.jpg",
  "primary_sku": "WH-001-BLK",
  "connectivity": "Bluetooth 5.0"
}

Always map all nested values you want to keep. Once indexed, unmapped values (and the parent object) will disappear from the index.

Troubleshooting

An Error Appears During First Indexation

To get your data feed properly indexed, Doofinder requires the ID and Title. If one or both of them have a field name in your feed that is not in the expected Field Aliases, Doofinder will not recognize it, and the index will deliver an error message such as this:

"Too much warnings. Last warning: id attribute(s) missing" See more details

To fix it, open Field name mapping and add the name your feed uses to the Field Aliases of the id or title row. Save the changes and index again.

The Layer Doesn’t Show Some Information in the Results

Doofinder should show the following fields in the results:

  • image_link
  • title
  • price
  • sale_price (if exists)
  • link

If some of this data is missing, the problem could be a non-recognized field name in your feed. To fix it, detect the non-recognized field name and configure the alias.

For instance, if your feed sends the product name in a field called product_name, add product_name to the Field Aliases of the title row.

If you do not know what the field is called in your feed, open the feed and check it.

How to Recover an Object After Deep Field Mapping

If you have already mapped some nested values and want to add more but can’t recall which values are available (and you don’t have access to the full feed):

  1. Temporarily remove the mappings from that object in Field name mapping.
  2. Save and Index. The full object will reappear in your feed. Remember, they only disappear from the index.
  3. Review its structure and add the desired fields.
  4. Re-apply and apply new mappings and save.

Last updated: 05/11/2026

Did you find this page helpful?