---
title: Query by metafield value
description: >-
  How to query Shopify resources, such as products and metaobjects, by specific
  metafield values.
source_url:
  html: >-
    https://shopify.dev/docs/apps/build/custom-data/metafields/query-by-metafield-value
  md: >-
    https://shopify.dev/docs/apps/build/custom-data/metafields/query-by-metafield-value.md
---

ExpandOn this page

* [Querying products by metafield value](https://shopify.dev/docs/apps/build/custom-data/metafields/query-by-metafield-value.md#querying-products-by-metafield-value)
* [Querying metaobjects by field value](https://shopify.dev/docs/apps/build/custom-data/metafields/query-by-metafield-value.md#querying-metaobjects-by-field-value)
* [Single-value metafield queries](https://shopify.dev/docs/apps/build/custom-data/metafields/query-by-metafield-value.md#single-value-metafield-queries)
* [Multi-value metafield queries](https://shopify.dev/docs/apps/build/custom-data/metafields/query-by-metafield-value.md#multi-value-metafield-queries)
* [Combining multiple metafield queries](https://shopify.dev/docs/apps/build/custom-data/metafields/query-by-metafield-value.md#combining-multiple-metafield-queries)
* [Troubleshooting common query issues](https://shopify.dev/docs/apps/build/custom-data/metafields/query-by-metafield-value.md#troubleshooting-common-query-issues)
* [Best Practices for Metafield Queries](https://shopify.dev/docs/apps/build/custom-data/metafields/query-by-metafield-value.md#best-practices-for-metafield-queries)
* [Related Resources](https://shopify.dev/docs/apps/build/custom-data/metafields/query-by-metafield-value.md#related-resources)

# Query by metafield value

It's possible to query Shopify resources by their custom field values. This is useful if you want to, for example, find products with specific metafield values or metaobjects with specific field values.

Warning

To query by metafield value, the metafield must have filtering enabled first. Without filtering enabled, queries will be ignored and return unfiltered results. See [enabling filtering](https://shopify.dev/docs/apps/build/custom-data/metafields/use-metafield-capabilities#admin-filterable) for details. Filtering can also be enabled in the Shopify admin. Learn more about enabling [filtering for product metafields](https://help.shopify.com/en/manual/custom-data/metafields/filtering-products) and [filtering for metaobject fields](https://help.shopify.com/en/manual/custom-data/options).

Not all metafield types support query filtering. The following types can be used in queries (see [complete list with details](https://shopify.dev/docs/apps/build/custom-data/metafields/use-metafield-capabilities#admin-filterable)):

* Single line text or Single line text (list)
* Product reference or Product reference (list)
* True or false
* Collection reference or Collection reference (list)
* Page reference or Page reference (list)
* Metaobject reference or Metaobject reference (list)
* Company reference or Company reference (list)

Note

Only case-sensitive, exact matches are supported for filtering.

***

## Querying products by metafield value

Products, collections, and other core Shopify resources can be filtered by their metafield values using the GraphQL Admin API's query parameter. The syntax for metafields on core resources (such as products) is `metafields.{namespace}.{key}:{query_value}`.

## POST https\://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL query

```graphql
query Products {
  products(first: 20, query: "metafields.custom.material:\"cotton\"") {
    edges {
      node {
        id
        title
        metafield(namespace: "custom", key: "material") {
          value
        }
        updatedAt
        createdAt
      }
    }
  }
}
```

***

## Querying metaobjects by field value

Use the `fields.{key}:{value}` syntax to query metaobjects based on their field values, including text fields, reference fields, and taxonomy fields.

### Querying metaobjects by taxonomy reference field value

Find metaobjects classified with specific taxonomy values like colors or materials:

## POST https\://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL query

```graphql
query Metaobjects {
    metaobjects(first: 20, type: "shopify--color-pattern",
    query: "fields.taxonomy_reference:\"gid://shopify/TaxonomyValue/2\"") {
    edges {
        node {
            id
            displayName
            type
            name: field(key: "color_taxonomy_reference") { value }
            updatedAt
            createdAt
        }
     }
  }
}
```

Note

This example uses the GID structure for the taxonomy node for the `color` blue. You can find GIDs for taxonomy nodes in the open source [Taxonomy Explorer](https://shopify.github.io/product-taxonomy/releases/latest/).

### Querying metaobjects using a simple single line text field

Filter metaobjects by exact text field matches:

## POST https\://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL query

```graphql
query Metaobjects {
  metaobjects(first: 20, type: "custom--product-feature",
    query: "fields.feature_name:\"waterproof\"") {
    edges {
      node {
        id
        displayName
        type
        name: field(key: "feature_name") { value }
        updatedAt
        createdAt
      }
    }
  }
}
```

***

## Single-value metafield queries

Build on the basic query syntax with these advanced examples showing how to query different metafield types, combine multiple conditions, and handle special cases like multi-value fields.

### Querying products by boolean metafield

Find all products that are marked as eco-friendly:

## POST https\://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL query

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

### Querying products by numeric metafield

Find products with a specific warranty period:

## POST https\://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL query

```graphql
query ProductsByWarranty {
  products(first: 20, query: "metafields.custom.warranty_years:\"2\"") {
    edges {
      node {
        id
        title
        metafield(namespace: "custom", key: "warranty_years") {
          value
          type
        }
      }
    }
  }
}
```

Note

Numeric metafield values must be quoted in the query string.

### Querying products by collection reference metafield

Find products that reference a specific collection:

## POST https\://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL query

```graphql
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
            }
          }
        }
      }
    }
  }
}
```

***

## Multi-value metafield queries

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.

### Querying products with multi-value text list metafields

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

## POST https\://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL query

```graphql
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.

### Querying products with multi-value product reference lists

Find products that reference a specific related product:

## POST https\://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL query

```graphql
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
                }
              }
            }
          }
        }
      }
    }
  }
}
```

### Querying metaobjects with multi-value fields

Find metaobjects that contain a specific value in a list field:

## POST https\://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL query

```graphql
query MetaobjectsByListValue {
  metaobjects(first: 20, type: "custom--product_feature",
    query: "fields.supported_devices:\"iPhone 15\"") {
    edges {
      node {
        id
        displayName
        field(key: "supported_devices") { 
          value 
        }
      }
    }
  }
}
```

***

## Combining 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.

### Query with multiple metafield conditions

Find products that match multiple metafield criteria:

## POST https\://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL query

```graphql
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
        }
      }
    }
  }
}
```

### Query with OR conditions

Find products that match any of the specified conditions:

## POST https\://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL query

```graphql
query ProductsWithOptions {
  products(first: 20, 
    query: "metafields.custom.size:\"large\" OR metafields.custom.size:\"x-large\"") {
    edges {
      node {
        id
        title
        metafield(namespace: "custom", key: "size") {
          value
        }
      }
    }
  }
}
```

***

## Troubleshooting 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.

### Issue: 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

```graphql
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
    }
  }
}
```

### Issue: "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\"`

