GraphQL queries

The GraphQL API gives you the ability to query all kinds of UserPoint data as collected by the platform (profile, activities, segments, identifiers, etc.) with a single request.

Each GraphQL query is meant to fetch a single UserPoint data. To query multiple UserPoint in a single query, depending on your use case, please refer to the OTQL queries and/or to the Query exports.

If you're not familiar with GraphQL and how to interact with such APIs, please refer to the official documentation: https://graphql.org/

GraphQL schema

The schema used in the GraphQL endpoint is based on the customer defined schema. To add/remove fields from the GraphQL API, the schema has to be updated accordingly.

GraphQL endpoint

POST /v1/datamarts/:datamartId/query_executions/graphql

Path Parameters

Name	Type	Description
datamartId	string	The datamartId in which the UserPoint data will be looked up

Request Body

Name	Type	Description
query	string	This parameter should include your GraphQL query, starting with "query MyQuery {...". Do not forget to escape double quotes if needed.

200

{
    "data": { ...GraphQL response... }
}

429

{
    "error": "..."
}

GraphQL editor

To test and write GraphQL queries, we recommend you using our GraphQL editor:

1. Head to the Computing Console

2. Click on GraphQL menu under DATA STUDIO section

Limits

Through the GraphQL endpoint, only queries (reads) are supported. Mutations (writes) are not supported.

This endpoint is being rate-limited and will respond with 429 HTTP status code if the QPS exceed its limits. Please discuss with your account manager to have more information about this rate limiting and to request any limit increase.

The user activities number retuned is also limited. A query return to maximum 100 activities. Be careful, there is not warning and you can't change this limit yet.

Moreover, an user event is always in an activity so, this limitation is indirectly apply on the events. The query will return only the event in the hundred first activities.

Query examples

# Return the UserPoint creation_ts field
query MyQuery {
  user_point(user_point_id: "xxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx") {
    creation_ts
  }
}

# Return profiles, accounts, segments and scenarios data of a UserPoint
# Warning: This query relies on a customer defined schema so it may not
# work as-is on your datamart.
query MyQuery {
  user_point(user_point_id: "xxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx") {
    id
    creation_ts
    profiles {
      gender
      birth_date
    }
    accounts {
      compartment_id
      user_account_id
    }
    segments {
      id
    }
    scenarios {
      scenario_id
    }
  }
}

Selecting a UserPoint

You can select a UserPoint by any identifier using different functions.

# Select by UserPoint ID
query MyQuery {
  user_point(user_point_id: "xxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx") {
    id
    creation_ts
  }
}

# Select by email hash
query MyQuery {
  user_point_by_email_hash(email_hash: "xxxxxxxxxxxxxxxxxxx") {
    id
    creation_ts
  }
}

# Select by user account
# Both compartment ID and user account ID are mandatory
query MyQuery {
  user_point_by_user_account_id(
    compartment_id: "XXXX",
    user_account_id: "xxxx-xxx-xx-xxxxx"
    ) {
    id
    creation_ts
  }
}

# Select by user agent ID
query MyQuery {
  user_point_by_user_agent_id(user_agent_id: "xxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx"){
    id
    creation_ts
  }
}

For more information, see User identifiers

Filters

To only select elements matching a specific clause, use @filter. This clause is a WHERE object tree expressions, so you can use any thing like it was this kind of expression.

query micsQuery {
  user_point(user_point_id:"xxx") {
    activities {
      #only return events with the name "$home_view"
      events @filter(clause: "name == \"$home_view\""){ 
        ts
      }
    }
  }
}

Be carful the @filter is applied after the limitation of the activities. So if your query does not return activities it only mean there isn't activities which respect your condition in the hundred first of the UserPoint select.