HomeDev guideAPI ReferenceGraphQL
Dev guideUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket

Create queries

How to create queries using the GraphQL querying services.

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

πŸ“˜

Note

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

Select fields

Select fields (items) from objects of a certain 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
    }
  }
}

Building on the previous example, 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 example gets Name, TeaserText, and MainBody items from the StandardPage objects whose locale is English (en), but adds another condition: the MainBody field must contain 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 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
    }
  }
}

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%" (for instance, "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

You can sort GraphQL results using orderBy. The following example 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 example 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 the 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 example orders the 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 example, 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
    }
  }
}