Skip to main content

Query using metafields

Use metafield values to find products, create automated collections, or search resources by specific criteria. This powerful querying capability turns your custom data into searchable, filterable attributes.

Anchor to RequirementsRequirements

Before using metafields to query, filtering must be enabled on the metafield definition. Without filtering enabled, queries return unfiltered results.

Anchor to Query syntax overviewQuery syntax overview

The following query patterns are available, depending on the metafield data type:

PatternDescription
Exact matchWorks for all types. Case-sensitive for text. Example: color:"blue"
Prefix matchText types only. Use * wildcard. Example: lapel_style:notch*
ExistsUse * alone to match resources where the metafield has any value. Example: color:*
NOTUse - or NOT to exclude matches. Use -field:* to find resources where a metafield has no value. Example: -color:"blue"
RangeNumeric and date types. Use >, <, >=, <=. Example: price:>100
BooleanUse true or false without quotes. Example: eco_friendly:true
ReferenceUse full GID format. Example: collection:"gid://shopify/Collection/123"
List valuesMatches if ANY value in the list matches. Example: tags:"organic"

Products, companies, and other core Shopify resources can be filtered by their metafield values using the GraphQL Admin API's query parameter.

The query format is metafields.{namespace}.{key}:{query_value}.

Info

Querying metaobjects: These query patterns also work for metaobjects — just swap metafields.namespace.key: for fields.field_name:. See Query metaobjects for examples.

Anchor to Query examplesQuery examples

The following examples demonstrate each query method with practical use cases.

Anchor to Filter by text valueFilter by text value

Filter products based on their metafield values. The following example finds all products with a color metafield set to "blue".

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

query ProductsByColor {
products(first: 10, query: "metafields.custom.color:\"blue\"") {
edges {
node {
id
title
metafield(namespace: "custom", key: "color") {
value
}
}
}
}
}

Anchor to Filter by prefix matchFilter by prefix match

Use the * wildcard to find resources where a string metafield starts with specific characters. This is useful for partial matches when you don't know the complete value.

The following example finds all products that start with "notch" as their lapel type on a custom suit.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

query NotchLapelProducts {
products(first: 20, query: "metafields.custom.lapel_style:notch*") {
edges {
node {
id
title
metafield(namespace: "custom", key: "lapel_style") {
value
}
}
}
}
}

Anchor to Filter by numeric valueFilter by numeric value

Numeric metafields support range queries using comparison operators. The following example finds companies with a minimum order value greater than $100.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

query CompaniesWithHighMinOrderValue {
companies(
first: 50
query: "metafields.b2b.min_order_value:>100"
) {
pageInfo {
hasNextPage
}
edges {
node {
id
name
metafield(namespace: "b2b", key: "min_order_value") {
id
type
value
}
}
}
}
}

Anchor to Filter by weightFilter by weight

Numeric metafields support range queries using comparison operators (>, <, >=, <=). For measurement types like weight, Shopify automatically converts between units.

The following example queries products by weight using different units (kilograms, grams, pounds).

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

query searchByWeightValue {
weight_match_kg: products(first: 5, query: "metafields.$app.weight_field:>=1kg") {
nodes {
id
metafield(namespace: "$app", key: "weight_field") { jsonValue }
}
}
weight_match_g: products(first: 5, query: "metafields.$app.weight_field:<2000g") {
nodes {
id
metafield(namespace: "$app", key: "weight_field") { jsonValue }
}
}
weight_match_lb: products(first: 5, query: "metafields.$app.weight_field:>=4lb") {
nodes {
id
metafield(namespace: "$app", key: "weight_field") { jsonValue }
}
}
}

Anchor to Filter by date rangeFilter by date range

Date metafields support range queries using comparison operators and can be combined with AND to filter within a specific date range.

The following example finds all vintages of wines bottled between 2015 and 2018.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

query WinesBottledBetween2015And2018 {
products(
first: 10
query: "metafields.custom.bottled_date:>=2015-01-01 AND metafields.custom.bottled_date:<=2018-12-31"
) {
nodes {
id
title
metafield(namespace: "custom", key: "bottled_date") {
value
}
}
}
}

