GraphQL API

Getting started

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

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

CubeQueryArgs

RootWhereInput

CubeArgs

CubeWhereInput

CubeOrderByInput

Filter

DateTimeFilter | FloatFilter | StringFilter

DateTimeFilter

FloatFilter

StringFilter

OrderBy

asc | desc