Docs

Author: igorlukanin

docs/pages/product/apis-integrations/rest-api.mdx

@@ -161,7 +161,7 @@ accessible for everyone.
 | API scope | REST API endpoints | Accessible by default? |
 | --- | --- | --- |
 | `meta`    | [`/v1/meta`][ref-ref-meta] | ✅ Yes |
-| `data`    | [`/v1/load`][ref-ref-load] | ✅ Yes |
+| `data`    | [`/v1/load`][ref-ref-load], [`/v1/cubesql`][ref-ref-cubesql] | ✅ Yes |
 | `graphql` | `/graphql` | ✅ Yes |
 | `sql`     | [`/v1/sql`][ref-ref-sql] | ✅ Yes |
 | `jobs`    | [`/v1/pre-aggregations/jobs`][ref-ref-paj] | ❌ No |
@@ -248,9 +248,20 @@ should be unique for each separate request. `spanId` should define user
 interaction span such us `Continue wait` retry cycle and it's value shouldn't
 change during one single interaction.
 
-## Troubleshooting
+## Cache control
 
-### `Continue wait`
+[`/v1/load`][ref-ref-load] and [`/v1/cubesql`][ref-ref-cubesql] endpoints of the REST API
+allow to control the cache behavior. The following querying strategies with regards to
+the cache are supported:
+
+| Strategy | Description |
+| --- | --- |
+| `stale-if-slow`         | If [refresh keys][ref-refresh-keys] are up-to-date, returns cached value. If expired, tries to return fresh value from the data source. If the data source query is slow (hits [`Continue wait`](#continue-wait)), returns stale value from cache. |
+| `stale-while-revalidate`| If [refresh keys][ref-refresh-keys] are up-to-date, returns cached value. If expired, returns stale data from cache and updates cache in background. |
+| `must-revalidate`       | If [refresh keys][ref-refresh-keys] are up-to-date, returns cached value. If expired, always waits for fresh value from the data source, even if slow (hits one or more [`Continue wait`](#continue-wait) intervals). |
+| `no-cache`              | Skips [refresh key][ref-refresh-keys] checks. Always returns fresh data from the data source, regardless of cache or query performance. |
+
+## `Continue wait`
 
 If the request takes too long to be processed, the REST API responds with
 `{ "error": "Continue wait" }` and the status code 200.
@@ -295,6 +306,7 @@ warehouse][ref-data-warehouses].
 [ref-ref-load]: /product/apis-integrations/rest-api/reference#base_pathv1load
 [ref-ref-meta]: /product/apis-integrations/rest-api/reference#base_pathv1meta
 [ref-ref-sql]: /product/apis-integrations/rest-api/reference#base_pathv1sql
+[ref-ref-cubesql]: /product/apis-integrations/rest-api/reference#base_pathv1cubesql
 [ref-ref-paj]: /product/apis-integrations/rest-api/reference#base_pathv1pre-aggregationsjobs
 [ref-security-context]: /product/auth/context
 [ref-graphql-api]: /product/apis-integrations/graphql-api
@@ -313,4 +325,5 @@ warehouse][ref-data-warehouses].
 [ref-traditional-databases]: /product/configuration/data-sources#transactional-databases
 [ref-pre-aggregations]: /product/caching/using-pre-aggregations
 [ref-javascript-sdk]: /product/apis-integrations/javascript-sdk
-[ref-recipe-real-time-data-fetch]: /product/apis-integrations/recipes/real-time-data-fetch
+[ref-recipe-real-time-data-fetch]: /product/apis-integrations/recipes/real-time-data-fetch
+[ref-refresh-keys]: /product/data-modeling/reference/cube#refresh_key

docs/pages/product/apis-integrations/rest-api/query-format.mdx

@@ -41,17 +41,6 @@ The default value is `false`.
 - `timezone`: A [time zone][ref-time-zone] for your query. You can set the
 desired time zone in the [TZ Database Name](https://en.wikipedia.org/wiki/Tz_database)
 format, e.g., `America/Los_Angeles`.
-- `renewQuery`: If `renewQuery` is set to `true`, Cube will renew all
-  [`refreshKey`][ref-schema-ref-preaggs-refreshkey] for queries and query
-  results in the foreground. However, if the
-  [`refreshKey`][ref-schema-ref-preaggs-refreshkey] (or
-  [`refreshKey.every`][ref-schema-ref-preaggs-refreshkey-every]) doesn't
-  indicate that there's a need for an update this setting has no effect. The
-  default value is `false`.
-  > **NOTE**: Cube provides only eventual consistency guarantee. Using a small
-  > [`refreshKey.every`][ref-schema-ref-preaggs-refreshkey-every] value together
-  > with `renewQuery` to achieve immediate consistency can lead to endless
-  > refresh loops and overall system instability.
 - `ungrouped`: If set to `true`, Cube will run an [ungrouped
 query][ref-ungrouped-query].
 - `joinHints`: Query-time [join hints][ref-join-hints], provided as an array of

docs/pages/product/apis-integrations/rest-api/reference.mdx

@@ -13,10 +13,11 @@ By default, it's `/cubejs-api`.
 
 Run the query to the REST API and get the results. 
 
-| Parameter   | Description                                                                                                           |
-| ----------- | --------------------------------------------------------------------------------------------------------------------- |
-| `query`     | Either a single URL encoded Cube [Query](/product/apis-integrations/rest-api/query-format), or an array of queries    |
-| `queryType` | If multiple queries are passed in `query` for [data blending][ref-recipes-data-blending], this must be set to `multi` |
+| Parameter   | Description                                                                                                           | Required |
+| ----------- | --------------------------------------------------------------------------------------------------------------------- | --- |
+| `query`     | Either a single URL encoded Cube [Query](/product/apis-integrations/rest-api/query-format), or an array of queries    | ✅ Yes |
+| `queryType` | If multiple queries are passed in `query` for [data blending][ref-recipes-data-blending], this must be set to `multi` | ❌ No |
+| `cache`     | See [cache control][ref-cache-control]. `stale-if-slow` by default | ❌ No |
 
 Response
 
@@ -319,9 +320,10 @@ This endpoint is part of the [SQL API][ref-sql-api].
 
 </InfoBox>
 
-| Parameter | Description |
-| --- | --- |
-| `query` | The SQL query to run. |
+| Parameter | Description | Required |
+| --- | --- | --- |
+| `query` | The SQL query to run. | ✅ Yes |
+| `cache` | See [cache control][ref-cache-control]. `stale-if-slow` by default | ❌ No |
 
 Response: a stream of newline-delimited JSON objects. The first object contains
 the `schema` property with column names and types. The following objects contain
@@ -639,4 +641,5 @@ Keep-Alive: timeout=5
 [ref-query-wpd]: /product/apis-integrations/queries#query-with-pushdown
 [ref-sql-api]: /product/apis-integrations/sql-api
 [ref-orchestration-api]: /product/apis-integrations/orchestration-api
-[ref-folders]: /product/data-modeling/reference/view#folders
+[ref-folders]: /product/data-modeling/reference/view#folders
+[ref-cache-control]: /product/apis-integrations/rest-api#cache-control