> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cube.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# GraphQL API

> Query Cube over HTTP using GraphQL for embedded analytics and front-end data applications.

GraphQL API

GraphQL API enables Cube to deliver data over the HTTP protocol to
[GraphQL][graphql]-enabled data applications, e.g., most commonly, front-end
applications.

Often, the GraphQL API is used to enable the [embedded analytics][cube-ea] use
case.

Under the hood, the GraphQL API is exposed via the `/graphql` endpoint of the
[REST (JSON) API][ref-rest-api].

See [GraphQL API reference][ref-ref-graphql-api] for the list of supported
requests and parameters.

> [!WARNING]
>
> Compared to the \[REST (JSON) API]\[ref-rest-api], GraphQL API currently has the
> following limitations:
>
> * No support for the \[WebSockets transport]\[ref-websockets].
> * No support for \[subscriptions to changes]\[ref-subscriptions].
> * No support for referencing \[segments]\[ref-segments] in queries.
> * No support for \[compare date range queries]\[ref-compare-date-range].
> * No support for querying \[data model metadata]\[ref-metadata].
> * No ability to apply a \[pivot config]\[ref-pivot-config] on the front-end.

## Configuration

GraphQL API is enabled by default and secured using [API scopes][ref-api-scopes]
and [CORS][ref-cors]. To disallow access to GraphQL API, disable the `graphql`
scope, e.g., by setting the [`CUBEJS_DEFAULT_API_SCOPES`](https://docs.cube.dev/reference/configuration/environment-variables#cubejs_default_api_scopes) environment variable to
`meta,data`.

The GraphQL schema is built for each caller from the members that
[access policies][ref-mls] make visible to them. Hidden members are absent from
introspection, and querying one fails GraphQL validation with a
`Cannot query field "<member>"` error (HTTP 400, no `data`). If no members are
visible at all, the schema contains only the
[`no_queries_available`][ref-no-queries-available] field.

To find your GraphQL API endpoint in Cube Cloud, go to the **Status**
page, click **API credentials**, and choose the **GraphQL API** tab.

## Getting started

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

```yaml title="YAML" theme={"dark"}
cubes:
  - name: orders
    sql_table: orders

    measures:
      - name: count
        type: count

    dimensions:
      - name: status
        sql: status
        type: string

      - name: created_at
        sql: created_at
        type: time
```

```javascript title="JavaScript" theme={"dark"}
cube(`orders`, {
  sql_table: `orders`,

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

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

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

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

```graphql theme={"dark"}
{
  cube {
    orders {
      count
      status
      created_at {
        day
      }
    }
  }
}
```

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

```json theme={"dark"}
{
  "measures": ["orders.count"],
  "dimensions": ["orders.status"],
  "timeDimensions": [
    {
      "dimension": "orders.created_at",
      "granularity": "day"
    }
  ]
}
```

### Modifying time dimension granularity

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

```graphql theme={"dark"}
{
  cube {
    orders {
      created_at {
        month
      }
    }
  }
}
```

[Any supported granularity][ref-schema-ref-preagg-granularity] can be used. If
you prefer to not specify a granularity, then use `value`:

```graphql theme={"dark"}
{
  cube {
    orders {
      created_at {
        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:

```graphql theme={"dark"}
query {
  cube(limit: 100, offset: 50, timezone: "America/Los_Angeles") {
    orders(
      orderBy: { created_at: asc, count: desc }
      where: { status: { equals: "completed" } }
    ) {
      count
      status
      created_at
    }
  }
}
```

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:

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

### 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:

```graphql theme={"dark"}
{
  cube {
    orders {
      status
      count
      created_at {
        month
      }
    }
    products {
      count
    }
  }
}
```

[ref-schema-ref-preagg-granularity]: https://docs.cube.dev/reference/data-modeling/pre-aggregations.md#granularity

[ref-rest-api]: https://docs.cube.dev/reference/core-data-apis/rest-api

[ref-api-scopes]: https://docs.cube.dev/reference/core-data-apis/rest-api#configuration-api-scopes

[ref-cors]: https://docs.cube.dev/reference/core-data-apis/rest-api#configuration-cors

[ref-mls]: https://docs.cube.dev/docs/data-modeling/access-control/member-level-security.md

[ref-no-queries-available]: https://docs.cube.dev/reference/core-data-apis/graphql-api/reference.md#no_queries_available

[graphql]: https://graphql.org

[cube-ea]: https://cube.dev/use-cases/embedded-analytics

[ref-ref-graphql-api]: https://docs.cube.dev/reference/core-data-apis/graphql-api/reference.md

[ref-websockets]: https://docs.cube.dev/recipes/core-data-api/real-time-data-fetch.md#web-sockets

[ref-subscriptions]: https://docs.cube.dev/recipes/core-data-api/real-time-data-fetch.md#client-subscriptions

[ref-compare-date-range]: https://docs.cube.dev/reference/core-data-apis/queries.md#compare-date-range-query

[ref-metadata]: https://docs.cube.dev/reference/core-data-apis/rest-api/reference.md#base_path/v1/meta

[ref-pivot-config]: https://docs.cube.dev/reference/javascript-sdk/reference/cubejs-client-core.md#pivotconfig

[ref-segments]: https://docs.cube.dev/reference/data-modeling/segments.md


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.