---
title: Query using metafields
description: Find Shopify resources by metafield values using the GraphQL Admin API.
source_url:
  html: 'https://shopify.dev/docs/apps/build/metafields/query-using-metafields'
  md: 'https://shopify.dev/docs/apps/build/metafields/query-using-metafields.md'
---

ExpandOn this page

* [Requirements](https://shopify.dev/docs/apps/build/metafields/query-using-metafields.md#requirements)
* [Query examples](https://shopify.dev/docs/apps/build/metafields/query-using-metafields.md#query-examples)
* [Query list metafields](https://shopify.dev/docs/apps/build/metafields/query-using-metafields.md#query-list-metafields)
* [Combining multiple metafield queries](https://shopify.dev/docs/apps/build/metafields/query-using-metafields.md#combining-multiple-metafield-queries)
* [Troubleshooting common query issues](https://shopify.dev/docs/apps/build/metafields/query-using-metafields.md#troubleshooting-common-query-issues)
* [Best Practices for Metafield Queries](https://shopify.dev/docs/apps/build/metafields/query-using-metafields.md#best-practices-for-metafield-queries)
* [Next steps](https://shopify.dev/docs/apps/build/metafields/query-using-metafields.md#next-steps)

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

***

## Requirements

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

* [Enable filtering](https://shopify.dev/docs/apps/build/metafields/use-metafield-capabilities#admin-filterable) through the API or in the Shopify admin.
* Not all metafield types or resources support filtering - see the [complete list](https://shopify.dev/docs/apps/build/metafields/use-metafield-capabilities#admin-filterable).

Products, companies, and other core Shopify resources can be filtered by their metafield values using the GraphQL Admin API's [`query` parameter](https://shopify.dev/docs/api/usage/search-syntax).

The syntax is `metafields.{namespace}.{key}:{query_value}`.

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

Info

**Querying metaobjects:** These query patterns also work for metaobjects — just swap `metafields.namespace.key:` for `fields.field_name:`. See [Query metaobjects](https://shopify.dev/docs/apps/build/metaobjects/query-metaobjects) for examples.

***

## Query examples

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

### Filter 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

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

### Filter by boolean value

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

### Filter 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

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

***

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

### Filter 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

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

### Filter by list references

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

***

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

### Combine multiple 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
        }
      }
    }
  }
}
```

***

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

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

***

## Next steps

* Learn how to [enable filtering and other advanced features](https://shopify.dev/docs/apps/build/metafields/use-metafield-capabilities).
* Learn how to [query metaobjects](https://shopify.dev/docs/apps/build/metaobjects/query-metaobjects).
* Learn how to [work with metafield definitions](https://shopify.dev/docs/apps/build/metafields/definitions).

***

* [Requirements](https://shopify.dev/docs/apps/build/metafields/query-using-metafields.md#requirements)
* [Query examples](https://shopify.dev/docs/apps/build/metafields/query-using-metafields.md#query-examples)
* [Query list metafields](https://shopify.dev/docs/apps/build/metafields/query-using-metafields.md#query-list-metafields)
* [Combining multiple metafield queries](https://shopify.dev/docs/apps/build/metafields/query-using-metafields.md#combining-multiple-metafield-queries)
* [Troubleshooting common query issues](https://shopify.dev/docs/apps/build/metafields/query-using-metafields.md#troubleshooting-common-query-issues)
* [Best Practices for Metafield Queries](https://shopify.dev/docs/apps/build/metafields/query-using-metafields.md#best-practices-for-metafield-queries)
* [Next steps](https://shopify.dev/docs/apps/build/metafields/query-using-metafields.md#next-steps)