Skip to content

Commit ebca109

Browse files
igorlukaninmcheshkov
igorlukanin
authored and
mcheshkov
committed
Add docs
1 parent 5da39ad commit ebca109

File tree

3 files changed

+74
-27
lines changed

3 files changed

+74
-27
lines changed

‎docs/pages/product/apis-integrations/queries.mdx

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -142,7 +142,7 @@ The same query using the REST API syntax looks as follows:
142142
### Query with post-processing
143143

144144
**Queries with post-processing are specific to the [SQL API][ref-sql-api].**
145-
They are structured in such a way that a [regular query](#regular-query) is
145+
Generally, they are structured in such a way that a [regular query](#regular-query) is
146146
part of a `FROM` clause or a common table expression (CTE):
147147

148148
```sql
@@ -178,8 +178,17 @@ limited set of SQL functions and operators.
178178

179179
#### Example
180180

181-
See an example of a query with post-processing. In this query, we derive new
182-
dimensions, post-aggregate measures, and perform additional filtering:
181+
The simplest example of a query with post-processing:
182+
183+
```sql
184+
SELECT VERSION();
185+
```
186+
187+
This query invokes a function that is implemented by the SQL API and executed without
188+
querying the upstream data source.
189+
190+
Now, see a more complex example of a query with post-processing. In this query, we derive
191+
new dimensions, post-aggregate measures, and perform additional filtering:
183192

184193
```sql
185194
SELECT

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

Lines changed: 5 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -130,13 +130,7 @@ accessible for everyone.
130130
| `data` | [`/v1/load`][ref-ref-load], [`/v1/sql`][ref-ref-sql] | ✅ Yes |
131131
| `graphql` | `/graphql` | ✅ Yes |
132132
| `jobs` | [`/v1/pre-aggregations/jobs`][ref-ref-paj] | ❌ No |
133-
134-
<InfoBox>
135-
136-
Exception: `/livez` and `/readyz` endpoints don't belong to any scope. Access to
137-
these endpoints can't be controlled using API scopes.
138-
139-
</InfoBox>
133+
| No scope | `/livez`, `/readyz` | ✅ Yes, always |
140134

141135
You can set accessible API scopes _for all requests_ using the
142136
`CUBEJS_DEFAULT_API_SCOPES` environment variable. For example, to disallow
@@ -282,10 +276,10 @@ example, the following query will retrieve rows 101-200 from the `Orders` cube:
282276
[ref-conf-basepath]: /reference/configuration/config#basepath
283277
[ref-conf-contexttoapiscopes]:
284278
/reference/configuration/config#contexttoapiscopes
285-
[ref-ref-load]: /product/apis-integrations/rest-api/reference#v1load
286-
[ref-ref-meta]: /product/apis-integrations/rest-api/reference#v1meta
287-
[ref-ref-sql]: /product/apis-integrations/rest-api/reference#v1sql
288-
[ref-ref-paj]: /product/apis-integrations/rest-api/reference#v1pre-aggregationsjobs
279+
[ref-ref-load]: /product/apis-integrations/rest-api/reference#base_pathv1load
280+
[ref-ref-meta]: /product/apis-integrations/rest-api/reference#base_pathv1meta
281+
[ref-ref-sql]: /product/apis-integrations/rest-api/reference#base_pathv1sql
282+
[ref-ref-paj]: /product/apis-integrations/rest-api/reference#base_pathv1pre-aggregationsjobs
289283
[ref-security-context]: /product/auth/context
290284
[ref-graphql-api]: /product/apis-integrations/graphql-api
291285
[ref-orchestration-api]: /product/apis-integrations/orchestration-api

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

Lines changed: 57 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -99,21 +99,59 @@ values.
9999

100100
## `{base_path}/v1/sql`
101101

102-
Get the SQL Code generated by Cube to be executed in the database.
102+
Takes an API query and returns the SQL query that can be executed against the data source
103+
that is generated by Cube. This endpoint is useful for debugging, understanding how
104+
Cube translates API queries into SQL queries, and providing transparency to SQL-savvy
105+
end users.
103106

104-
| Parameter | Description |
105-
| --------- | ------------------------------------------------------------------------- |
106-
| query | URLencoded Cube [Query](/product/apis-integrations/rest-api/query-format) |
107+
Using this endpoint to take the SQL query and execute it against the data source directly
108+
is not recommended as it bypasses Cube's caching layer and other optimizations.
107109

108-
Response
110+
Request parameters:
109111

110-
- `sql` - JSON Object with the following properties
111-
- `sql` - Formatted SQL query with parameters
112-
- `order` - Order fields and direction used in SQL query
113-
- `cacheKeyQueries` - Key names and TTL of Cube data cache
114-
- `preAggregations` - SQL queries used to build pre-aggregation tables
112+
| Parameter, type | Description | Required |
113+
| --- | --- | --- |
114+
| `format`, `string` | Query format:<br/>`sql` for [SQL API][ref-sql-api] queries,<br/>`rest` for [REST API][ref-rest-api] queries (default) | ❌ No |
115+
| `query`, `string` | Query as an URL-encoded JSON object or SQL query | ✅ Yes |
116+
| `disable_post_processing`, `boolean` | Flag that affects query planning, `true` or `false` | ❌ No |
115117

116-
Example request:
118+
If `disable_post_processing` is set to `true`, Cube will try to generate the SQL
119+
as if the query is run without [post-processing][ref-query-wpp], i.e., if it's run as a
120+
query with [pushdown][ref-query-wpd].
121+
122+
<WarningBox>
123+
124+
Currently, the `disable_post_processing` parameter is not yet supported.
125+
126+
</WarningBox>
127+
128+
The response will contain a JSON object with the following properties under the `sql` key:
129+
130+
| Property, type | Description |
131+
| --- | --- |
132+
| `status`, `string` | Query planning status, `ok` or `error` |
133+
| `sql`, `array` | Two-element array (see below) |
134+
| `sql[0]`, `string` | Generated query with parameter placeholders |
135+
| `sql[1]`, <nobr>`array` or `object`</nobr> | Generated query parameters |
136+
137+
For queries with the `sql` format, the response will also include the following additional
138+
properties under the `sql` key:
139+
140+
| Property, type | Description |
141+
| --- | --- |
142+
| `data_source`, `string` | [Data source][ref-data-sources] name or `cubestore` |
143+
| `query_plan`, `object` | Query execution plan |
144+
| `query_type`, `string` | `regular` for [regular][ref-regular-queries] queries,<br/>`post_processing` for queries with [post-processing][ref-query-wpp],<br/>`pushdown` for queries with [pushdown][ref-query-wpd] |
145+
146+
For queries with the `sql` format, in case of an error, the response will only contain
147+
`status`, `query_type`, and `error` properties.
148+
149+
For example, an error will be returned if `disable_post_processing` was set to `true` but
150+
the query can't be run without post-processing.
151+
152+
### Example
153+
154+
Request:
117155

118156
```bash{outputLines: 2-6}
119157
curl \
@@ -124,7 +162,7 @@ curl \
124162
http://localhost:4000/cubejs-api/v1/sql
125163
```
126164

127-
Example response:
165+
Response:
128166

129167
```json
130168
{
@@ -464,4 +502,10 @@ Keep-Alive: timeout=5
464502
[ref-recipes-data-blending]: /product/data-modeling/concepts/data-blending#data-blending
465503
[ref-rest-api]: /product/apis-integrations/rest-api
466504
[ref-basepath]: /product/apis-integrations/rest-api#base-path
467-
[ref-datasources]: /product/configuration/advanced/multiple-data-sources
505+
[ref-datasources]: /product/configuration/advanced/multiple-data-sources
506+
[ref-sql-api]: /product/apis-integrations/sql-api
507+
[ref-rest-api]: /product/apis-integrations/rest-api
508+
[ref-data-sources]: /product/configuration/advanced/multiple-data-sources
509+
[ref-regular-queries]: /product/apis-integrations/queries#regular-query
510+
[ref-query-wpp]: /product/apis-integrations/queries#query-with-post-processing
511+
[ref-query-wpd]: /product/apis-integrations/queries#query-with-pushdown

0 commit comments

Comments
 (0)