HomeGuidesAPI ReferenceGraphQL
Submit Documentation FeedbackJoin Developer CommunityLog In

Getting Started with GraphQL

What is GraphQL?

GraphQL is a query language for data that is available via API. It allows the developer to ask for exactly the data wanted, in the shape wanted.

Relative to a REST API, GraphQL has the following benefits:

  • Ability to ask for the fields needed, rather than provide all the fields
  • Well supported, good client libraries
  • Allows for joins between data dimensions in a real-time request

For more information, visit https://graphql.org/.

Choosing GraphQL vs REST with Zaius

Bulk events

For events across many customers use the Optimizely Data Platform (ODP) Exports API.
Example: Export all send events for a particular campaign.

Bulk Dimensions

For bulk dimensions (either all values or values filtered in a particular way) you can use either GraphQL or the ODP Exports API. We recommend using the ODP Exports API anytime you expect more than 1,000 entities in your result. The maximum page size in GraphQL is 1,000 and cursors can be used to retrieve multiple pages; however, the latency cost of paginating through will eventually exceed the latency overhead of the ODP Exports API, making Exports the more performant option.

Example: Export all customers with their consent status. Use the Exports API.

Example: Export all customers with have opted-out in the last hour. Use GraphQL.

Point data that crosses dimensions

For data about a single thing (like a set of events or a customer), but which requires joining across dimensions (such as adding product details), use the GraphQL endpoint. This endpoint allows for joins on a single point in real time across dimensions.

Example: Retrieve details about a purchase, and add in product details like the name and image URL.

Single-purpose point data

For data limited to a single point on a single dimension, either approach is available and it's a matter of preference. However, for performance reasons, ODP recommends GraphQL.

Example: Retrieve consent or reachability details for an identifier.