Documentation Center

GraphQL requests involving custom metadata filtering

This series of samples demonstrates the use of scope while filtering on custom metadata.

The following basic query gets a number of properties for all items that have the custom metadata Keyword "mykey" set to the value 42:
{
  items(
    filter: {
      customMeta: {scope: Item, key: "mykey", value: "42"}
    }
  ) {
    edges {
      node {
        id
        publicationId
        namespaceId
        itemId
        itemType
        title
        customMetas {
          edges {
            node {
              key
              value
            }
          }
        }
      }
    }
  }
}

Now we explore how changing the filter affects the results of the query.

To limit your query within the scope of one or more Publications, change the filter: part of the query, changing scope: Item into scope:Publication:
filter: {
  customMeta: {scope: Publication, key: "mykey", value: "42"} 
}
To further specify that the returned items should only be Publications, add itemTypes to your filter:
filter: {
  itemTypes: [PUBLICATION],
  customMeta: {scope: Publication, key: "mykey", value: "42"}
}
By setting itemTypes to [Publication], the scope property in customMeta becomes irrelevant. A query with the filter above gives the same result as a query with the following filter:
filter: {
  itemTypes: [PUBLICATION],
  customMeta: {scope: Item, key: "mykey", value: "42"}
}
For the following set of sample filters, we're imagining querying the following data set:
  • Three Publications called Pub1, Pub2 and Pub3.
  • Pub1 contains two items: Item1, which has item type 16, and Item2, which has item type 64 (which means it's a Page).
  • Item1 has the mykey custom metadata Keyword set to the value 42. (Item2 has no custom metadata of any kind.)
  • Pub2 also contains two items: Item3 and Item4, both of which have item type 16.
  • Item3 has the mykey custom metadata Keyword set to the value 42. (Item4 has no custom metadata of any kind.)
  • Finally, Pub3 only contains one item: Item5, which is of item type 64 (which means it's a Page) and also has no custom metadata set.
As a diagram:

The set of sample filters shows the use of ItemInPublication scope. You use this scope to retrieve items located in a Publication that contains items tagged with a specified custom metadata key-value pair.

Here is a basic filter using ItemInPublication:
filter: {
  customMeta: {scope: ItemInPublication, key: "mykey", value: "42"}
}

Applied to the sample data set, the query returns all items associated with Publications that contain items tagged with mykey=42 (including the Publications themselves). That is, the query returns Pub1, Pub2, Item1, Item2, Item3 and Item4.

To only get the Publications back, we add an itemTypes property to our filter:
filter: {
  itemTypes: [PUBLICATION],
  customMeta: {scope: ItemInPublication, key: "mykey", value: "42"}
}

Applied to the sample data set, the query returns all Publications that contain items tagged with mykey=42. That is, the query returns Pub1 and Pub2.

To only get Pages back, we change the itemTypes property in our filter:
filter: {
  itemTypes: [PAGE],
  customMeta: {scope: ItemInPublication, key: "mykey", value: "42"}
}

Applied to the sample data set, the query returns all Pages located in Publications that contain items tagged with mykey=42. That is, the query returns Item2 only. The reason why Item1, Item3 and Item4 are not returned is because they are not Pages; the reason why Item5 is not returned is because it isn't located in a Publication containing an item tagged with mykey=42.