---
title: metafieldDefinition - GraphQL Admin
description: >-
  Retrieves a
  [`MetafieldDefinition`](https://shopify.dev/docs/api/admin-graphql/current/objects/MetafieldDefinition)
  by its identifier. You can identify a definition using either its owner type,
  namespace, and key, or its global ID.


  Use this query to inspect a definition's configuration, including its data
  type, validations, access settings, and the count of
  [metafields](https://shopify.dev/docs/api/admin-graphql/current/objects/Metafield)
  using it.
api_version: 2025-10
api_name: admin
type: query
api_type: graphql
source_url:
  html: >-
    https://shopify.dev/docs/api/admin-graphql/latest/queries/metafieldDefinition
  md: >-
    https://shopify.dev/docs/api/admin-graphql/latest/queries/metafieldDefinition.md
---

# metafield​Definition

query

Requires API client to have access to the resource type associated with the metafield definition.

Retrieves a [`MetafieldDefinition`](https://shopify.dev/docs/api/admin-graphql/current/objects/MetafieldDefinition) by its identifier. You can identify a definition using either its owner type, namespace, and key, or its global ID.

Use this query to inspect a definition's configuration, including its data type, validations, access settings, and the count of [metafields](https://shopify.dev/docs/api/admin-graphql/current/objects/Metafield) using it.

## Arguments

* identifier

  [Metafield​Definition​Identifier​Input](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/MetafieldDefinitionIdentifierInput)

  The identifier of the MetafieldDefinition to return.

* id

  [ID](https://shopify.dev/docs/api/admin-graphql/latest/scalars/ID)

  Deprecated

***

## Possible returns

* Metafield​Definition

  [Metafield​Definition](https://shopify.dev/docs/api/admin-graphql/latest/objects/MetafieldDefinition)

  Defines the structure, validation rules, and permissions for [`Metafield`](https://shopify.dev/docs/api/admin-graphql/current/objects/Metafield) objects attached to a specific owner type. Each definition establishes a schema that metafields must follow, including the data type and validation constraints.

  The definition controls access permissions across different APIs, determines whether the metafield can be used for filtering or as a collection condition, and can be constrained to specific resource subtypes.

***

## Examples

* ### Retrieve a count of a resource's metafields.

  #### Query

  ```graphql
  query MetafieldsCount($metafieldDefinitionId: ID!) {
    metafieldDefinition(id: $metafieldDefinitionId) {
      id
      metafieldsCount
    }
  }
  ```

  #### Variables

  ```json
  {
    "metafieldDefinitionId": "gid://shopify/MetafieldDefinition/1071456212"
  }
  ```

  #### cURL

  ```bash
  curl -X POST \
  https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \
  -H 'Content-Type: application/json' \
  -H 'X-Shopify-Access-Token: {access_token}' \
  -d '{
  "query": "query MetafieldsCount($metafieldDefinitionId: ID!) { metafieldDefinition(id: $metafieldDefinitionId) { id metafieldsCount } }",
   "variables": {
      "metafieldDefinitionId": "gid://shopify/MetafieldDefinition/1071456212"
    }
  }'
  ```

  #### React Router

  ```javascript
  import { authenticate } from "../shopify.server";

  export const loader = async ({request}) => {
    const { admin } = await authenticate.admin(request);
    const response = await admin.graphql(
      `#graphql
    query MetafieldsCount($metafieldDefinitionId: ID!) {
      metafieldDefinition(id: $metafieldDefinitionId) {
        id
        metafieldsCount
      }
    }`,
    {
      variables: {
          "metafieldDefinitionId": "gid://shopify/MetafieldDefinition/1071456212"
      },
    },
    );
    const json = await response.json();
    return json.data;
  }
  ```

  #### Ruby

  ```ruby
  session = ShopifyAPI::Auth::Session.new(
    shop: "your-development-store.myshopify.com",
    access_token: access_token
  )
  client = ShopifyAPI::Clients::Graphql::Admin.new(
    session: session
  )

  query = <<~QUERY
    query MetafieldsCount($metafieldDefinitionId: ID!) {
      metafieldDefinition(id: $metafieldDefinitionId) {
        id
        metafieldsCount
      }
    }
  QUERY

  variables = {
    "metafieldDefinitionId": "gid://shopify/MetafieldDefinition/1071456212"
  }

  response = client.query(query: query, variables: variables)
  ```

  #### Node.js

  ```javascript
  const client = new shopify.clients.Graphql({session});
  const data = await client.query({
    data: {
      "query": `query MetafieldsCount($metafieldDefinitionId: ID!) {
        metafieldDefinition(id: $metafieldDefinitionId) {
          id
          metafieldsCount
        }
      }`,
      "variables": {
          "metafieldDefinitionId": "gid://shopify/MetafieldDefinition/1071456212"
      },
    },
  });
  ```

  #### Response

  ```json
  {
    "metafieldDefinition": {
      "id": "gid://shopify/MetafieldDefinition/1071456212",
      "metafieldsCount": 0
    }
  }
  ```

* ### Retrieve a metafield definition

  #### Description

  To retrieve a single metafield definition, use the \`metafieldDefinition\` query with its ID. The following example shows how to retrieve a metafield definition.

  #### Query

  ```graphql
  query {
    metafieldDefinition(id: "gid://shopify/MetafieldDefinition/1071456211") {
      name
    }
  }
  ```

  #### cURL

  ```bash
  curl -X POST \
  https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \
  -H 'Content-Type: application/json' \
  -H 'X-Shopify-Access-Token: {access_token}' \
  -d '{
  "query": "query { metafieldDefinition(id: \"gid://shopify/MetafieldDefinition/1071456211\") { name } }"
  }'
  ```

  #### React Router

  ```javascript
  import { authenticate } from "../shopify.server";

  export const loader = async ({request}) => {
    const { admin } = await authenticate.admin(request);
    const response = await admin.graphql(
      `#graphql
    query {
      metafieldDefinition(id: "gid://shopify/MetafieldDefinition/1071456211") {
        name
      }
    }`,
    );
    const json = await response.json();
    return json.data;
  }
  ```

  #### Ruby

  ```ruby
  session = ShopifyAPI::Auth::Session.new(
    shop: "your-development-store.myshopify.com",
    access_token: access_token
  )
  client = ShopifyAPI::Clients::Graphql::Admin.new(
    session: session
  )

  query = <<~QUERY
    query {
      metafieldDefinition(id: "gid://shopify/MetafieldDefinition/1071456211") {
        name
      }
    }
  QUERY

  response = client.query(query: query)
  ```

  #### Node.js

  ```javascript
  const client = new shopify.clients.Graphql({session});
  const data = await client.query({
    data: `query {
      metafieldDefinition(id: "gid://shopify/MetafieldDefinition/1071456211") {
        name
      }
    }`,
  });
  ```

  #### Response

  ```json
  {
    "metafieldDefinition": {
      "name": "ingredients"
    }
  }
  ```

[Open in GraphiQL](http://localhost:3457/graphiql?query=query%20MetafieldsCount\(%24metafieldDefinitionId%3A%20ID!\)%20%7B%0A%20%20metafieldDefinition\(id%3A%20%24metafieldDefinitionId\)%20%7B%0A%20%20%20%20id%0A%20%20%20%20metafieldsCount%0A%20%20%7D%0A%7D\&variables=%7B%0A%20%20%22metafieldDefinitionId%22%3A%20%22gid%3A%2F%2Fshopify%2FMetafieldDefinition%2F1071456212%22%0A%7D)

##### GQL

```graphql
query MetafieldsCount($metafieldDefinitionId: ID!) {
  metafieldDefinition(id: $metafieldDefinitionId) {
    id
    metafieldsCount
  }
}
```

##### cURL

```bash
curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query MetafieldsCount($metafieldDefinitionId: ID!) { metafieldDefinition(id: $metafieldDefinitionId) { id metafieldsCount } }",
 "variables": {
    "metafieldDefinitionId": "gid://shopify/MetafieldDefinition/1071456212"
  }
}'
```

##### React Router

```javascript
import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  query MetafieldsCount($metafieldDefinitionId: ID!) {
    metafieldDefinition(id: $metafieldDefinitionId) {
      id
      metafieldsCount
    }
  }`,
  {
    variables: {
        "metafieldDefinitionId": "gid://shopify/MetafieldDefinition/1071456212"
    },
  },
  );
  const json = await response.json();
  return json.data;
}
```

##### Node.js

```javascript
const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `query MetafieldsCount($metafieldDefinitionId: ID!) {
      metafieldDefinition(id: $metafieldDefinitionId) {
        id
        metafieldsCount
      }
    }`,
    "variables": {
        "metafieldDefinitionId": "gid://shopify/MetafieldDefinition/1071456212"
    },
  },
});
```

##### Ruby

```ruby
session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  query MetafieldsCount($metafieldDefinitionId: ID!) {
    metafieldDefinition(id: $metafieldDefinitionId) {
      id
      metafieldsCount
    }
  }
QUERY

variables = {
  "metafieldDefinitionId": "gid://shopify/MetafieldDefinition/1071456212"
}

response = client.query(query: query, variables: variables)
```

## Input variables

JSON

```json
{
  "metafieldDefinitionId": "gid://shopify/MetafieldDefinition/1071456212"
}
```

## Response

JSON

```json
{
  "metafieldDefinition": {
    "id": "gid://shopify/MetafieldDefinition/1071456212",
    "metafieldsCount": 0
  }
}
```