Request for Comment: Faceted Filtering

[morganmccunn]

Currently in the unstable version of the Storefront API, you'll notice changes to support filtering products within a collection! Before we commit this to a version of the API, we want your feedback to ensure this is useful and extensible:

• Is the current proposed schema helpful for achieving desired filtering functionality?
• If not, what changes would you like to see to this schema?
• Where else would you like to see filtering functionality in the API?
• How would you expect Shopify to help you integrate with the new filtering API?

Below is the schema you would use to build your query to filter for the desired products:

type Collection {
  products(
    first: Int
    after: String
    last: Int
    before: String
    reverse: Boolean = false
    sortKey: ProductCollectionSortKeys = COLLECTION_DEFAULT
    filters: [ProductFilter!]
  ): ProductConnection!
}

input ProductFilter {
  inStock: Boolean
  variantOption: VariantOptionFilter
  productType: String
  productVendor: String
  price: PriceRangeFilter
}

input VariantOptionFilter {
  name: String!
  value: String!
}

input PriceRangeFilter {
  min: Float = 0.0
  max: Float
}

Below is the schema for returning the available filters that you can use to dynamically build your filters based on how a merchant has set up their products in the admin:

type ProductConnection {
  edges: [ProductEdge!]!
  pageInfo: PageInfo!
  facets: [FilterGroup!]!
}

type FilterGroup {
  id: String!
  label: String!
  type: FilterType!
  values: [FilterValue!]!
}

type FilterValue {
  id: String!
  label: String!
  count: Integer!
  filterParams: JSON!
}

enum FilterType {
  LIST
  PRICE_RANGE
}

Specifically, the filterParams: JSON! field is meant to be a machine-readable field to help with building a valid ProductFilter input. Opaque JSON was used to make the FilterValue type generic so it wasn't locked to just filtering on products. We're curious what you think about this:

• What issues arise from using opaque JSON?
• Would making use of interfaces and union types make the API more approachable?

Let us know what you think!

[isAdrisal]

Looking forward to this update! The one key feature that's missing is the ability to filter based on product tags. Merchants often want to create their own filter facets such as style or season, which is typically solved in third-party apps with prefixed/named tags such as style:foo and season:bar.

This Storefront API approach will unfortunately not meet that common use case without support for tags.

[morganmccunn]

Hey @isAdrisal thanks for the feedback! Is the only reason for tag filtering because of historical use for custom filters from 3p apps? Are there any other use cases that wouldn't necessarily be attached to product data directly?

[isAdrisal]

Hi @morganmccunn, no problem! I wouldn't necessarily categorise tag-based filters as 'historical' as they are very much a current and future requirement for many merchants — granted, it is a problem that has historically not been solvable using native Shopify APIs.

The use of tags to decorate products with additional metadata that does not have a matching native Product field is a hugely common use case in Shopify. Exactly what filter group/values are added through tags will vary from merchant to merchant. Metafields are of course also available to store this information, but equally not available to filter on through this new API (to my knowledge).

The big opportunity here is to remove the need for stores to rely on third-party apps and the apps' external-to-Shopify product database and APIs in order to create filter functionality that meets their needs. Shopify already has all of the required information within its own product database, with the only challenge being able to access it through APIs such as the one we're discussing.

Thanks for replying and I'm looking forward to seeing how this API looks in its final release (with fingers crossed!).

[kusumkanwar2]

@carolinjahn FYI

[justinmetros]

Is the current proposed schema helpful for achieving desired filtering functionality?

Being able to filter when directly querying a collection is a huge step forward. We had to jump through quite a few hoops to get our filters working on our Storefront API implementation.

what changes would you like to see to this schema?

It would be really useful to have product tags available on the ProductFilter input.

[morganmccunn]

Hey @justinmetros, I'd love to understand what kind of filtering options you'd like to store in product tags that you wouldn't be able to store as other product data directly? Wondering if the only use for product tags is because of historical reasons of filtering limitations or not! Thanks!!

[evaldas-raisutis]

Hi, I can chime in with my two cents based on experience building for Shopify Plus merchants. For merchants selling jewelry, we often need to add additional filter options such as:

• Category (usually we put the data in a metafields or a prefixed tag)
• Sub-Category (usually we put the data in a metafields or a prefixed tag)
• Metal / Stone / Material (usually we put the data in a metafields or a prefixed tag)
• Series / Collection (usually we put the data in a metafields or a prefixed tag)

This is of course in addition to filter options which can come product existing product/variant fields

• Size / Color / Style (variant options)
• Type (product type)
• Price (variant)

