GraphQL API

🐣 Preview

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

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/cubejs-api/graphql in your browser. You should see the GraphiQL interface:

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"
    }
  ]
}

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
      }
    }
  }
}

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
    }
  }
}

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
    }
  }
}

query {
  cube [([cubeQueryArgs])] {
    <cubeName> [([cubeArgs])] {
      <cubeMember>
    }
  }
}
KeySchemaDescription
cubeQueryArgsCubeQueryArgsOptions that apply to the entire query
cubeArgsCubeArgsOptions that apply only to a specific cube

KeySchemaDescription
whereRootWhereInputRepresents a SQL WHERE clause
limitIntA row limit for your query. The default value is 10000. The maximum allowed limit is 50000
offsetIntThe number of initial rows to be skipped for your query. The default value is 0
timezoneStringThe timezone to use for the query. The default value is UTC
renewQueryBooleanIf renewQuery is set to true, Cube.js will renew all refreshKey for queries and query results in the foreground. The default value is false

KeySchemaDescription
AND[RootWhereInput!]
OR[RootWhereInput!]
<cubeName>CubeWhereInput

KeySchemaDescription
whereCubeWhereInput
orderByCubeOrderByInput

KeySchemaDescription
AND[RootWhereInput!]
OR[RootWhereInput!]
<cubeMember>Filter

KeySchemaDescription
<cubeMember>OrderBy

DateTimeFilter | FloatFilter | StringFilter

KeySchemaDescription
equalsString
notEqualsString
in[String]
notIn[String]
inDateRange[String]
notInDateRange[String]
beforeDateString
afterDateString
setBoolean

KeySchemaDescription
equalsFloat
notEqualsFloat
in[Float]
notIn[Float]
setBoolean

KeySchemaDescription
equalsString
notEqualsString
in[String]
notIn[String]
containsString
notContainsString
setBoolean

asc | desc

Did you find this page useful?