Anchor to Filter by boolean valueFilter by boolean value

Find all products that are marked as eco-friendly.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

query EcoFriendlyProducts {
products(first: 50, query: "metafields.custom.eco_friendly:true") {
edges {
node {
id
title
metafield(namespace: "custom", key: "eco_friendly") {
value
}
}
}
}
}

Anchor to Filter by date valueFilter by date value

Date metafields support comparison operators for range queries.

The following example finds products released after January 1, 2024.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

query ProductsByReleaseDate {
products(first: 20, query: "metafields.custom.release_date:>2024-01-01") {
edges {
node {
id
title
metafield(namespace: "custom", key: "release_date") {
value
type
}
}
}
}
}

Anchor to Filter by referenceFilter by reference

Reference metafields can be queried using the full Global ID (GID) of the referenced resource.

The following example finds products that reference a specific collection.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

query ProductsByCollectionRef {
products(first: 20,
query: "metafields.custom.featured_collection:\"gid://shopify/Collection/123456789\"") {
edges {
node {
id
title
metafield(namespace: "custom", key: "featured_collection") {
value
reference {
... on Collection {
id
title
}
}
}
}
}
}
}

Anchor to Query list metafieldsQuery list metafields

When querying list fields, the search matches if ANY value in the list equals the search term. This applies to all list types including text lists, reference lists, and multi-select fields.

Anchor to Filter by list valuesFilter by list values

Find products that have a specific tag in a list of tags.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

query ProductsByTag {
products(first: 20,
query: "metafields.custom.product_tags:\"sustainable\"") {
edges {
node {
id
title
metafield(namespace: "custom", key: "product_tags") {
value
type
}
}
}
}
}
Important

When querying multi-value metafields, the query matches if ANY value in the list matches the search term.

Anchor to Filter by list referencesFilter by list references

Find products that reference a specific related product.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

query RelatedProducts {
products(first: 20,
query: "metafields.custom.related_products:\"gid://shopify/Product/987654321\"") {
edges {
node {
id
title
metafield(namespace: "custom", key: "related_products") {
value
references(first: 10) {
edges {
node {
... on Product {
id
title
}
}
}
}
}
}
}
}
}

Anchor to Combining multiple metafield queriesCombining multiple metafield queries

Build complex queries by combining multiple metafield conditions using AND/OR operators. This allows you to filter products based on multiple criteria simultaneously, such as finding products that meet all specified conditions or any of them.

Anchor to Combine multiple conditionsCombine multiple conditions

Find products that match multiple metafield criteria.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

query ComplexProductQuery {
products(first: 20,
query: "metafields.custom.material:\"leather\" AND metafields.custom.eco_friendly:true") {
edges {
node {
id
title
material: metafield(namespace: "custom", key: "material") {
value
}
ecoFriendly: metafield(namespace: "custom", key: "eco_friendly") {
value
}
}
}
}
}

Anchor to Use range queriesUse range queries

Use multiple conditions with AND to filter within a value range. The following example finds products with sizes between 4 and 8.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

query ProductsWithOptions {
products(first: 20,
query: "metafields.custom.dress_size:>4 AND metafields.custom.dress_size:<8") {
edges {
node {
id
title
metafield(namespace: "custom", key: "size") {
value
}
}
}
}
}

Anchor to Troubleshooting common query issuesTroubleshooting common query issues

If your metafield queries aren't working as expected, check these common issues and their solutions. Most problems stem from missing configuration, incorrect syntax, or misunderstanding how different metafield types handle query values.

Anchor to Issue: Query returns all products/metaobjects instead of filtered resultsIssue: Query returns all products/metaobjects instead of filtered results

Problem: Your query isn't filtering results as expected, returning all items instead of just those matching your metafield criteria.

Solution: Ensure the metafield has filtering enabled.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation to enable filtering

