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

# Query History

> The Query History feature in Cube Cloud is a one-stop shop for all performance and diagnostic information about queries issued for a deployment.

It provides a real-time and historic view of requests to [data APIs][ref-apis] of your
Cube Cloud deployment, so you can check whether queries were accelerated with
[pre-aggregations][ref-caching-gs-preaggs], how long they took to execute, and if they
failed.

<Note>
  You can choose a [Query History tier](/admin/account-billing/pricing#query-history-tiers)
  to fit your retention and throughput needs.
</Note>

You can set the [time range](#setting-the-time-range), [explore queries](#exploring-queries)
and filter them, drill down on specific queries to [see more details](#inspecting-api-queries).

You can also use [Query History export][ref-query-history-export] to bring Query History
data to an external monitoring solution for further analysis.

<br />

<video width="100%" controls>
  <source src="https://ucarecdn.com/ceba0bdc-298b-44e6-8491-2b0e39985465/video.mp4" type="video/mp4" />
</video>

## Setting the time range

By default, Cube Cloud shows you a live feed of queries made to the API and
connected [data sources][ref-conf-db].

You can navigate throughout the query history by using the date picker in the
top right corner of the page and selecting a time period:

<Frame>
  <img src="https://ucarecdn.com/393dfa47-033d-421b-87ce-fcf5617ac1c8/" />
</Frame>

To go back to live mode, click **▶**:

<Frame>
  <img src="https://ucarecdn.com/393dfa47-033d-421b-87ce-fcf5617ac1c8/" />
</Frame>

## Exploring queries

You can switch between [queries made to the API](#inspecting-api-queries) and
[queries made to connected data sources](#inspecting-database-queries) by
switching between the **API** and **Database** tabs.

<Frame>
  <img src="https://ucarecdn.com/951a2a64-bc9b-4277-b2fe-4cc88dbf4f49/" />
</Frame>

### All queries and top queries

Clicking **All Queries** will show all queries in order of recency,
while **Top Queries** will show the queries with the largest total duration (hits \* avg duration) in the selected time frame. Both results are limited to 100 unique queries.

<Frame>
  <img src="https://ucarecdn.com/951a2a64-bc9b-4277-b2fe-4cc88dbf4f49/" />
</Frame>

### Filtering

You can use filters to find queries by various criteria:

* duration,
* cache status,
* whether the query was accelerated with pre-aggregations,
* whether the query yielded an error,
* API type.

<Frame>
  <img src="https://ucarecdn.com/951a2a64-bc9b-4277-b2fe-4cc88dbf4f49/" />
</Frame>

## Inspecting API queries

In the table, all queries are shown in their collapsed view by default.
To see an expanded view of a query, click on the **❯** button
to the left of any query.

<Frame>
  <img src="https://ucarecdn.com/fe755749-9eff-4b58-b7b0-c79de2510499/" />
</Frame>

Check the columns to see the details:

* **Query** column shows a representation of a query, similar to the
  REST (JSON) API [query format][ref-query-format]. In case of the SQL API, if the
  query is not coercible to a REST (JSON) API query, raw SQL is shown "as is."
* **API** column shows the API type that was used to run the query:
  REST (JSON) API via HTTP transport, REST (JSON) API via WebSockets, GraphQL API, or SQL API.
* **Duration** column shows how long the query took.
* Bolt icon indicates the [cache type][ref-cache-types] that was used to
  fulfill the query.
* **Time** column shows the point in time the query was run at.

To drill down on a specific query, click it to see more information.

### Query

The **Query** tab shows the raw JSON query sent to the Cube Cloud
deployment.

<Frame>
  <img src="https://ucarecdn.com/3c0490be-757d-46cd-ba2d-d7c93a7acf4e/" />
</Frame>

### Errors

If the query failed, the **Errors** tab will show you the error message
and stacktrace:

<Frame>
  <img src="https://ucarecdn.com/858633a0-4ee3-4dec-adb6-1d91ca30919f/" />
</Frame>

### SQL

The **SQL** tab shows the generated SQL query sent by Cube to either your
data source **or** Cube Store if the query was accelerated with a
pre-aggregation:

<Frame>
  <img src="https://ucarecdn.com/537f7269-654d-479c-a0cc-abc2941f9b5a/" />
</Frame>

You can also run the SQL query directly against your data source using the [SQL
Runner][ref-workspace-sqlrunner] by clicking **▶️**:

<Frame>
  <img src="https://ucarecdn.com/537f7269-654d-479c-a0cc-abc2941f9b5a/" />
</Frame>

### Pre-aggregations

The **Pre-Aggregations** tab shows the
[pre-aggregation][ref-caching-gs-preaggs] used to accelerate this query, if one
was used:

<Frame>
  <img src="https://ucarecdn.com/e0a8d722-d43a-4d6f-8d3c-dbdd3173638e/" />
</Frame>

If no pre-aggregations were used for this query, you should see the following
screen:

<Frame>
  <img src="https://ucarecdn.com/b5cadb89-fbda-404a-806c-da99dc046845/" />
</Frame>

Clicking **Accelerate** allows you to add a pre-aggregation to
accelerate similar queries in the future.

### Security context

The **Security Context** tab shows the [security context][ref-security-context]
that was used to process this query:

<Frame>
  <img src="https://ucarecdn.com/4ea5f5b6-f5a0-4d62-93f9-b9adfe5a2a07/" />
</Frame>

This is helpful in case [multitenancy][ref-multitenancy] is configured.

### Queue graph

The **Queue Graph** tab details any activity in the query queue while
processing the query. This may include other queries that were being processed
or were waiting in the queue by Cube Cloud at the same time as this query:

<Frame>
  <img src="https://ucarecdn.com/dbac27fa-5722-415f-9374-11682b4159d7/" />
</Frame>

A large number of queries in the queue may indicate that your deployment is
under-provisioned, and you may want to consider scaling up your deployment.

### Flame graph

The **Flame Graph** tab shows a [flame graph][datadog-kb-flamegraph] of a
query's execution time across resources in the Cube Cloud deployment. This is
extremely useful for diagnosing where time is being spent in a query, and can
help identify bottlenecks in your Cube deployment or data source.

<Frame>
  <img src="https://ucarecdn.com/56188be4-0614-48e1-97c8-6d8d89639849/" />
</Frame>

## Inspecting database queries

### Query

For Database requests, the **Query** tab shows the SQL query compiled by
Cube that is executed on the data source:

<Frame>
  <img src="https://ucarecdn.com/5a5779f6-b484-49bc-9269-6e145b89f5eb/" />
</Frame>

This can be useful for debugging queries that are failing or taking a long time,
as you can copy the query and run it directly against your data source.

### Errors

If the query failed, the **Errors** tab will show you the error message
and stacktrace:

<Frame>
  <img src="https://ucarecdn.com/efd45e3a-8b44-4ee9-9f9e-284f0fd8eb96/" />
</Frame>

Errors here generally indicate a problem with querying the data source. The
generated SQL query can be copied from the **[Query](#query-1)** tab and
run directly against your data source to debug the issue.

### Events

The **Events** tab shows all data source-related events that occurred
while the query is in the query execution queue:

<Frame>
  <img src="https://ucarecdn.com/24eb11a1-4312-4d06-ac1b-6a0575c7dbe6/" />
</Frame>

[datadog-kb-flamegraph]: https://www.datadoghq.com/knowledge-center/distributed-tracing/flame-graph/

[ref-caching-gs-preaggs]: /docs/pre-aggregations/getting-started-pre-aggregations

[ref-conf-db]: /admin/connect-to-data/data-sources

[ref-workspace-sqlrunner]: /docs/data-modeling/sql-runner

[ref-query-format]: /reference/rest-api/query-format

[ref-cache-types]: /docs/pre-aggregations#cache-type

[ref-security-context]: /docs/data-modeling/access-control/context

[ref-multitenancy]: /embedding/multitenancy

[ref-apis]: /reference

[ref-query-history-export]: /admin/deployment/monitoring-integrations#query-history-export