In all cases, today we have to either install an existing product search/filter app or build a custom app for clients who need this kind of filtering functionality on collection and search pages. These days we refer to Clerk as go-to, since most of our clients and Danish and they're based in Denmark.

If Shopify could handle these (in my opinion simple) filtering requirements, that's one less app for them to install and a big win for Shopify, because of happier clients.

[kusumkanwar2]

@carolinjahn

[bodog]

I'll have to give +1 to the idea that product tags are a fundamental use case for the vast majority of merchants to flexibly be able to create facets and dimensions. Especially in key:value types.

Not having the ability to query a collection by tag facets makes using the Storefront API a non-starter for most merchants we work with. It forces us onto third-party search solutions every time.

[appscompany]

Apart from adding the tags to the filters, it will be nice to get the number of products count when filters are applied.

[stewartknapman]

As others have already mentioned here having the ability to filter by tag and/or metafields is pretty important.

These are some real world examples, from some of my clients, of things that need to be filtered on collections—outside of price, variant option, type, or vendor:

• A car parts company that has products that work on different makes and models. Customer wants to be able to filter the collection by their make and model. This information makes the most sense to be stored against the product as a tag: product can have many makes or models; no extra processing needed on the frontend to parse a comma separated string or JSON from a metafield; it's easy for the merchant to maintain.
• An umbrella company that offers different products that vary in size. The customer wants to see all products with a certain open diameter. The size could be a tag but the new metafields dimension type probably makes more sense.
• A temporary tattoo company that offers different styles and inks. The customer could be viewing the animals collection and want to filter all the products that have glitter, or are water colour, or are red. These are usually attributes that don't change the price of the product so make no sense to be a variant option. The most appropriate place to store this information is as a tag or a metafield.

[dinhcuong2209]

Something is wrong here, i have installed Shopify GraphiQL App on my site. Document https://shopify.dev/custom-storefronts/products/filter-products#query-products-by-vendor

[morganmccunn]

Thanks for the flag - we'll take a look and see if we can reproduce.

[patrickdaley]

Same issue here, tested with productVendor and variantOption.

[patrick91]

I've seen this too, and I think it might happen when vendors is not filterable, for example I don't see vendor here:

not sure how to enable it as a filter though

[brendastorer]

This is also the number one customization request I get from merchants. I'm finding that I cannot use any of the new 2.0 filters at all because they don't integrate with tag filtering, and the flexibility of tag filtering wins out. The new filter url params do not appear to work on urls that have tag filtering applied (see screenshot below, which is the latest Dawn out of the box). There are only two products with the tag "banana" and the filters still show number results based on the full collection, and the price filter that is applied isn't filtering out the $1.00 product like I would expect it to. This also means any link in a navigation to a collection that is filtered by tag can't use the new collection filters. This has made the new filters unusable now for my merchants. Some workarounds I've done are to generate tags based on the vendor name to be able to filter by brand, and are now looking to utilize tags to be able to add our own "availability" and "product type" filters in the same way.

Two examples of custom category filters for stores that I am working on that are using tag filters:

Sustainable Grocery Store

• filter by Dietary Concerns (e.g. Paleo, Gluten-Free), Certifications (e.g. Organic, Fair Trade), Coffee Roast Level (e.g. Light, Medium, Dark), Brand (converting vendor name to a tag for this)

Streaming Travel Seminars

• filter by Region (e.g. Europe, Asia), Genres (e.g. Literature, Archaeology), Expert/Host name (converting vendor name to a tag for this)

Besides this limitation, I've been really excited about all the other 2.0 upgrades. Keep up the good work!

[davidkensell]

To add yet more real world use cases of merchants depending on tag filtering:

An apparel company filtering a "Dress" collection of all Product Type == Dress with Style_Maxi, Style_T-Shirt, Style_Long Sleeve, etc.

A wellness company filtering by Concern. Concern_Tiredness, Concern_Soreness, Concern_Nausea, etc.

A maternity brand filtering bras by Feature. Feature_Pumping, Feature_Active, Feature_Cooling, etc.

A maternity brand filtering bras by Style. Style_Bralette, Style_Plunge, Style_T-Shirt, etc.

A medical orthotics company wanting to filter products based on Insurance coverage. Insured_Anthem, Insured_Blue Cross, etc.

A meal delivery service with diet and ingredient filtering. Lifestyle_Gluten Free, Lifestyle_Vegan, Meat_Chicken, Meat_Beef, etc.

