Metafield Filters

Shopify metafields allow you to store custom data on products (materials, care instructions, certifications, etc.). FilterIQ can turn any metafield into a filterable attribute.

How Metafield Filters Work

When you create a filter from a metafield, the app:

Reads the metafield values from your products during indexing
Indexes those values as filterable attributes in the search engine
Generates filter options based on the unique values found
Displays the filter on your storefront using the appropriate filter type

Supported Metafield Types

Shopify Metafield Type	Filter Display	Example
Single-line text	Checkbox list	Material: Cotton, Polyester, Silk
List of text values	Checkbox list	Certifications: Organic, Fair Trade
Number (integer)	Range slider	Thread count: 200-1000
Number (decimal)	Range slider	Weight: 0.5-5.0 kg
True/False	Boolean toggle	Vegan: Yes/No
Rating	Star rating	Review rating: 1-5
Color	Color swatch	Primary color

Creating a Metafield Filter

Step 1: Ensure Metafield Definitions Exist

Your metafields must have Shopify metafield definitions. Go to Shopify Admin > Settings > Custom data > Products to see your existing definitions.

Step 2: Add the Filter

Go to Filters in the app dashboard
Click Add Filter
In the data source dropdown, select Metafield
Choose the metafield namespace and key (e.g., custom.material)
Select the display type (checkbox, range slider, etc.)
Configure the filter label and options
Click Save

Step 3: Re-index Products

After adding a metafield filter, you may need to trigger a re-sync to index the new metafield values. Go to Settings > Sync Status and click Re-sync Products.

Step 4: Publish

Click Publish to Storefront to make the new filter available to shoppers.

Metafield Doctor

The Metafield Doctor is a built-in tool that analyzes your product catalog and suggests which metafields would make good filters.

What It Does

Scans your products for existing metafield data
Identifies metafields with enough unique values to be useful as filters
Suggests the optimal filter type for each metafield
Calculates a data health score showing how completely your products have the metafield populated

How to Use It

Go to Filters > Metafield Doctor (requires a paid plan)
Click Scan Products
Review the suggestions
Click Create Filter next to any suggestion you want to use

Data Health Score

The Metafield Doctor calculates how well your product data supports filtering:

Score	Meaning
90-100%	Excellent -- nearly all products have this metafield populated
70-89%	Good -- most products have this metafield, some gaps
50-69%	Fair -- significant gaps; some products will not appear when this filter is used
Below 50%	Poor -- consider populating more products before using as a filter

Safety Guarantee

The Metafield Doctor only writes to the searchfilters.* namespace. It never modifies core Shopify product fields (title, description, vendor, product_type, handle, tags, or images). All changes are reversible via the rollback endpoint.

Best Practices

Check data coverage before creating metafield filters -- A filter is only useful if most products have the metafield populated
Use consistent values -- Metafield values like "Red", "red", and "RED" will create separate filter options unless you configure merge groups
Start with high-coverage metafields -- Create filters for metafields that 80%+ of your products have populated
Test on your storefront -- After publishing, verify the filter options match what you expect