Graph Query Language Reference

Try it live

Graph API Explorer

API Key Run Query

Query

query { Content(limit: 5) { items { Name ContentType _metadata { published url { default } } } total } }

Results

Click "Run Query" to execute

https://cg.optimizely.com/content/v2 Enter your Graph SingleKey above to query your own content

Query structure

Every Graph query targets a content type and returns items, metadata, and optional facets:

query {
  ContentTypeName(
    where: { /* filter conditions */ }
    orderBy: { /* sort fields */ }
    limit: 10
    skip: 0
    cursor: "opaque-cursor-string"
    locale: en
  ) {
    items { /* selected fields */ }
    total
    cursor
    facets { /* aggregation buckets */ }
  }
}

Comparison operators

Use these operators inside where clauses to filter results by field values.

String operators

Operator	Description	Syntax	Example
eq	Equals (exact match)	{ Field: { eq: "value" } }	{ Status: { eq: "Published" } }
notEq	Not equals	{ Field: { notEq: "value" } }	{ Category: { notEq: "Draft" } }
in	In list (any match)	{ Field: { in: ["a", "b"] } }	{ Category: { in: ["News", "Blog"] } }
notIn	Not in list	{ Field: { notIn: ["a"] } }	{ Status: { notIn: ["Archived"] } }
like	Wildcard match	{ Field: { like: "%pattern%" } }	{ Title: { like: "%optimizely%" } }
contains	Contains substring	{ Field: { contains: "text" } }	{ Body: { contains: "getting started" } }
startsWith	Prefix match	{ Field: { startsWith: "text" } }	{ Name: { startsWith: "Product" } }
endsWith	Suffix match	{ Field: { endsWith: "text" } }	{ Email: { endsWith: "@example.com" } }
exists	Has any value	{ Field: { exists: true } }	{ HeroImage: { exists: true } }

Numeric operators

Operator	Description	Syntax	Example
eq	Equals	{ Field: { eq: 100 } }	{ Price: { eq: 49 } }
notEq	Not equals	{ Field: { notEq: 0 } }	{ Stock: { notEq: 0 } }
gt	Greater than	{ Field: { gt: 100 } }	{ Price: { gt: 50 } }
gte	Greater than or equal	{ Field: { gte: 4 } }	{ Rating: { gte: 4 } }
lt	Less than	{ Field: { lt: 10 } }	{ Stock: { lt: 10 } }
lte	Less than or equal	{ Field: { lte: 30 } }	{ Age: { lte: 30 } }
in	In list	{ Field: { in: [1, 2, 3] } }	{ Priority: { in: [1, 2] } }

Date operators

Date values use ISO 8601 format. All numeric comparison operators apply:

where: {
  _metadata: {
    published: { gte: "2025-01-01T00:00:00Z" }
  }
  EventDate: { lt: "2026-12-31T23:59:59Z" }
}

Boolean logic

AND (default)

All conditions at the same level use AND logic. Every condition must match:

where: {
  Status: { eq: "Published" }
  Category: { eq: "News" }
  Author: { exists: true }
}

OR

Use _or to match any condition in the array:

where: {
  _or: [
    { Category: { eq: "News" } }
    { Category: { eq: "Blog" } }
    { Tags: { in: ["featured"] } }
  ]
}

NOT

Use _not to negate a condition:

where: {
  _not: { Status: { eq: "Archived" } }
}

Combined logic

Nest boolean operators for complex conditions:

where: {
  _metadata: { status: { eq: "Published" } }
  _or: [
    { Category: { eq: "News" } }
    {
      Category: { eq: "Blog" }
      Tags: { in: ["featured"] }
    }
  ]
  _not: { Author: { eq: "Anonymous" } }
}

Filter arguments

where

Filters results by field conditions. See operator tables above.

orderBy

Sorts results by one or more fields:

# Single field
orderBy: { PublishedDate: DESC }

# Multiple fields (ordered by priority)
orderBy: { Category: ASC, PublishedDate: DESC }

# Metadata fields
orderBy: { _metadata: { published: DESC } }

# Search relevance
orderBy: { _ranking: RELEVANCE }

# Semantic similarity
orderBy: { _ranking: SEMANTIC }

Direction	Behavior
ASC	Ascending (A-Z, oldest first, lowest first)
DESC	Descending (Z-A, newest first, highest first)

limit

Maximum items to return per query. Default: 20. Maximum: 100.

ArticlePage(limit: 50) { ... }

skip