In my experience, products frequently have multiple tags assigned to them, and diff collections may use diff tag filters. The filtering happens at the product level, not the variant level. Product metafields could prbly work; but almost all the apps and themes with filtering solutions use tags, since they've been so much more accessible via the UI Admin historically. Using a schema like "Prefix_Display Name" keeps tags that aren't meant to be front-facing out of the UI.

A pretty nice solution is the one the app Boost uses, where you can build different filter trees and then assign trees to different collections.

[appscompany]

Hi,
Any update on this issue on combining tags with filtering functionality?

[alinad-am]

+1

[sja87]

any update on this? Can't use this for my client at the moment :(

[morganmccunn]

Thanks for all the feedback so far! A quick update here - we are looking into the option of leveraging metafields as part of filtering to provide an additional parameter for filtering. I understand that tags are currently in use for many reasons, but the unstructured nature of tags make them difficult to leverage. Metafields with various types will provide additional flexibility and transparency for approaching how filtering works. It sounds like overall there are no major concerns about the approach of the schema itself though so I'm working with the team to see when we can get this work completed. I'm hoping this can be added to the upcoming storefront API version.

[patryk-smc]

I'd like to add that having product count surfaced in collection (both filtered and unfiltered) and search results would be huge. Also, page-based navigation would be nice to have. According to my knowledge, it is not possible to have pagination with numbered pages built with only Storefront API. FYI — Algolia comes with those features, and Shopify Liquid Storefront as well.

[PaulNewton]

@morganmccunn If this goes in will these metafields be part of search?
At least for the onlinestore channel a strong side-effect of tags is showing in search even if unintented by merchants that add them, and can be a hard fix when intentional such as accounting for the limitations of typo tolerance, or the issue with OS2 JSON templates content not being in search.

[isAdrisal]

Another key limitation of metafields is that they're not available in Shopify Scripts, or returned as part of the product.js API. The structured nature of metafields is certainly an upgrade vs tags, so long as there's a longer-term focus on improving the usability of metafields in both the Admin and front-end to replace the need for tags more generally.

[jschwarzinger]

Echoing others, I love the new updates - I just wish I could use the existing Dawn sorting/filtering with more than 1000 products.

[cyrilchapon]

@morganmccunn thanks for the update, finally some "official" news around it. Being a dev myself, metafields (paired with metafields-UI) seems a legit upgrade for too-many-stuff put in tags in the past, for various reasons above. I'm dying to see this landed in filtering system; be it tag of metafields.

Though, if I can go for a bit of feedback, everyone in this github thread is capable of understanding this like me, because everyone out there is a developer. But not everyone is : threads like this one => https://community.shopify.com/c/online-store-2-0/filter-by-tag-in-dawn-theme/td-p/1264678/page/6 definitely deserve an answer !

[Willowmoon8]

Thank you for working on this! Another case of needing to be able to filter by tags (or maybe metafields) is my gift/party supply store where I need to filter by party theme, age range, holiday/occasion, etc. I've been holding off on updating to 2.0 since finding out that tag filters don't seem to be included in the new system. I never had any trouble with the old tag system which worked perfectly - if I needed to use tags for admin purposes that I didn't want to show up on the storefront I would just use "unless tag contains..." to prevent it from being displayed. I hope that tag filtering can be restored as otherwise 2.0 looks great but this is a big important missing piece that essentially renders it unusable to me, so I appreciate all who are working on this!

[PaulNewton]

I understand that tags are currently in use for many reasons, but the unstructured nature of tags make them difficult to leverage

In addition to that point by @morganmccunn while we all love tags as a hammer for workarounds they can be a double edge sword that too easily exposes back end organizational info or private data to front ends ,sensitive or not , because it's often forgotten to put restraints on that tag data or having any maintenance process that validates them when staff enters them in an admin. And for themes the underscore convention to suppress tags is not universal in themes, or able to be enforced in the admin. And tags cannot be omitted from the ajax apis.

[patryk-smc]

New filtering in liquid storefronts is limited to collections with up to 1000 products. Will Storefront API filtering work with collections larger than 1000 products?

[NoskiNoski]

For us, the biggest limitation is the limit of 1000 products in the collection. We would like to be able to use native Shopify filters and with this limit we are not able to.

[jschwarzinger]

Same here. I've been scratching my head why the Dawn filter disappears when I view all [2000+] products. Now I understand why - a Shopify limitation. I wish I knew about the limit before I started building with the theme!

[TimKerre]

Same for me. Filters are literally made to break down large collections so I really can't understand why they would put a limit of 1000 products on the filter..

[isAdrisal]

