> ## Documentation Index
> Fetch the complete documentation index at: https://cubed3-feat-druid-driver-streaming.mintlify.site/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.
</Warning>

## 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`](/reference/configuration/environment-variables#cubejs_default_api_scopes) environment variable to
`meta,data`.

To find your GraphQL API endpoint in Cube Cloud, go to the **Overview**
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:

<CodeGroup>
  ```yaml title="YAML" theme={null}
  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={null}
  cube(`orders`, {
    sql_table: `orders`,

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

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

      created_at: {
        sql: `created_at`,
        type: `time`
      }
    }
  })
  ```
</CodeGroup>

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

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

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

```json theme={null}
{
  "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={null}
{
  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={null}
{
  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={null}
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={null}
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={null}
{
  cube {
    orders {
      status
      count
      created_at {
        month
      }
    }
    products {
      count
    }
  }
}
```

[ref-schema-ref-preagg-granularity]: /reference/data-modeling/pre-aggregations#granularity

[ref-rest-api]: /reference/core-data-apis/rest-api

[ref-api-scopes]: /reference/core-data-apis/rest-api#configuration-api-scopes

[ref-cors]: /reference/core-data-apis/rest-api#configuration-cors

[graphql]: https://graphql.org

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

[ref-ref-graphql-api]: /reference/core-data-apis/graphql-api/reference

[ref-websockets]: /reference/core-data-apis/rest-api/real-time-data-fetch#web-sockets

[ref-subscriptions]: /reference/core-data-apis/rest-api/real-time-data-fetch#client-subscriptions

[ref-compare-date-range]: /reference/core-data-apis/queries#compare-date-range-query

[ref-metadata]: /reference/core-data-apis/rest-api/reference#base_path/v1/meta

[ref-pivot-config]: /reference/javascript-sdk/reference/cubejs-client-core#pivotconfig

[ref-segments]: /reference/data-modeling/segments