Number of items to skip (offset-based pagination). Avoid for deep pagination — use cursor instead.

ArticlePage(limit: 10, skip: 20) { ... }

cursor

Opaque cursor string for efficient pagination. Returned in the response and passed to the next query:

# First request
ArticlePage(limit: 10) {
  items { Headline }
  cursor
}

# Subsequent request
ArticlePage(limit: 10, cursor: "eyJsaW1pdCI6MTB9") {
  items { Headline }
  cursor
}

locale

Filter by content language:

# Single locale
ArticlePage(locale: en) { ... }

# Multiple locales
ArticlePage(locale: [en, sv, de]) { ... }

# All locales
ArticlePage(locale: ALL) { ... }

Inline fragments for polymorphic content

Use inline fragments to query type-specific fields when querying interfaces or content areas:

query {
  Content(
    where: { _metadata: { types: { eq: "Page" } } }
    limit: 20
  ) {
    items {
      _metadata { key types url { default } }
      ... on ArticlePage {
        Headline
        Author
      }
      ... on ProductPage {
        ProductName
        Price
      }
      ... on LandingPage {
        HeroTitle
        HeroImage { url }
      }
    }
  }
}

Content area items use the same pattern:

MainContentArea {
  ... on TextBlock { Body { html } }
  ... on ImageBlock { AltText Image { url } }
  ... on VideoBlock { EmbedUrl Caption }
}

Full-text search

_fulltext search

Search across all full-text indexed fields:

where: {
  _fulltext: { contains: "content modeling best practices" }
}

_autocomplete

Provide type-ahead suggestions with prefix matching:

query Autocomplete($prefix: String!) {
  ArticlePage(
    where: {
      _fulltext: {
        _autocomplete: { contains: $prefix }
      }
    }
    limit: 5
  ) {
    items {
      Headline
      _metadata { url { default } }
    }
  }
}

Search result fields

Field	Type	Description
_fulltext	[String]	Matched text fragments with highlights
_score	Float	Relevance score (higher = more relevant)
_ranking	Sort option	RELEVANCE, SEMANTIC

Boosting

Boost specific fields to increase their weight in relevance scoring:

where: {
  _fulltext: {
    contains: "search term"
    boost: {
      Headline: 5
      Summary: 3
      Tags: 2
      ArticleBody: 1
    }
  }
}

Higher boost values make matches in that field rank higher. Default boost is 1 for all fields.

Synonyms

Enable synonym expansion to match related terms:

where: {
  _fulltext: {
    contains: "laptop"
    synonym: ON
  }
}

Value	Behavior
ON	Expand query with configured synonym sets
OFF	Match only the exact terms (default)

Synonyms are configured through the Graph admin API. See Configure Synonyms.

Pinned results

Pinned results appear at the top of search results for specific query terms, regardless of relevance score. Configure pinned results through the admin API.

Pinned results are automatically applied when the query matches a configured pin rule. No query-side syntax is needed — the Graph backend injects pinned items at the top of the result set.

Facets (aggregations)

String facets

facets {
  Category(limit: 10, orderBy: COUNT, orderType: DESC) {
    name
    count
  }
}

Parameter	Description
limit	Maximum facet values to return
orderBy	COUNT or VALUE
orderType	ASC or DESC

Date facets

facets {
  _metadata {
    published(unit: MONTH) {
      name
      count
    }
  }
}

Unit	Bucket size
DAY	One calendar day
WEEK	One calendar week
MONTH	One calendar month
YEAR	One calendar year

Number range facets

facets {
  Price(
    ranges: [
      { from: 0, to: 25 }
      { from: 25, to: 50 }
      { from: 50, to: 100 }
    ]
  ) {
    name
    count
  }
}

Metadata fields

Every content item exposes system metadata through _metadata:

_metadata {
  key          # Content GUID
  locale       # Language code (en, sv, etc.)
  published    # ISO 8601 publish timestamp
  status       # Published, Draft, etc.
  types        # Array of content type names
  version      # Content version string
  url {
    default    # Primary URL path
    internal   # CMS internal URL
    base       # Base URL
    hierarchical # Full hierarchical path
  }
}

Rate limits

Constraint	Value
Max query depth	10 levels
Max result size	10,000 items
Default limit	20 items
Max limit per query	100 items
Query timeout	30 seconds
Max query complexity	1,000 points

Related

• Content Delivery with Graph — Architecture overview
• Graph Query Syntax — Quick syntax reference
• Write Complex Queries — Practical query patterns
• Query Optimization — Performance strategies