---
title: Query metaobjects
description: >-
  Filter and search metaobjects by their field values using the GraphQL Admin
  API.
source_url:
  html: 'https://shopify.dev/docs/apps/build/metaobjects/query-metaobjects'
  md: 'https://shopify.dev/docs/apps/build/metaobjects/query-metaobjects.md'
api_name: admin
---

# Query metaobjects

Query metaobjects by their field values to find entries that match specific criteria. Use this to build dynamic searches, filter content, or find metaobject entries based on their data.

***

## Prerequisites

Before querying by field value, you need a metaobject definition with entries created.

* [Create metaobject definitions](https://shopify.dev/docs/apps/build/metaobjects/manage-metaobject-definitions)
* [Create metaobject entries](https://shopify.dev/docs/apps/build/metaobjects/manage-metaobjects)

***

## Query syntax

Use the `fields.{key}:{value}` syntax to query metaobjects based on their field values:

metaobjects(type: "your\_type", query: "fields.field\_name:\\"value\\"")

**Note:**

The `{key}` must exactly match the field's key from its metaobject definition, and matching is case-sensitive. Field keys are typically `snake_case` (for example, `feature_name`), so a query like `fields.featureName` won't match a field whose key is `feature_name`.

***

## Query examples

The following examples demonstrate how to query metaobjects by different field types.

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

### By taxonomy reference

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/).

### By list fields

Find metaobjects that contain a specific value in a list field. The query matches if ANY value in the list matches the search term.

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

***

## Best practices

* **Test queries in GraphiQL** before implementing in code.
* **Use pagination** for large result sets with cursor-based pagination.
* **Be case-sensitive** - metaobject field queries are case-sensitive.
* **Quote values** - always wrap query values in escaped quotes: `\"value\"`

***

## Next steps

* Learn how to [work with metaobject entries](https://shopify.dev/docs/apps/build/metaobjects/manage-metaobjects).
* Learn how to [work with metaobject definitions](https://shopify.dev/docs/apps/build/metaobjects/manage-metaobject-definitions).
* Learn how to use metafields to [query resources](https://shopify.dev/docs/apps/build/metafields/query-using-metafields).

***