HomeDev GuideRecipesAPI ReferenceGraphQL
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunityDoc feedbackLog In
GitHubNuGetDev CommunityDoc feedback

Create queries

Describes how to create queries using the GraphQL querying services.

The following examples are based on the Optimizely Alloy sample site. See the Alloy documentation.

📘

Tip

The following recipes work with the GraphQL schema generated from the Alloy site defaults. If you customize the data or content types in these examples, your results may vary.

Select fields

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

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

Building on the previous recipe, you can modify the previous recipe to select items from the StandardPage type.

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

Match on values in fields

You can use fields in GraphQL to restrict results based on their value. The following recipe gets Name, TeaserText, and MainBody items from StandardPage objects whose locale is English (en), but adds another condition: the MainBody field must contains the string "alloy".

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

Building off of the previous example, you can 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, you can use a Boolean operator (such as OR) to match fields that meet one or the other condition. The following recipe 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
    }
  }
}

You can also negatively restrict results with NOT. This recipe gets data where:

  • MainBody has "alloy"
  • and its MetaKeywords have one or more of the matching values
  • but it does not have a TeaserText field starting with "explor%" (e.g. "explore", "exploration", "exploring", etc)
{
  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 date/datetimes, can use comparison operators to select based on a range of values. The following recipe 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

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

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

You can also combine sorting criteria. The following recipe sorts its results by relevance first, then name (in case two items have the same relevance).

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

Select number of results per page

You can select the number of results returned by selecting a range in the total result set. This can be useful to "page" through the results one chunk at a time.

The following recipe orders results by relevance and then by Name (in case two results have the same relevance) and selects just the first five results by using limit. Using this recipe, you can create 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, you can use skip: 5 to pass over the first five results and select the next five (with limit: 5 again). You can continue this pattern indefinitely by increasing skip by increments of five (or ten, twenty-five, and so forth).

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