---
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 syntax overview](https://shopify.dev/docs/apps/build/metafields/query-using-metafields.md#query-syntax-overview)
* [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).

***

## Query syntax overview

The following query patterns are available, depending on the metafield [data type](https://shopify.dev/docs/apps/build/metafields/list-of-data-types):

* **Exact match:** Works for all types. Case-sensitive for text. Example: `color:"blue"`.
* **Prefix match:** Text types only. Use `*` wildcard. Example: `lapel_style:notch*` matches "notch lapel".
* **Range queries:** Numeric and date types. Use `>`, `<`, `>=`, `<=`. Example: `price:>100`.
* **Boolean:** Use `true` or `false` without quotes. Example: `eco_friendly:true`.
* **Reference:** Use full GID format. Example: `collection:"gid://shopify/Collection/123"`.
* **List values:** Matches 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](https://shopify.dev/docs/api/usage/search-syntax).

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](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 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

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

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

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

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

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

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

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

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

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

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

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

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

***

## 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 syntax overview](https://shopify.dev/docs/apps/build/metafields/query-using-metafields.md#query-syntax-overview)
* [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)