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

<InfoBox>

Available on [all plans](https://cube.dev/pricing).
You can also choose a [Query History tier](/product/administration/pricing#query-history-tiers).

</InfoBox>

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:

<Screenshot
  highlight="inset(15% 1% 60% 21% round 10px)"
  src="https://ucarecdn.com/393dfa47-033d-421b-87ce-fcf5617ac1c8/"
/>

To go back to live mode, click <Btn>▶</Btn>:

<Screenshot
  highlight="inset(15% 6% 79% 88% round 10px)"
  src="https://ucarecdn.com/393dfa47-033d-421b-87ce-fcf5617ac1c8/"
/>

## 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 <Btn>API</Btn> and <Btn>Database</Btn> tabs.

<Screenshot
  highlight="inset(22% 79% 70% 7% round 10px)"
  src="https://ucarecdn.com/951a2a64-bc9b-4277-b2fe-4cc88dbf4f49/"
/>

### All queries and top queries

Clicking <Btn>All Queries</Btn> will show all queries in order of recency,
while <Btn>Top Queries</Btn> 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. 

<Screenshot
  highlight="inset(30% 65% 64% 7% round 10px)"
  src="https://ucarecdn.com/951a2a64-bc9b-4277-b2fe-4cc88dbf4f49/"
/>

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

<Screenshot
  highlight="inset(36% 22% 58% 7% round 10px)"
  src="https://ucarecdn.com/951a2a64-bc9b-4277-b2fe-4cc88dbf4f49/"
/>

## 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&nbsp;<Btn>❯</Btn> button
to the left of any query.

<Screenshot
  src="https://ucarecdn.com/fe755749-9eff-4b58-b7b0-c79de2510499/"
  highlight="inset(35% 2% 0 17.5%)"
/>

Check the columns to see the details:
- <Btn>Query</Btn> column shows a representation of a query, similar to the
REST API [query format][ref-query-format]. In case of the SQL API, if the
query is not coercible to a REST API query, raw SQL is shown "as is."
- <Btn>API</Btn> column shows the API type that was used to run the query:
REST API via HTTP transport, REST API via WebSockets, GraphQL API, or SQL API.
- <Btn>Duration</Btn> column shows how long the query took.
- Bolt icon indicates the [cache type][ref-cache-types] that was used to
fulfill the query.
- <Btn>Time</Btn> 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 <Btn>Query</Btn> tab shows the raw JSON query sent to the Cube Cloud
deployment.

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

### Errors

If the query failed, the <Btn>Errors</Btn> tab will show you the error message
and stacktrace:

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

### SQL

The <Btn>SQL</Btn> 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:

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

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

<Screenshot
  highlight="inset(51.5% 2.5% 44% 94% round 10px)"
  src="https://ucarecdn.com/537f7269-654d-479c-a0cc-abc2941f9b5a/"
/>

### Pre-aggregations

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

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

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

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

Clicking <Btn>Accelerate</Btn> allows you to add a pre-aggregation to
accelerate similar queries in the future.

### Security context

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

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

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

### Queue graph

The <Btn>Queue Graph</Btn> 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:

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

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 <Btn>Flame Graph</Btn> 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.

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

## Inspecting database queries

### Query

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

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

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 <Btn>Errors</Btn> tab will show you the error message
and stacktrace:

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

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

### Events

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

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

[datadog-kb-flamegraph]:
  https://www.datadoghq.com/knowledge-center/distributed-tracing/flame-graph/
[ref-caching-gs-preaggs]: /product/caching/getting-started-pre-aggregations
[ref-conf-db]: /product/configuration/data-sources
[ref-workspace-sqlrunner]: /product/data-modeling/sql-runner
[ref-query-format]: /product/apis-integrations/rest-api/query-format
[ref-cache-types]: /product/caching#cache-type
[ref-security-context]: /product/auth/context
[ref-multitenancy]: /product/configuration/multitenancy
[ref-apis]: /product/apis-integrations
[ref-query-history-export]: /product/administration/deployment/monitoring#query-history-export