### Issue: 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:

```graphql
# 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
  }
}
```

### Issue: Boolean metafield queries not working

**Problem:** Boolean values aren't matching correctly.

**Solution:** Try using lowercase `true` or `false` without quotes:

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

### Issue: Reference field queries failing

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

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

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

### Issue: Case sensitivity problems

**Problem:** Queries don't match when case differs.

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

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

### Issue: Special characters in query values

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

**Solution:** Escape special characters properly:

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

***

## Best 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:

```graphql
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.

***

## Related Resources

* [Enabling metafield filtering](https://shopify.dev/docs/apps/build/custom-data/metafields/use-metafield-capabilities#admin-filterable)
* [Metafield definitions](https://shopify.dev/docs/apps/build/custom-data/metafields/definitions)
* [GraphQL query documentation](https://shopify.dev/docs/api/admin-graphql/latest/queries/products)

***

* [Querying products by metafield value](https://shopify.dev/docs/apps/build/custom-data/metafields/query-by-metafield-value.md#querying-products-by-metafield-value)
* [Querying metaobjects by field value](https://shopify.dev/docs/apps/build/custom-data/metafields/query-by-metafield-value.md#querying-metaobjects-by-field-value)
* [Single-value metafield queries](https://shopify.dev/docs/apps/build/custom-data/metafields/query-by-metafield-value.md#single-value-metafield-queries)
* [Multi-value metafield queries](https://shopify.dev/docs/apps/build/custom-data/metafields/query-by-metafield-value.md#multi-value-metafield-queries)
* [Combining multiple metafield queries](https://shopify.dev/docs/apps/build/custom-data/metafields/query-by-metafield-value.md#combining-multiple-metafield-queries)
* [Troubleshooting common query issues](https://shopify.dev/docs/apps/build/custom-data/metafields/query-by-metafield-value.md#troubleshooting-common-query-issues)
* [Best Practices for Metafield Queries](https://shopify.dev/docs/apps/build/custom-data/metafields/query-by-metafield-value.md#best-practices-for-metafield-queries)
* [Related Resources](https://shopify.dev/docs/apps/build/custom-data/metafields/query-by-metafield-value.md#related-resources)