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, whereas 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 metric_time and country)

mutation {
    createMqlQuery(
        input: {
            metrics: ["revenue_usd"],
            groupBy: ["metric_time", "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
        }
    }
}