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.

Alpha Release Disclaimer

The feature discussed in the following documentation is in Alpha Release.

Participation in Alpha releases gives you the opportunity to benefit from early-stage functionalities in your mediarithmics platform environments. The feedback you are willing to provide to mediarithmics will be considered with the highest attention to shape the future stable release.

However, an Alpha release also means that what is described hereafter might change before the Stable Release. To improve the quality of the Software Services it provides, mediarithmics reserves the right to add, modify, or remove at any time any element related to this feature. This includes functional behaviors, backward compatible and non-backward compatible changes in APIs, User Interface modifications, review of the estimated SLA etc.

Moreover, features in Alpha Release cannot be subject to SLA guarantees.

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": "..."
}

Tools

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

We recommend you to use the GraphQL Playground that is available in our computing console.

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.