--- title: Create queries slug: graph/docs/create-queries docTags: createdAt: 2026-07-30T20:30:18.888Z --- 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](https://docs.developers.optimizely.com/content-management-system/docs/installing-optimizely-net-5#/install-a-cms-sample-site-with-alloy-templates) 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. :::hint{type="info"} **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`. ```graphql { Content(locale: en) { items { Name Url } } } ``` Modify the previous recipe to select items from the `StandardPage` type instead of `Content`. ```graphql { 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". ```graphql { 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". ```graphql { 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." ```graphql { 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). ```graphql { 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`. ```graphql { 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. ```graphql { 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). ```graphql { 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. ```graphql { 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). ```graphql { StandardPage( locale: en skip: 5 limit: 5 orderBy: { _ranking: RELEVANCE Name: DESC } ) { items { Name Url } } } ``` ## 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. ```http 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. ```graphql { StandardPage(locale: en) { items { Name Url StopPublish } } } ```