Hey @morganmccunn, great to see that the metafields MVP has been released (https://shopify.dev/themes/navigation-search/filtering#product-specific-filters)!

Quick question re: product-specific metafield filters. The docs include metafields in both the product-specific and variant-specific sections linked above, but the copy states the following within the product-specific table: Filter based on a specific variant metafield..

Is this a typo, and can you confirm that both product-level and variant-level metafields can be used in filters? (🤞)

[bitforcesrl]

the only meta you can add in the admin/navigation/filter config are product meta not variant meta

[kfalkiewicz]

Nice to see new metafield filtering, but still there is a room to improve. For example string value in this form "value1,value2" will be displayed in storefront filters as 1 option, not 2 with for me looks like a bad decision. Lack of proper "custom" filtering for things like age, groups etc. is deal breaker. 1k items per collection limit is also something that shouldn't happen.

[mkromann]

Yea. This is a an issue we are facing as well.

The documentation says that comma-separated values are supported but it doesn't seem like it at this point:

[cocoahero]

Hi there. Just want to clarify something that perhaps our docs are not illustrating well. The comma-delimited values are for the Liquid / URL based filters only. Within the Storefront API, you can achieve filtering by multiple values by providing multiple MetafieldFilter objects for the same namespace and key. For example:

query Filtering($filters: [ProductFilter!]!) {
  collection(handle: "staff-picks") {
    products(filters: $filters) {
      edges {
        node {
          id
        }
      }
    }
  }
}

Variables:

{
  "filters": [
    {
      "productMetafield": {
        "namespace": "my_fields",
        "key": "made_in",
        "value": "usa"
      }
    },
    {
      "productMetafield": {
        "namespace": "my_fields",
        "key": "made_in",
        "value": "canada"
      }
    }
  ]
}

[ProDevArdi]

Filtering by metafield is a great addition. I wanted to suggest an addition.
I think adding rating and boolean type metafields to the types will be a great addition.
Right now, I use number_integer as a workaround, but it would make everything easier if these two were also available.

[kfalkiewicz]

Nope, because I need to have product in 3-4 different age groups. For example when user selects 4 years old + my product that is 3 years old + should also be visible. I could create 7 different metafields that that's not a point. It would break filtering to different "fields" and I want to have 1 age filter and that's it. On other platform I used tags for this, but now this isn't possible. For me, the best solution would be support for JSON objects or strings with comma separated items that would be treated as list items, not as a single value.

[bredowmax]

@kfalkiewicz fully agree with your point of supporting multiple values for the same product, for example “Great for: Dinner, Breakfast” —> 1. Dinner, 2. Breakfast. Well, kind of how tags work, but inside Metafields. “Metatags” :-)

That said I fully support @Ardavan947 request for a simple Boolean. Would make our lives so much easier with a simple checkbox “Bio ✅”

[ProDevArdi]

@kfalkiewicz Oh, yeah, I understand now. This will be very useful for me too actually.

[tkenalas]

@kfalkiewicz fully agree with your point of supporting multiple values for the same product, for example “Great for: Dinner, Breakfast” —> 1. Dinner, 2. Breakfast. Well, kind of how tags work, but inside Metafields. “Metatags” :-)

That said I fully support @Ardavan947 request for a simple Boolean. Would make our lives so much easier with a simple checkbox “Bio ✅”

+1, this is my biggest issue right now aside from the 1k limit (and the 20 metafield filter limit). I'm a fan of the idea of metafields replacing tags as the main filtering mechanism, but there are many use cases that want for a "list" content type to exist and be filter-able.

In my immediate case, a client has a store that uses "Ceritifcations_xxxx" tags to list out everything a product qualifies under, and customers can filter to the one(s) they care about. There are enough different certs that making one metafield for each would both be unwieldy and also violate the 20 max limit.

[davidkensell]

the best solution would be support for JSON objects or strings with comma separated items that would be treated as list items, not as a single value.
a client has a store that uses "Ceritifcations_xxxx" tags to list out everything a product qualifies under, and customers can filter to the one(s) they care about

Def sounds like a JSON object to me! Maybe we could have a "Filter" metafield type where Key is the filter, and Value is the array of options the product qualifies for. So, { "Certifications": ["Cert1", "Cert2", "Cert3" ] }.

[uibaseio]

Filtering with productType and productVendor literally doesn't work both in my own project, and on Shopify's own GraphQL playground when adding the query variables exactly as shown in the tutorial and at the top of this page. Why is this broken?

[patrick91]

Is there anything specific one needs to do to enable filters? At the moment when I ask for filters for a specific collection I only get these:

{
filters: [
    {
    label: 'Availability',
    values: [
        { count: 4, label: 'In stock' },
        { count: 0, label: 'Out of stock' }
    ]
    },
    { label: 'Price', values: [ { count: 0, label: 'Price' } ] }
],
}

