Shopify metafields

Search.io supports Shopify metafields. Adding metafields to Search.io can further improve your store’s search ranking and relevance, and display product metafield data in your search results.

Adding metafields to your Search.io collection

Your store must have the Search.io Shopify App installed. To install the app, follow these instructions.

Add a metafield to your schema

1. Log in to the Search.io Console.

2. Navigate to the Schema section.

3. Click Add metafield.

4. Select a metafield definition from the dropdown list. Only product and variant metafield definitions are supported. Refer to Shopify’s documentation if you need to add a metafield definition to your store.
5. Select Indexed if want the metafield to be searchable. Refer to the supported metafield content types for a list of content types that can be indexed.

6. Click Add metafield. Search.io creates the necessary schema fields for the selected metafield definition. Metafields containing values which need to be represented in different ways will generate multiple fields.

7. Repeat steps 3-6 to sync additional metafields, or click Sync products to trigger a full products sync with Search.io. Triggering a sync updates the records in your collection with the new metafield values.

A full products sync can take several minutes to a few hours, depending on the number of products in your store.

Supported metafield types

The following table shows the schema field mappings for each metafield type. Note that some metafields may be mapped to multiple schema fields.

Product metafields are mapped to schema fields with prefix metafield_{namespace}_{key}.

Variant metafields are mapped to array schema fields with prefix variant_metafield_{namespace}_{key}.

Metafield content types	Description	Search.io schema types	Can be indexed
Single line text	A single-line text field.	String	Yes
Multi-line text	A multi-line text field.	String	Yes
Page reference	A reference to a page on the online store. e.g. gid://shopify/OnlineStorePage/1	String	Yes
Variant reference	A reference to a product variant on the online store. e.g. gid://shopify/ProductVariant/1	String	Yes
Integer	A whole number in the range of +/-9,007,199,254,740,991.	Integer	No
Date	A date in ISO 8601 format without a presumed timezone.	Timestamp	No
Date and time	A date and time in ISO 8601 format without a presumed timezone.	Timestamp	No
JSON string	A JSON-formatted string. Note: The json_string type is deprecated but does still exist because it behaves differently from the new json type in Liquid.	String	Yes
Boolean	A true or false value.	Boolean	No
Color	The hexadecimal code for a color.	String	Yes
Weight	A value and a unit of weight. Valid unit values: oz, lb, g, kg	normalized field - Double The value in cubic meters. e.g. 0.1 raw field - String Contains the raw metafield value. E.g. {"value":100.0,"unit":"LITERS"} display field - String A friendly formatted string that can be used for display in a results view. e.g. 100 L	No
Volume	A value and a unit of volume. Valid unit values: ml, cl, l, m3 (cubic meters), us_fl_oz, us_pt, us_qt, us_gal, imp_fl_oz, imp_pt, imp_qt, imp_gal.	normalized field - Double The value in kilograms. e.g. 0.1 raw field - String Contains the raw metafield value. e.g. {"value":100.0,"unit":"GRAMS"} display field - String A friendly formatted string that can be used for display in a results view. e.g. 100 g	No
Dimension	A value and a unit of length. Valid unit values: in, ft, yd, mm, cm, m	normalized field - Double The value in cubic meters. e.g. 0.005 raw field - String Contains the raw metafield value. e.g. {"value":5,"unit":"MILLIMETERS"} display field - String A friendly formatted string that can be used for display in a results view. e.g. 5 mm	No
Rating	A rating measured on a specified decimal scale.	normalized field - Double The value. e.g. 3.5 raw field - String Contains the raw metafield value. e.g. {"value": "3.5", "scale_min": "1.0", "scale_max": "5.0"}	No

Customizing your search algorithm with metafields

Search.io works right out of the box for Shopify stores. Metafields can be used to further improve your store’s search relevance and ranking by customizing your search algorithm.

If a metafield has been configured to be indexed, you should add it to the textual relevance in your search settings so the metafield’s values can be used for textual relevance in search results.

Metafields can also be used to make ranking adjustments, to further fine-tune your search results.

Adding metafields to your search UI

Using a metafield as a filter

1. In the Search.io Console, click Shopify in the Integration section.

2. In the Filters section, click Add.

3. Select the metafield from the Field dropdown, and specify a Title.

4. Click Add filter.

   The filter will appear in your search preview.

   
5. Once you are happy with the search UI, click the Install button. Follow the installation instructions which are tailored to your configuration.

6. If you are manually installing Search.io into a live store, we recommend that you duplicate the active theme and first install the search UI to that theme. This lets you check everything is perfect before you push it live.

Displaying metafield values in the search results UI

This section covers an advanced topic, and requires:

• Basic knowledge of HTML and CSS,

• Familiarity with the Tempura template language.

1. In the Search.io Console, click Shopify in the Integration section.

2. Select the Custom option in the Search result template section.

3. Click Edit.

4. Select a template (e.g. Default) and click Next.

5. Add the schema field for the corresponding metafield to the HTML template. e.g. For a product field metafield with namespace and key my_fields.description, the corresponding schema field name is metafield_my_fields_description.

   Reference the schema field like this:

   {{ #expect metafield_my_fields_description }} {{#if metafield_my_fields_description}} metafield_my_fields_description {{/if}}

   The #expect annotation is required to prevent the template from erroring if the product does not contain a metafield. The display of the metafield is inside an #if statement to ensure that nothing is rendered if the product does not contain a metafield.
6. Click Save.

7. Once you are happy with the search UI, click the Install button. Follow the installation instructions which are tailored to your configuration.

8. If you are manually installing Search.io into a live store, we recommend that you duplicate the active theme and first install the search UI to that theme. This lets you check everything is perfect before you push it live.