Applies globally to item fields across an entire index

Companies can control the searchability of item fields from the Constructor dashboard. This directly impacts whether data is available to search against when a user submits a query on a company’s website.

For example, if a company configures the field color as searchable, then shoppers can search for items like “black shoes” or “red dress” and Constructor can retrieve and rank items with those colors.

Searchability and displayability

Searchability and displayability are two separate configurations that live in the same place in the Constructor dashboard. Similarly, they are two separate parameters when configuring via Constructor’s API.

A metadata field can be searchable but not displayable. For example, values for keywords might have a fuzzy or exact match, but don’t need to appear anywhere in the UI or API response. A metadata field can also be displayable but not searchable. For example, values for description can be shown but are not indexed for search due to the volume of the data.

Searchability types

There are three levels of searchability in Constructor: fuzzy, exact, and non-searchable. By default, newly added catalog fields are marked as non-searchable.

• Fuzzy searchability: Allows for flexibility with search terms. For example, if a user includes the color blue in their search query but spells it bleu, Constructor can still understand the intent of the query and retrieve and rank items that contain the value blue in their color field.
• Exact searchability: Would require the user to enter an exact match for a value for an associated item to be returned. For example, a search for the item ID 28193 would only return an item with that ID value.
• Non-searchable: Fields with this searchability are not available to query against. This setting is ideal for fields that contain sensitive data or fields that are not relevant to a user’s search (e.g., last_updated or internal_status).

⚙️

Manage searchability and displayability via API

In addition to managing searchability and displayability in the Constructor dashboard, your team can also create, update, and delete these configurations via our API.

Manage searchability

Navigate to Manage Searchability & Displayability

1. Select Workspace in the side menu of the Constructor dashboard, then select Indexes.
2. Locate the index you wish to configure.
3. Select Manage Searchability & Displayability to the right of the desired index.

Add a new searchability

1. Select + Add New in the top-right corner of the Manage Searchability & Displayability page.
2. On the pop-up, enter the name of the field you wish to configure. The list of available fields will filter as you type. Only fields included in the index catalog will appear in the list.
3. Once you locate the field, select it, then select Add in the bottom-right corner of the pop-up.
4. Next, in the Searchability section, select your desired searchability type. Learn more about these types here.
   • Note: By default, all new catalog fields are marked as non-searchable until they are configured.
5. Select Save changes in the top-right corner of the page.

Edit a searchability

1. Locate and select the field you wish to edit from the list on the left side of the page. You can use the search bar to filter for the field, or scroll to locate it.
2. In the Searchability section, select the new searchability type.
3. Select Save changes in the top-right corner of the page.

Delete a searchability

1. Locate and select the field you wish to edit from the list on the left side of the page. You can use the search bar to filter for the field, or scroll to locate it.
2. Select Delete configuration on the right side of the page. This option is located beneath the Save changes option.
3. On the pop-up, confirm your action by selecting Delete.

Note: If you ever need to reconfigure a field, simply follow the steps outlined in Add a new searchability section.

Manage displayability

Displayability refers to whether a metadata field is included in API responses for Search, Browse, and Collections, and if those field values can be exposed in the UI. You can configure displayability in the Constructor dash or via the API.

For example, marking fields like price, title, or brand as displayable ensures those product details can appear in an API response. If displayable fields are configured as facets, they can also appear as filters on results pages.

However, not all fields should be marked as displayable. Sensitive fields, such as profit_margin, should be kept non-displayable to prevent their exposure via API.

Configure displayability

1. Locate and select the field you wish to edit from the list on the left side of the page. You can use the search bar to filter for the field, or scroll to locate it.
2. In the Displayability section, turn on the Displayable toggle. If you wish to make the field non-displayable, then turn off the toggle.
3. Select Save changes in the top-right corner of the page.

Inherited displayability configurations

❗Inherited displayability only applies when configuring displayability using Constructor's API. It does not apply to configurations made in the Constructor dashboard.

If you create a searchability configuration but do not specify an explicit displayable value, it will inherit its displayable value from the nearest existing parent (deepest ancestor). If no parent configuration exists, the value defaults to False.

For example, say product_info has a displayability of False; however, product_info.prices has a displayability of True with content like {"CA": …, "US": …}. If you were create product_info.prices.CA but did not define displayability, it will inherit the value of True from product_info.prices.

⚠️ Please note: Inheritance is not dynamic, meaning that changing a parent's displayability later will not update existing children.

Configure displayability for hierarchical data

If your catalog has items with metadata fields that contain object fields with nested data, you can configure the displayability of those fields in the Constructor dash.

For example, dimensions is an object field in an item’s metadata. It contains three nested fields:

"metadata": {
    ...
    "color": "black",
    "dimensions": {
        "width": "10 cm",
        "height": "20 cm",
        "depth": "30 cm" 
    },
    ...
}

⚠️ Please note: object fields cannot be made searchable, only displayable.

1. Locate and select the object field you wish to edit from the list on the left side of the page. You can use the search bar to filter for the field, or scroll to locate it.
   • Note: Nested fields will have an object type in the field summary at the top of the page.
2. In the Displayability section, turn on the Displayable toggle. If making the field non-displayable, turn off the toggle.
3. Select Save changes in the top-right corner of the page.

Configure metadata hidden status

Merchandisers and company admins can manage the hidden status of a metadata field as part of the Displayability configuration.

Configuring a field as hidden will still add the field during an index build, but will not return the field in API responses unless explicitly requested via the fmt_options[hidden_fields] query parameter.

For example, an admin might choose to hide the price attribute because they have multiple regions and therefore multiple prices (e.g., price_1, price_2, price_3, etc.). However, when making a request for a user in Region 1, the admin can send fmt_options[hidden_fields]=price_1 as a query parameter.

⚠️ Please note: By default, the Hidden toggle for an attribute is turned off. If you enable the Hidden toggle for an attribute configured as displayable, but later turn off the Displayable toggle, then the Hidden toggle will also be turned off.

1. If necessary, locate and select the field you wish to edit from the list on the left side of the page. You can use the search bar to filter for the field, or scroll to locate it.
2. In the Displayability section, turn on the Hidden toggle.
3. Select Save changes in the top-right corner of the page.

🚧

Important

Changes to metadata field configurations take effect in search and browse requests once Constructor rebuilds indexes. Rebuild duration will depend on the size of your data set, including items, facets, rules, and other indexed data.