GraphQL queries

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

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

Alpha Release Disclaimer

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 user point 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.

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

Tools

To test/write GraphQL queries, it is best to use a dedicated editor.

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.

Query examples

# Return the User Point 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 User Point
# 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 user point

You can select a user point by any identifier using different functions.

# Select by user point 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
      }
    }
  }
}

Last updated

Was this helpful?