Core Concepts

9 min

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 GraphQL.org.

📘 Note Use GraphQL to query real-time segments for customer events within the last 28 days. If you want to use data greater than 28 days old, use the standard segments on the Customers > Segments page (see Create segments).

GraphQL terminology

Throughout the documentation you will come across with following terminologies.

Schema

The schema defines ODP GraphQL type system. It describes the complete set of possible data (objects, fields, relationships) that a client can access. For more information, see Discovering the GraphQL API.

Field

A field is a unit of data you can retrieve from an object. It is explained in GraphQL docs as "GraphQL query language is basically about selecting fields on objects."

Argument

An argument is a set of key-value pairs attached to a specific field. It can be either required or optional depending on the implementation.

Connection

Connections allow you to query related objects as part of the same call. With connections, you can use a single GraphQL call where you would have to use multiple calls to a REST API. For example, Point data that crosses dimensions

Edge

Edges represent connections between nodes. When you query a connection, you traverse its edges to get to its nodes. Every edges field has a node field and a cursor field. Cursors are used for pagination.

Node

Nodes represent objects. You can look up a node directly, or you can access related nodes via a connection. If you specify a node that does not return a scalar, you must include subfields until all fields return scalars.

Scalars

Scalars are the primitive types at the leaves of a GraphQL query: numbers, strings and booleans.

Discovering the GraphQL API

GraphQL is introspective which means you can query a GraphQL schema for details about itself.

Using GraphQL Explorer

Explore the schema and test queries using our GraphiQL UI.

For most dimensions, filtering is only available by the primary key(s). For special dimensions, like events and customers, additional filter options are available to specify the data returned. Explore the schema by clicking "Query" in the Documentation Explorer, or searching for a specific field.

All dimensions available in the account can be queried. Custom dimensions vary by account, but standard dimensions include:

events

customer

order

product

list

list_member

customer_observation

customer_insight

product_observation

product_insight

compliance

View custom dimensions on the account's Objects & Fields page.

Using GraphQL API

Query __schema to list all types defined in the schema and get details about each:

query {
  __schema {
    types {
      name
      kind
      description
      fields {
        name
      }
    }
  }
}

Query __type to get details about any type:

query {
  __type(name: "Customer") {
    name
    kind
    description
    fields {
      name
    }
  }
}