Skip to main content

GraphQL

GraphQL (GQL) is an open-source query language for APIs. It offers a more efficient and flexible approach compared to traditional RESTful APIs.

With GraphQL, users can request specific data using a single query, reducing the need for many server round trips. This improves performance and minimizes network overhead.

GraphQL has several advantages, such as self-documenting, having a strong typing system, supporting versioning and evolution, enabling rapid development, and having a robust ecosystem. These features make GraphQL a powerful choice for APIs that prioritize flexibility, performance, and developer productivity.

dbt Semantic Layer GraphQL API​

The dbt Semantic Layer GraphQL API allows you to explore and query metrics and dimensions. Due to it's self-documenting nature, you can explore the calls conveniently through the schema explorer.

dbt Partners can use the Semantic Layer GraphQL API to build and integration with the dbt Semantic Layer.

Using the GraphQL API​

If you're a dbt user or partner with access to dbt Cloud and the dbt Semantic Layer, you can setup and test this API with data from your own instance by configuring the Semantic Layer and obtaining the right GQL connection parameters described in this document.

Refer to Get started with the dbt Semantic Layer for more info.

Authentication​

Authentication uses a dbt Cloud service account tokens passed through a header as follows. To explore the schema, you can enter this information in the "header" section.

{"Authorization": "Bearer <SERVICE TOKEN>"}

Each GQL request also comes with a dbt Cloud environmentId. The API uses both the service token in the header and environmentId for authentication.

Metric metadata calls​

Use the following example calls to provide you with an idea of the types of commands you can use:

Fetch available metrics

metrics(environmentId: Int!): [Metric!]!

Fetch available dimensions for metrics

dimensions(
environmentId: Int!
metrics: [String!]!
): [Dimension!]!

Fetch available time granularities given metrics

queryableGranularities(
environmentId: Int!
metrics: [String!]!
): [TimeGranularity!]!

Fetch available metrics given a set of a dimensions

metricsForDimensions(
environmentId: Int!
dimensions: [String!]!
): [Metric!]!

Fetch dimension values for metrics and a given dimension

dimensionValues(
environmentId: Int!
metrics: [String!]!
dimension: String!

Metric value query parameters​

The mutation is createQuery. The parameters are as follows:

createQuery(
environmentId: Int!
metrics: [String!]!
dimensions: [String!] = null
limit: Int = null
startTime: String = null
endTime: String = null
where: String = null
order: [String!] = null
): String
0
Edit this page