Skip to main content

Overview

Transform has two GraphQL APIs that can be queried:

  1. Backend API: The backend API holds information about metric metadata and objects in the Transform. For example, it stores annotations, keys, and metric descriptions.
  2. MQL API: The MQL API holds the core of the metric data itself and allows you to slice and dice metrics by dimensions.

Both are valuable because one is primarily for the quantitative aspects of the metric, where as the other is about the qualitative.

The simplest way to query our APIs is via our API Explorer.

Our MQL API forms the basis for all our other interfaces below and acts as the single source of truth that all requests are routed through. This allows all downstream interfaces to enjoy the same ease-of-use, authentication, and reliability promises made by this core API layer. You can switch between the backend API and the MQL API from the top of the page. The metric data can be supplemented with contextual information that the backend API has to offer.

Benefits of GraphQL

  • A strongly-typed API schema reduces bugs, and allows our API to be fairly self-documenting.
  • GraphQL queries allow clients to build the query response they want, rather than having to piece together data across different endpoints.
  • GraphiQL, a GraphQL IDE allows our users to easily explore the graph and iteratively build and test the queries they want to make (more below):

Example GraphQL Request against MQL API#

The following are sample GraphQL queries to do basic operations on metrics.

Ensure you select the MQL Server radio button at the top of the API explorer page because these examples are specifically for issuing queries against the MQL GraphQL API (not Transform's backend API which is a separate)

For a client to make requests, they must be authenticated with an API key. To provide the API key specify a header in the form:

Authorization: X-Api-Key API_KEY_HERE

List all Metrics with Dimensions#

query MetricList($modelKey: ModelKeyInput) {    metrics(modelKey: $modelKey) {        name        measures        type        typeParams {            numerator            denominator            expr            window        }        constraint        dimensionObjects {            name            identifierName            identifierNames            type            isPrimaryTime            timeGranularity            cardinality        }    }}

Query a certain metric#

query MetricQuery($modelKey: ModelKeyInput, $metricName: String!) {    metricByName(modelKey: $modelKey, name: $metricName) {        name        measures        type        typeParams {            numerator            denominator            expr            window        }        constraint        dimensionObjects {            name            identifierName            identifierNames            type            isPrimaryTime            timeGranularity            cardinality        }    }}

Example of a query with a metric called revenue_usd (with two dimensions ds and country)#

mutation {    createMqlQuery(        input: {            metrics: ["revenue_usd"],            groupBy: ["ds", "customer__country"],        }    ) {        id     } }

List all Dimensions#

query MetricQuery($modelKey: ModelKeyInput, $metricName: String!) {    metricByName(modelKey: $modelKey, name: $metricName) {        name        measures        type        typeParams {            numerator            denominator            expr            window        }        constraint        dimensionObjects {            name            identifierName            identifierNames            type            isPrimaryTime            timeGranularity            cardinality        }    }}

Issue a Query against Metrics:#

mutation CreateMqlQueryMutation(    $modelKey: ModelKeyInput,    $metrics: [String!],    $groupBy: [String!],    $whereConstraint: String,    $timeConstraint: String,    $timeGranularity: TimeGranularity,    $order: [String!],    $limit: LimitInput,    $cacheMode: CacheMode,    $asTable: String,    $timeSeries: Boolean,    $resultFormat: ResultFormat,    $pctChange: PercentChange,    $allowDynamicCache: Boolean,) {    createMqlQuery(        input: {            modelKey: $modelKey,            metrics: $metrics,            groupBy: $groupBy,            whereConstraint: $whereConstraint,            timeConstraint: $timeConstraint,            timeGranularity: $timeGranularity,            order: $order,            limit: $limit,            cacheMode: $cacheMode,            asTable: $asTable,            addTimeSeries: $timeSeries,            resultFormat: $resultFormat,            pctChange: $pctChange,            allowDynamicCache: $allowDynamicCache        }    ) {        id    }}

Get a Query Status#

query GetMqlQueryResultsStatus($queryId: ID!) {    mqlQuery(id: $queryId) {        status        error        sql    }}

Fetch the Results of a Query and Paginate Results#

query GetMqlQueryResultsTabular($queryId: ID!, $cursor: Int) {    mqlQuery(id: $queryId) {        resultTabular(orient: TABLE, cursor: $cursor) {            nextCursor            data        }    }}

Backend API#

The Backend API holds metadata about your Transform instance and metrics. Make sure you choose the backend API when you are running these queries.

Query that returns the count of annotations you have in your Transform instance:

query Annotation {  myOrganization{    totalAnnotations  }}

Queries to retrieve a model key#

query LatestModelKeyQuery {    myOrganization {        currentModel {            id            organizationId            gitBranch            gitCommit            gitRepo            createdAt            isCurrent        }    }}
query ModelKeyQuery($modelId: ID) {    myOrganization {        models(id: $modelId){            id            organizationId            gitBranch            gitCommit            gitRepo            createdAt            isCurrent        }    }}