Create queries

Use GraphQL queries to fetch, filter, sort, and page content from Optimizely Graph so applications return only the data each view needs. The examples in this article use the Optimizely Alloy sample site as a concrete reference. Custom content types or data produce different results. See the Alloy documentation for CMS 12.

Prerequisites

Before you run the examples in this article, confirm the following:

• A working Optimizely Graph endpoint with a valid authentication key.
• Optimizely Alloy sample content synchronized to Optimizely Graph, or an equivalent CMS schema with the Content and StandardPage types.
• A GraphQL client (for example, GraphiQL) that targets the Optimizely Graph endpoint.

📘

Note

The recipes work with the GraphQL schema generated from the Alloy site defaults. Custom data or content types in the schema produce different results.

Select fields

Field selection narrows a response to only the data the application needs, which reduces payload size and removes unrelated content from the result. Use field selection as the building block for every other query pattern in this article.

Select fields (items) from objects of a specific type and return them. The following example gets two items (Name and Url) from objects of the type Content.

{
  Content(locale: en) {
    items {
      Name
      Url
    }
  }
}

Modify the previous recipe to select items from the StandardPage type instead of Content.

{
  StandardPage(locale: en) {
    items {
      Name
      Url
    }
  }
}

Match on values in fields

Filter results by field value so the response includes only the content that satisfies the conditions in the query. Use these patterns when an application needs to scope content by language, keyword, range, or any combination of those criteria.

Restrict results in GraphQL by field value. The following example gets Name, TeaserText, and MainBody items from the StandardPage objects whose locale is English (en) and whose MainBody field contains the string "alloy".

{
  StandardPage(
    locale: en
    where: {
      MainBody: {
        contains: "alloy"
      }
    }
  )
  {
    items {
      Name
      TeaserText
      MainBody
    }
  }
}

Building on the previous example, add another condition. The TeaserText must start with "explore".

{
  StandardPage(
    locale: en
    where: {
       MainBody: {
         contains: "alloy"
       }
       TeaserText: {
         startsWith: "explore"
       }
    }
  )
  {
    items {
      Name
      TeaserText
      MainBody
    }
  }
}

When combining two or more conditions, use a Boolean operator (such as OR) to match fields that meet one or the other conditions. The following example returns items from StandardPage objects whose MainBody contains "alloy" or whose TeaserText starts with "explore."

{
  StandardPage(
    locale: en
    where: {
      OR: [
        {
          MainBody: {
            contains: "alloy"
          }
        }
        {
          TeaserText: {
            startsWith: "explore"
          }
        }
      ]
    }
  )
  {
    items {
      Name
      TeaserText
      MainBody
    }
  }
}

Exclude results with NOT. The following recipe gets data where MainBody contains "alloy" and MetaKeywords contains one or more of the matching values, and TeaserText does not start with "explor%" (for example, "explore", "exploration", "exploring", and so on).

{
  StandardPage(
    locale: en
    where: {
      MainBody: {
      	contains: "alloy"
      }
      NOT: [
        {
          TeaserText: {
            like: "explor%"
          }
        }
      ],
      MetaKeywords: {
        in: ["Online seminar","collaboration", "Alloy Plan"]
      }
    }
  )
  {
    items {
      MainBody
      TeaserText
    }
  }
}

Certain field types, such as numbers and dates or date-times, can use comparison operators to select based on a range of values. The following example gets StandardPage objects whose Created field has a value between 2020-09-13 and 2020-10-3.

{
  StandardPage(
    where: {
      Created: {
        gte: "2012-09-13"
        lt: "2012-10-03"
      }
    }
  )
  {
    items {
      MainBody
      Created
    }
  }
}

Sort results

Sorting controls the order in which Optimizely Graph returns items so that lists, search results, and ranked views display in a predictable order. Combine sort criteria to break ties and surface the most relevant content first.

Sort GraphQL results with orderBy. The following example sorts results in ascending alphabetical order based on the value of the Name field.

{
  StandardPage(
    locale: en
    orderBy: {
      Name: ASC
    }
  )
  {
    Name
    Url
  }
}

Combine sorting criteria. The following example sorts its results by relevance first, then by name (in case two items have the same relevance).

{
  StandardPage(
    locale: en
    orderBy: {
      _ranking: RELEVANCE
      Name: DESC
    }
  )
  {
    items {
      Name
      Url
    }
  }
}

Select the number of results per page

Paging splits a large result set into smaller chunks so the application returns one page at a time instead of every match in a single response. Use paging to power search result pages, infinite scroll, and any view that needs predictable batch sizes.

Select the number of results returned by selecting a range in the total result set. The following example orders the results by relevance and then by Name (in case two results have the same relevance), and selects only the first five results with limit. Use this pattern to build the first page of five results for a search results page.

{
  StandardPage(
    locale: en
    limit: 5
    orderBy: {
      _ranking: RELEVANCE
      Name: DESC
    }
  )
  {
    items {
      Name
      Url
    }
  }
}

To build the next "page" of five results, use skip: 5 to pass over the first five results and select the next five (with limit: 5 again). Continue this pattern indefinitely by increasing skip by increments of five (or 10, 25, and so on).

{
  StandardPage(
    locale: en
    skip: 5
    limit: 5
    orderBy: {
      _ranking: RELEVANCE
      Name: DESC
    }
  )
  {
    items {
      Name
      Url
    }
  }
}

Learn more about how to handle large results.

Handle expired content

Expired content can still appear in GraphQL responses depending on the authentication method and request headers. Use the patterns in this section to decide whether to include or exclude expired content for each request, so that public pages hide stale content while editorial workflows continue to surface it.

The authentication method and request headers determine whether expired content appears in GraphQL query results by default.

• Expired content continues to display as Published in GraphQL. CMS does not trigger a status change when content expires.
• The StopPublish field indicates expiration in the following ways:
  • null – The content is not expired.
  • Past date – The content is expired.

Authentication behavior

The authentication method on the request determines the default treatment of expired content. Review the following options before choosing an authentication method for a client that must filter expired content automatically.

The following authentication methods determine how Optimizely Graph handles expired content:

• Public key (single CMS key) – Optimizely Graph filters out expired content automatically.
• Auth headers or Basic Auth keys – Optimizely Graph returns expired content unless the request excludes it explicitly.

Override with the cg-include-expired request header

The cg-include-expired request header overrides the default expiration behavior on a per-request basis. Use it when a single client needs to include or exclude expired content for specific queries without changing the authentication method.

Set the cg-include-expired request header to include or exclude expired content.

cg-include-expired: "true"   # Include expired
cg-include-expired: "false"  # Exclude expired

Example query for expired content

The following query returns StandardPage objects and includes the StopPublish field, which lets a client check expiration on each item. When the request adds the header cg-include-expired: false, Optimizely Graph returns only non-expired items.

{
  StandardPage(locale: en) {
    items {
      Name
      Url
      StopPublish
    }
  }
}