GraphQL Content Delivery API: filter and playground

Release date: 19th April 2023

In this release we're introducing enhanced filter and sort functionality to the GraphQL Content Delivery API. Previously you could list all items of a content type, now you can also filter content by one or more properties, and define the way the results are sorted.

We are also introducing our new Amplience playground, which has many in-built features to enhance your coding experience. Some of these include:

• Switching between multiple tabs to view different code snippets
• The ability to prettify, copy and merge fragments into your queries
• A documentation explorer and history log of previous queries to reuse
• The ability to refetch GraphQL schemas and access the short-keys dialog for a seamless coding experience

You can find more information in the GraphQL Content Delivery overview.

Using GraphQL filter and sort

The GraphQL filter functionality lets you sort and filter your content. You can specify the sort order of your results when listing and filter content using one or more custom properties. Content is pre-filtered using the filters specified in your content type schemas so the API is optimized for speed.

The main features of the GraphQL filter API include:

• Sorting content using properties in your content type schema. With a blog, for example, you could sort all blogs by category, read time or date.
• Filter by content type and one or more properties. So you could retrieve all products in a particular category, or all blogs on a chosen topic.
• Manage multiple pages of responses. If you get a lot of results, then you can easily request the next page of responses or adjust the page size.

note

In order to use the filter functionality you need to specify filterable and sortable traits in your schemas. The content must be published after these traits have been added.

In the code snippet example below, we use sortBy to set the key default and order to descending. We also use filter to filter by Product Family, which was already set in the content type schema.

{
  allPdpContentBlock(
    first: 2
    sortBy: { key: default, order: DESC }
    filter: { byProductFamily: { productFamily: "Womenswear" } }
  ) {
    edges {
      node {
        categoryId
      }
    }
  }
}

This gives us the following response:

{
  "data": {
    "allPdpContentBlock": {
      "edges": [
        {
          "node": {
            "categoryId": "tailored-jacket"
          }
        },
        {
          "node": {
            "categoryId": "grey-jacket"
          }
        }
      ]
    }
  }
}

Using the Amplience GraphQL playground

The Amplience playground contains all the content and data associated with the hub you've used the endpoint for. For example, if we have specific blog post content that we'd like to request for, we can run a simple query in the playground.

To query this blog post in a GraphQL playground, we need either the delivery key or the content id. In the example query below, we're using the delivery key to request the title, description and read time.

{
  blogPostFilter(deliveryKey: "indoor-play-for-kids") {
    title
    description
    readTime
  }
}

As shown below, our query returns a GraphQL format result that includes the title of our blog post, the description and the read time:

{
  "data": {
    "blogPostFilter": {
      "title": "Indoor play ideas for the kids this half term",
      "description": "Try out our ideas for indoor play and entertainment this week.",
      "readTime": 20
    }
  }
}

To access the playground, use the GraphQL API endpoint for your chosen hub in your web browser.

If you would like to try out a few simple GraphQL queries in the Amplience playground using some of our pre-built example schemas, click the following endpoint URL: https://amplience-examples.cdn.content.amplience.net/graphql/

Related pages

• GraphQL Content Delivery overview
• Filter