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:
- In your Admin Panel, go to Configuration > Search Engines and click See indices.
- On the Indices tab, click the three dots on the index card, next to the index name. A dropdown menu will appear.
- Click on Field name mapping.
- 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
pricerow, for example, already containsprix,precio,prezzoandpreis.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_fieldon the left,different_name_in_the_feed, other field nameon the right.For example:
- Your product data feed calls the fields
pvp, fabricante, familia. - Doofinder indexes them as
price, brand, categories.
Add
pvpto the Field Aliases of thepricerow,fabricantetobrandandfamiliatocategories. - Your product data feed calls the fields
- 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:
mpnandgtin, 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.
- Click the "+Add new field" button.
- Under Normalized Field Name, type the name you want the field indexed under in Doofinder.
- 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:
idfromproduct_idtitlefromnamepricefrombase_price
xml in-feed field example:
<color> black </color>
Deep Field Mapping
Used for mapping nested attributes within an object or list:
colorfromattributes.colortypefromcustom_fields.specifications.typeattributesfromcustom_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:
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:
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):
- Temporarily remove the mappings from that object in Field name mapping.
- Save and Index. The full object will reappear in your feed. Remember, they only disappear from the index.
- Review its structure and add the desired fields.
- Re-apply and apply new mappings and save.