---
title: Use metafield capabilities
description: Learn about optional features available for metafields.
source_url:
  html: 'https://shopify.dev/docs/apps/build/metafields/use-metafield-capabilities'
  md: 'https://shopify.dev/docs/apps/build/metafields/use-metafield-capabilities.md'
---

ExpandOn this page

* [Smart collection](https://shopify.dev/docs/apps/build/metafields/use-metafield-capabilities.md#smart-collection)
* [Admin filterable](https://shopify.dev/docs/apps/build/metafields/use-metafield-capabilities.md#admin-filterable)
* [Unique values](https://shopify.dev/docs/apps/build/metafields/use-metafield-capabilities.md#unique-values)

# Use metafield capabilities

Capabilities enable optional features for metafield definitions. You can enable the following `capabilities`:

* **[`smartCollectionCondition`](#smart-collection)**: Create an automated collection based on metafield values for a given definition.
* **[`adminFilterable`](#admin-filterable)**: Filter supported owner types based on metafield values for a definition in the Shopify admin and GraphQL Admin API.
* **[`uniqueValues`](#unique-values)**: Enforce unique metafield values for a definition.

Capability support in TOML configuration

Currently, only the `adminFilterable` and `uniqueValues` capabilities are supported in TOML configuration.

***

## Smart collection

An automated collection, also known as a smart collection, is a grouping of products that's defined by a set of rules. Shopify automatically changes the contents of an automated collection based on the configured rules. You can create rules with metafield definitions to automatically update the contents of an automated collection based on product or variant metafields.

Smart collections are available for the following metafield types:

| Metafield definition type | Supported conditions |
| - | - |
| True or false | equals |
| Integer | equals greater than less than |
| Decimal | equals greater than less than |
| Rating | equals greater than less than |
| Single line text | equals |
| Metaobject reference | equals |

### Enabling the smart collection capability

Enable this capability using either:

* [`metafieldDefinitionUpdate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/metafieldDefinitionUpdate)
* [`metafieldDefinitionCreate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/metafieldDefinitionCreate)

The following example shows how to update a metafield definition with the `smartCollectionCondition` set to `true` to enable the smart collection capability:

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

## GraphQL mutation

```graphql
mutation metafieldDefinitionUpdate($definition: MetafieldDefinitionUpdateInput!) {
  metafieldDefinitionUpdate(definition: $definition) {
    userErrors {
      field
      message
    }
    updatedDefinition {
      key
      name
      namespace
      ownerType
      id
      capabilities {
        smartCollectionCondition {
          enabled
            }
          }
        }
  }
}
```

## Variables

```json
{
  "definition": {
    "namespace": "custom",
    "key": "material",
    "ownerType": "PRODUCT",
    "capabilities": {
      "smartCollectionCondition": {
        "enabled": true
      }
    }
  }
}
```

### Using metafields in a smart collection

After the capability is enabled, you can create a smart collection either in the Shopify admin or with the following mutations:

* To create a smart collection, you can use the [`collectionCreate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/collectionCreate) mutation.
* To update an existing collection, you can use the [`collectionUpdate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/collectionUpdate) mutation.

The following example creates a smart collection that includes products with a `color` metaobject reference set to `blue`:

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

## GraphQL mutation

```graphql
mutation CreateCollection($collection: CollectionInput!) {
  collectionCreate(input: $collection) {
    collection {
      id
      title
      descriptionHtml
      sortOrder
      handle
      templateSuffix
      ruleSet {
        appliedDisjunctively
        rules {
          column
          relation
          condition
       }
      }
    }
    userErrors {
      field
      message
      }
     }
}
```

## Variables

```json
{
  "collection": {
    "title": "Blue products collection",
    "metafields": [],
    "ruleSet": {
      "appliedDisjunctively": false,
      "rules": [
      {
          "column": "PRODUCT_METAFIELD_DEFINITION",
          "relation": "EQUALS",
          "condition": "gid://shopify/Metaobject/112030056537",
          "conditionObjectId": "gid://shopify/MetafieldDefinition/23417389145"
        }
      ]
    }
  }
}
```

***

## Admin filterable

The Shopify admin filterable capability allows you to use a metafield definition and its values to filter resource lists in the Shopify admin. This capability makes it easier for developers to find and manage resources, such as products, based on their specific metafield values. Learn how to [query using metafields](https://shopify.dev/docs/apps/build/metafields/query-using-metafields).

The capability is available for the following metafield types:

| Metafield Type |
| - |
| Single line text |
| Single line text (list) |
| Product reference |
| Product reference (list) |
| True or false |
| Collection reference |
| Collection reference (list) |
| Page reference |
| Page reference (list) |
| Metaobject reference |
| Metaobject reference (list) |
| Company reference |
| Company reference (list) |

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

To enable this capability, you can use TOML configuration or the [`metafieldDefinitionUpdate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/metafieldDefinitionUpdate) mutation.

The following example shows how to enable the admin filterable capability:

## shopify.app.toml

##### TOML

```toml
[product.metafields.custom.material]
name = "material"
type = "single_line_text_field"
capabilities.admin_filterable = true
```

##### GraphQL

```graphql
mutation metafieldDefinitionUpdate {
  metafieldDefinitionUpdate(definition: {
    namespace: "custom"
    key: "material"
    ownerType: PRODUCT
    capabilities: {
      adminFilterable: {
        enabled: true
      }
    }
  }) {
    userErrors {
      field
      message
    }
    updatedDefinition {
      key
      name
      namespace
      ownerType
      id
      capabilities {
        adminFilterable {
          enabled
        }
      }
    }
  }
}
```

See [query using metafields](https://shopify.dev/docs/apps/build/metafields/query-using-metafields) for examples of filtering by metafield value.

***

## Unique values

The unique values capability ensures all values of a metafield definition are unique. This is commonly used when storing external identifiers that must not duplicate, like ERP or PIM IDs. See [working with custom IDs](https://shopify.dev/docs/apps/build/metafields/working-with-custom-ids) for a complete guide.

| Metafield Type |
| - |
| Single line text |
| URL |
| Integer |

The following example shows how to create a metafield definition with `uniqueValues` set to `true` to enable the unique values capability.

## shopify.app.toml

##### TOML

```toml
[product.metafields.custom.external_id]
name = "External ID"
type = "single_line_text_field"
capabilities.unique_values = true
```

##### GraphQL

```graphql
mutation {
  metafieldDefinitionCreate(definition: {
    name: "External ID"
    namespace: "custom"
    key: "external_id"
    type: "single_line_text_field"
    ownerType: PRODUCT
    capabilities: {
      uniqueValues: {
        enabled: true
      }
    }
  }) {
    createdDefinition {
      id
      name
      namespace
      key
      capabilities {
        uniqueValues {
          enabled
        }
      }
    }
    userErrors {
      field
      message
      code
    }
  }
}
```

***

* [Smart collection](https://shopify.dev/docs/apps/build/metafields/use-metafield-capabilities.md#smart-collection)
* [Admin filterable](https://shopify.dev/docs/apps/build/metafields/use-metafield-capabilities.md#admin-filterable)
* [Unique values](https://shopify.dev/docs/apps/build/metafields/use-metafield-capabilities.md#unique-values)