I want to be able to filter by vendor name and by attributes :)

[uibaseio]

Found out the answer in the end after getting really frustrated 😂 go to navigation in your online store and you can add filters. By default they’re not enabled

[patrick91]

awesome! thank you!

[r0busta]

Thanks! You saved my day 🙌

For those wondering why there's no such option, you need to add the Dawn theme to your store to enable the 2.0 features.

[patrick91]

Will support for filtering all products be added at some point? Sometimes we don't want to filter by collection first :)

[bitforcesrl]

the suggestion is to create a collection which contains the whole catalog, this will work but you've the size limit in filtering

[cocoahero]

Hi everyone! Thanks again for all your wonderful feedback. Just wanted to announce a few updates:

• Support for filtering by product and variant metafields has been added! As of right now, only single_line_text_field, number_integer, and number_decimal metafields are supported. Support for boolean metafields will be coming soon.
• The filterJson field has been renamed to input to better represent its purpose.
• The filtering functionality will be a part of the 2022-01 release and now considered stable API!

[kusumkanwar2]

Collection metafields are coming soon, in January 2022!!

[Ale1234509]

@cocoahero Hello, will the Text List or Array metafield type be released in 2022-01?
Thank you very much for your support

[iMac2021]

Hello, I have further questions about this

With the Metafiled Collection, there will then also be the option of storing metafiles as a condition for the categorization so that the categories are automatically filled? It is currently product day.

I would also be interested in whether the limit of currently 20 filters will be lifted?
More precisely, will there be extensions of infinite filters for individual collections that are created?

It would also be great if you could sort the metafileds in the backend.

Thank you for the answer, :-) Have a Merry Christmas to everyone

[mkromann]

The current single-line text fields are designed for simple values like Material: Cotton or Made In: Canada which translate well to options to filter by in a dropdown list. I believe what you are asking for is a Text List or Array metafield type, which we currently do not support but will be coming soon.

Seriously looking forward Text List / Array metafield.

[lowpressurestudio]

The current single-line text fields are designed for simple values like Material: Cotton or Made In: Canada which translate well to options to filter by in a dropdown list. I believe what you are asking for is a Text List or Array metafield type, which we currently do not support but will be coming soon.

Any update or ETA for the Text List / Array type? We're launching 3 store updates end of July — hoping not to have to write a workaround...

[bitforcesrl]

PERFORMANCES issues
DEMO: https://bitforce-headless-shopify.herokuapp.com/collections/sale (Wait for the heroku cold start)
i've implemented filters updating the serverState filter props when the user toggle filters. I think this is the correct approach.
On the linked demo you can see that the /react call needed to render the new list of products is slow >1s i know that with the server cache + local API on hydrogen that will be faster but for the first render and deploy outside oxygen this machienry is slow. Any suggestion or thoughts on this?

@morganmccunn you can update the first post with the possibility to filter on metafields that are now working.
I've read above some common issues that i agree like

• the needs to filter on the whole catalog and not only inside a collection (create a collection with all prods is a workaround)
• we need a way to get facets for the whole collections so this query:

collectionByHandle(handle: $handle) {
      handle
      products(first: $numProducts) {
        filters {
          id
          label
          type
          values {
            id
            label
            count
            input
          }
        }
      }
    }
    ```
 Should work without any first limit
    

[bitforcesrl]

HOW TO Filtering facets:
When the user apply some filter would be necessary to retrieve the new facets available considering that filter applied.
Ex if the user selcts the brand Adidas in the collection shoes i'd like to fetch again for facets excluding color and sizes for other brands.
The query is this one which works to retrieve filtered products, but not filtered facets

  query Facets(
    $handle: String!
    $country: CountryCode
    $numProducts: Int!
    $productFilters: [ProductFilter!] = []
  ) @inContext(country: $country) {
    collectionByHandle(handle: $handle) {
      handle
      products(first: $numProducts, filters: $productFilters) {
        edges {node {handle: -->> THIS WORKS, ONLY ADIDAS SHOES}}}
        filters { -->> HERE WE'VE ALL FACETS FOR SHOES COLLECTION, NOT FILTERED WITH {"productVendor": "ADIDAS"}
          id
          label
          type
          values {
            id
            label
            count
            input
          }
        }
      }
    }
  }

vars

{
  "handle": "shoes",
  "numProducts": 100,
  "productFilters":[{"productVendor": "ADIDAS"}]
}```

[bitforcesrl]

ok, it seems to work for priceRange but not for the others do you have a list of facets type that are filtrable?