Disclaimer: This website requires Please enable JavaScript in your browser settings for the best experience.

HomeDev guideRecipesAPI Reference
Dev guideUser GuidesNuGetDev CommunityOptimizely AcademySubmit a ticketLog In
Dev guide

Where

Describes the where parameter, which is part of the GraphQL API used for the Optimizely querying service.

The where parameter in Optimizely Graph lets you filter and search for values within your query, helping refine the results you receive. This capability is essential for tailoring the data to meet your specific needs, whether reducing or expanding the retrieved results.

where: [{filter_condition}]

The filter_condition is defined like the following:

predicate: {
      filter_operators: expression
}

You can use the GraphiQL schema explorer to understand how the where parameter works. This tool visually represents the available fields and their types, letting you identify which fields can be filtered using the where parameter. It differs depending on the Content Type, but some are included as part of the original graph query language. Common fields are defined by the abstract content types that start with an I.

Definitions

In Optimizely Graph, certain fields are universally available as part of the query language, especially those defined by abstract content types that usually start with I. These fields provide standard filtering capabilities across various content types, ensuring flexibility and consistency in query formulation.

  • {filter_condition} – Defines the conditions to be met for the result to be returned by Optimizely Graph. There is no limit to the number of predicates that can be included in a filter_condition.
  • predicate – A field name.
  • filter_operators – Matching functions (called "operators") that operate specifically on string, number, date, and Boolean values, and operator options like boost and synonyms that work together with the operators.
  • expression – A string, numeric, enumerated, or Boolean value.

📘

Note

  • Optimizely Graph supports using _modified extend argument to query content. Whenever content is synced to the service, that content would be marked with _modified extend field equal to now().
  • For numeric filtering (for example, gt, gte, lt, lte) with floating point numbers, Optimizely Graph supports accurate filtering up to three decimals.
    • For example,gt: 18.524 is accurate. However, for gt: 18.5243 the remainder decimals after three decimals are ignored.
filter_operatorsDescriptionString typeSearchableString typeNumber typeDate typeBoolean type
eqUsed to test equality between two literal expressions, can be case-insensitive.YesYesYesYesNo
noteqUsed to test the condition of two literal expressions not being equal to each other, can be case-insensitive.YesYesYesYesNo
likeDetermines whether a specific character string matches a specified pattern.YesYesNoNoNo
containsFilter fields that contain character-based data for precise or less precise matches to single words and phrases.NoYesNoNoNo
gtUsed to test the condition of one expression being greater than another.NoNoYesYesNo
gteUsed to test the condition of one expression being greater than or equal to another.NoNoYesYesNo
ltUsed to test the condition of one expression being less than another.NoNoYesYesNo
lteUsed to test the condition of one expression being less than or equal to another.NoNoYesYesNo
existDetermines whether a specific expression exists.YesYesYesNoYes
startsWithDetermines whether a specific expression starts with a specific pattern.YesYesNoNoNo
endsWithDetermines whether a specific expression ends with a specific pattern.YesNoNoNoNo
inDetermines whether a specific literal expression is in an array.YesYesYesNoNo
notInDetermines whether a specific literal expression is not in an array.YesYesYesNoNo
boostBoost a {filter_condition} by a positive number, so certain results can be ranked higher when sorting by RELEVANCE.YesYesYesYesYes
synonymsPermits the expansion of the expression with synonyms stored in the system.YesYesNoNoNo

Examples

The following examples show how to use some common filter conditions in the where clause:

Where with eq operators

{
  BiographyPage(where: {
    Name: {
         eq: "Alan Turing"
     }
  }, locale: [en]) {
    Name
    Language {
      Name
      DisplayName
    }
  }
}

Query with dates

Querying for date values is flexible. You can query for exact date values indexed in the ISO 8601 standard.

{
  BiographyPage(where: { Born: { eq: "1983-11-14T00:00:00Z" } }) {
    items {
      Name
      Born
    }
    total
  }
}

You can write this date query in a different format, but you must specify the time zone UTC. Otherwise, the date value is converted to a date value from the local system, resulting in no matches.

{
  BiographyPage(where: { Born: { eq: "11/14/1983 00:00:00 AM UTC" } }) {
    items {
      Name
      Born
    }
    total
  }
}

The power of the date query is that you can query for results between time ranges, with an optional time. This query returns results where the value for Born is equal or greater than "1947-07-30".

{
  BiographyPage(where: { Born: { gte: "1947-07-30" } }) {
    items {
      Name
      Born
    }
    total
  }
}

Where with multiple filter conditions

{ 
  BiographyPage(where: {
      Name: {
        eq: "Alan Turing"
      }
      Language: {
        DisplayName: {
          eq: "English"
        }
      }
  }, locale: [en]) {
    Name
    Language {
      Name
      DisplayName
    }
  }
}

📘

Note

The AND operator is the default logical operator that applies to the group of multiple filtered conditions, so the above query can be understood like the following:

if (Name == "Alan Turing" AND Language.DisplayName == "English")

See Logical connectors for information about logical operators AND, OR, and NOT.

Where with _modified extend date argument.

The _modified field contains the date time when content was created, updated, or deleted in the service. The value in _modify is not the same as the created or saved value on the content.

The _modified field can be used to accomplish a delta import of content from the service. For example, "give me content that was modified after (gt) 2023-09-13T04:36:14Z". You can use filtering by _modify field with cursor to accomplish the delta import of content from the service.

{ 
  BiographyPage(where: {
      _modified: {
        gte: "2021-09-13T04:36:14Z"
      }
  }, locale: [en]) {
    Name
    Language {
      Name
      DisplayName
    }
  }
}