Introducing the Cube GraphQL API: Building GraphQL Endpoints for Metrics

At Cube, we’ve been excited to watch GraphQL’s growth in popularity and the rise of a rich and mature ecosystem of GraphQL front-end integrations and back-end tools. GraphQL has quickly become the most popular query language for APIs because it provides a complete description of the data in your API—giving clients the power to ask for exactly the data they need and nothing more.

However, I believe that while the GraphQL ecosystem is rich in tools focused on creating transactional (a.k.a. CRUD) GraphQL servers, analytical workloads are still underserved. This is particularly true for workloads designed on top of data warehouses.

For more than a year, a Cube GraphQL API has been the top requested feature from the Cube community. There’s clearly tremendous value for GraphQL users in having a uniform way to access both transactional and analytical APIs, in order to keep the data layer unified and organized.

Today, we are excited to announce GraphQL API support in Cube. With this release, you can use Cube as part of your GraphQL layer to deliver metrics to your application.

We owe tremendous thanks to Luc Vauvillier, the COO and a co-founder at Gadsme, who contributed initial support for this GraphQL API and layed out the principal design:

“With GraphQL support in Cube we can have a unified typed API for our frontend clients and be able to run code generators”. We built a GraphQL proxy on top of the Cube REST API internally first. Then we started to share our API design with the community, and when we realized that the additional work to make it generic would not be too substantial, we decided to contribute to have it officially supported. At Gadsme, contributing to open source projects is part of our values and we really enjoyed working on this.”

With this API and our recently-released SQL API, Cube can provide analytics data to a wide variety of tools and clients building towards our vision of a universal, headless analytics layer to provide metrics to any application.

Getting Started with the GraphQL API

Cube uses a JSON-based metrics framework to describe data calculations that can be exposed via GraphQL. Once defined, Cube will use these definitions to translate an incoming GraphQL query into a native SQL query to the underlying data storage layer.

Let’s consider the following example of Cube’s metrics framework that can be used to model orders in a hypothetical ecommerce data store:

cube(`Orders`, {
  sql: `SELECT * FROM public.orders`,

  measures: {
    count: {
      type: `count`,
    },
  },

  dimensions: {
    status: {
      sql: `status`,
      type: `string`,
    },

    createdAt: {
      sql: `created_at`,
      type: `time`,
    },
  },
});

The main object in Cube’s merics framework is cube. Cubes always have the sql property. Usually, this points to the SQL table to which this configuration applies, but in more sophisticated use cases, a custom SQL query can be used as a property.

Measures are quantitative data—such as the number of units sold, unique visits, profit, and so forth. Dimensions are categorical data, such as state, gender, product name, or units of time. (You can learn more about Cube’s data schema in our docs.)

Once the above definitions are created, we can start querying Cube via the GraphQL API. To get “Number of orders grouped by status,” we can use the following query:

{
  cube {
    orders {
      count
      status
    }
  }
}

Cube will translate the above GraphQL query into a native SQL for your database and execute it. For example, if your database is Postgres, it would be the following SQL query:

SELECT
  "orders".status "orders__status",
  count("orders".id) "orders__count"
FROM
  public.orders AS "orders"
GROUP BY
  1
ORDER BY
  2 DESC
LIMIT
  10000

Cube users probably are aware that Cube comes with Developer Playground, a useful tool to build and test metrics layer. Now, the Playground includes a built-in GraphiQL to test GraphQL API calls.

To get started with the GraphQL API from scratch, you can follow this step-by-step guide.

We’re excited about finally bringing GraphQL support to Cube, and we hope you are, too! We’d love to hear your feature requests and use cases; please provide your feedback in our Slack.

Want to learn more? Give Cube a free try.