mutation EnableFiltering {
metafieldDefinitionUpdate(
definition: {
namespace: "custom" # Replace with your namespace
key: "material" # Replace with your metafield key
ownerType: PRODUCT # Replace with appropriate owner type
capabilities: {
adminFilterable: {
enabled: true
}
}
}
) {
updatedDefinition {
id
namespace
key
capabilities {
adminFilterable {
enabled
}
}
}
userErrors {
field
message
}
}
}

Anchor to Issue: "Invalid query" or syntax errorsIssue: "Invalid query" or syntax errors

Problem: Your query string may have incorrect syntax.

Common mistakes and fixes:

  1. Missing quotes around values:

    • ❌ Wrong: metafields.custom.color:blue
    • ✅ Correct: metafields.custom.color:\"blue\"

  2. Incorrect namespace/key separator:

    • ❌ Wrong: metafields.custom:material:\"cotton\"
    • ✅ Correct: metafields.custom.material:\"cotton\"

  3. Wrong syntax for metaobjects:

    • ❌ Wrong: metafields.color:\"blue\"
    • ✅ Correct: fields.color:\"blue\"

Anchor to Issue: Multi-value metafield queries not workingIssue: Multi-value metafield queries not working

Problem: Queries against list fields return unexpected results.

Solution: Remember that multi-value queries match if ANY value in the list matches:

# If a product has tags: ["sustainable", "organic", "cotton"]
# This query will match:
query {
products(first: 10, query: "metafields.custom.tags:\"organic\"") {
# Returns products with "organic" anywhere in the tags list
}
}

Anchor to Issue: Boolean metafield queries not workingIssue: Boolean metafield queries not working

Problem: Boolean values aren't matching correctly.

Solution: Try using lowercase true or false without quotes:

# Correct boolean query syntax
query {
products(first: 10, query: "metafields.custom.is_featured:true") {
# Note: no quotes around true/false
}
}

Anchor to Issue: Reference field queries failingIssue: Reference field queries failing

Problem: Can't query by product/collection/metaobject references.

Solution: Try using the full GID (Global ID) format:

# Correct reference query
query {
products(first: 10,
query: "metafields.custom.related_collection:\"gid://shopify/Collection/123456789\"") {
# Must use full GID format
}
}

Anchor to Issue: Case sensitivity problemsIssue: Case sensitivity problems

Problem: Queries don't match when case differs.

Solution: Metafield queries are case-sensitive. Ensure exact matching:

# These are different queries:
query CaseSensitive {
# Won't match "Cotton" or "COTTON"
lowercase_only: products(first: 10, query: "metafields.custom.material:\"cotton\"") { nodes { id } }
# To handle case variations, use multiple OR conditions:
case_variants: products(first: 10, query: "metafields.custom.material:\"cotton\" OR metafields.custom.material:\"Cotton\"") { nodes { id } }
}

Anchor to Issue: Special characters in query valuesIssue: Special characters in query values

Problem: Values with quotes or special characters break the query.

Solution: Escape special characters properly:

# For values with quotes, escape them:
query SpecialChars {
products(first: 10,
query: "metafields.custom.description:\"24\\\" monitor\"") {
# Note the escaped quote: \\\"
}
}

Anchor to Best Practices for Metafield QueriesBest Practices for Metafield Queries

  1. Always enable filtering first: Before attempting queries, ensure the metafield definition has adminFilterable enabled.

  2. Test with simple queries: Start with basic single-field queries before combining multiple conditions.

  3. Use GraphiQL for testing: Test your queries in the GraphiQL explorer before implementing in code.

  4. Paginate large result sets: Use cursor-based pagination for better performance:

query PaginatedQuery($cursor: String) {
products(first: 50, after: $cursor,
query: "metafields.custom.category:\"electronics\"") {
edges {
node {
id
title
}
}
pageInfo {
hasNextPage
endCursor
}
}
}
  1. Monitor query performance: Complex metafield queries can be slower than standard field queries. Consider caching results when appropriate.

Anchor to Next stepsNext steps

Was this page helpful?