GraphQL API

🐣 Preview

The Cube GraphQL API is currently in Preview, and there may be changes in a future version.

Getting started

The Cube GraphQL API does not currently support using variables from a GraphQL client. Instead inline variables directly in the query.

First, ensure you're running Cube v0.28.58 or later. Then start the project locally in development mode, and navigate to http://localhost:4000/ in your browser. After generating schema and running query you should see the GraphiQL interface if you click 'GraphiQL' button. If you click the 'Docs' button in the top-right, you can explore the introspected schema.

As an example, let's use the Orders cube from the example eCommerce database:

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

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

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

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

A GraphQL query to return the number of orders by status would look something like this:

{
  cube {
    orders {
      count
      status
      createdAt {
        day
      }
    }
  }
}

The equivalent query to the REST API endpoint would look like this:

{
  "measures": ["Orders.count"],
  "dimensions": ["Orders.status", "Orders.createdAt"],
  "timeDimensions": [
    {
      "dimension": "Orders.createdAt",
      "granularity": "day"
    }
  ]
}

Modifying time dimension granularity

The granularity for a time dimension can easily be changed by specifying it in the query:

{
  cube {
    orders {
      createdAt {
        month
      }
    }
  }
}

Any supported granularity can be used. If you prefer to not specify a granularity, then use value:

{
  cube {
    orders {
      createdAt {
        value
      }
    }
  }
}

Specifying filters and ranges

Filters can be set on the load query or on a specific cube. Specifying the filter on the load query applies it to all cubes in the query. Filters can be added to the query as follows:

query {
  cube(limit: 100, offset: 50, timezone: "America/Los_Angeles") {
    orders(
      orderBy: { createdAt: asc, count: desc }
      where: { status: { equals: "completed" } }
    ) {
      count
      status
      createdAt
    }
  }
}

Some other differences between the JSON query filters and the GraphQL filters to note:

number values are used for number types instead of strings
The notSet filter is replaced by { set: false }
New in and notIn filters to check for multiple values
AND and OR fields for boolean operators

The GraphQL API supports @skip and @include directives too:

query GetOrders($byStatus: Boolean) {
  cube(limit: 100, offset: 50, timezone: "America/Los_Angeles") {
    orders(
      orderBy: { createdAt: asc, count: desc }
      where: { status: { equals: "completed" } }
    ) {
      count
      status @include(if: $byStatus)
      createdAt
    }
  }
}

Querying multiple cubes

Using the same Orders cube as before, let's try and get the numbers of products for each order status too. We can do this by adding the Products cube to our query as follows:

{
  cube {
    orders {
      status
      count
      createdAt {
        month
      }
    }
    products {
      count
    }
  }
}

Reference

cube

query {
  cube [([cubeQueryArgs])] {
    <cubeName> [([cubeArgs])] {
      <cubeMember>
    }
  }
}

Key	Schema	Description
`cubeQueryArgs`	`CubeQueryArgs`	Options that apply to the entire query
`cubeArgs`	`CubeArgs`	Options that apply only to a specific cube

CubeQueryArgs

Key	Schema	Description
`where`	`RootWhereInput`	Represents a SQL `WHERE` clause
`limit`	`Int`	A row limit for your query. The default value is `10000`. The maximum allowed limit is `50000`
`offset`	`Int`	The number of initial rows to be skipped for your query. The default value is `0`
`timezone`	`String`	The timezone to use for the query. The default value is `UTC`
`renewQuery`	`Boolean`	If `renewQuery` is set to `true`, Cube will renew all `refreshKey` for queries and query results in the foreground. The default value is `false`

RootWhereInput

Key	Schema	Description
`AND`	`[RootWhereInput!]`
`OR`	`[RootWhereInput!]`
`<cubeName>`	`CubeWhereInput`

CubeArgs

Key	Schema	Description
`where`	`CubeWhereInput`
`orderBy`	`CubeOrderByInput`

CubeWhereInput

Key	Schema	Description
`AND`	`[RootWhereInput!]`
`OR`	`[RootWhereInput!]`
`<cubeMember>`	`Filter`

CubeOrderByInput

Key	Schema	Description
`<cubeMember>`	`OrderBy`

Filter

DateTimeFilter | FloatFilter | StringFilter

DateTimeFilter

Key	Schema	Description
`equals`	`String`
`notEquals`	`String`
`in`	`[String]`
`notIn`	`[String]`
`inDateRange`	`[String]`
`notInDateRange`	`[String]`
`beforeDate`	`String`
`afterDate`	`String`
`set`	`Boolean`

FloatFilter

Key	Schema	Description
`equals`	`Float`
`notEquals`	`Float`
`in`	`[Float]`
`notIn`	`[Float]`
`set`	`Boolean`

StringFilter

Key	Schema	Description
`equals`	`String`
`notEquals`	`String`
`in`	`[String]`
`notIn`	`[String]`
`contains`	`String`
`notContains`	`String`
`set`	`Boolean`

OrderBy

asc | desc

Did you find this page useful?