docs: Examples for the /v1/sql endpoint (#9367)

Author: igorlukanin

docs/pages/guides/recipes/access-control/controlling-access-to-cubes-and-views.mdx

@@ -109,7 +109,7 @@ view(`total_revenue_per_customer`, {
 After generating a JWT with a `department` claim set to `finance`, we can send
 it as part of a cURL command:
 
-```bash{outputLines: 2-3}
+```bash
 curl \
   -H "Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkZXBhcnRtZW50IjoiZmluYW5jZSIsImV4cCI6MTY2NzMzNzI1MH0.njfL7GMDNlzKaJDZA0OQ_b2u2JhuSm-WjnS0yVfB8NA" \
   http://localhost:4000/cubejs-api/v1/meta

docs/pages/guides/recipes/access-control/enforcing-mandatory-filters.mdx

@@ -40,7 +40,7 @@ module.exports = {
 
 To get the orders we will send two queries with filters by status:
 
-```bash{outputLines: 1,3-13}
+```bash
 # Completed orders
 curl cube:4000/cubejs-api/v1/load \
   -H "Authorization: eeyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoib3BlcmF0b3IiLCJpYXQiOjE2Mjg3NDUwNDUsImV4cCI6MTgwMTU0NTA0NX0.VErb2t7Bc43ryRwaOiEgXuU5KiolCT-69eI_i2pRq4o" \
@@ -56,7 +56,7 @@ curl cube:4000/cubejs-api/v1/load \
   }'
 ```
 
-```bash{outputLines: 1,3-13}
+```bash
 # Shipped orders
 curl cube:4000/cubejs-api/v1/load \
   -H "Authorization: eeyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoib3BlcmF0b3IiLCJpYXQiOjE2Mjg3NDUwNDUsImV4cCI6MTgwMTU0NTA0NX0.VErb2t7Bc43ryRwaOiEgXuU5KiolCT-69eI_i2pRq4o" \

docs/pages/guides/recipes/analytics/active-users.mdx

@@ -123,7 +123,7 @@ cube(`active_users`, {
 
 We should set a `timeDimensions` with the `dateRange`.
 
-```bash{outputLines: 2-18}
+```bash
 curl cube:4000/cubejs-api/v1/load \
   'query={
     "measures": [

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

@@ -33,7 +33,7 @@ Response
 
 Example request:
 
-```bash{outputLines: 1,3-9,11-15}
+```bash
 curl \
  -X POST  \
  -H "Content-Type: application/json" \
@@ -67,7 +67,7 @@ Example response:
 
 #### With `runQuery`
 
-```bash{outputLines: 1,3-9,11-15}
+```bash
 curl \
  -X POST  \
  -H "Content-Type: application/json" \

docs/pages/product/apis-integrations/javascript-sdk.mdx

@@ -84,7 +84,7 @@ that you can always use a different charting library that suits your needs:
 
 You can install Cube JavaScript Client with npm or Yarn:
 
-```bash{outputLines: 1,3-4}
+```bash
 # npm
 npm install --save @cubejs-client/core
 

docs/pages/product/apis-integrations/javascript-sdk/angular.mdx

@@ -93,7 +93,7 @@ can always use a different charting library that suits your needs:
 
 You can install Cube JavaScript Client and the Angular package with npm or Yarn:
 
-```bash{outputLines: 1,3-4}
+```bash
 # npm
 npm install --save @cubejs-client/core @cubejs-client/ngx
 

docs/pages/product/apis-integrations/javascript-sdk/react.mdx

@@ -102,7 +102,7 @@ always use a different charting library that suits your needs:
 
 You can install Cube JavaScript Client and the React package with npm or Yarn:
 
-```bash{outputLines: 1,3-4}
+```bash
 # npm
 npm install --save @cubejs-client/core @cubejs-client/react
 

docs/pages/product/apis-integrations/javascript-sdk/reference/cubejs-client-ngx.mdx

@@ -7,7 +7,7 @@ Angular app.
 
 First, install `@cubejs-client/ngx` using npm or yarn:
 
-```bash{outputLines: 2}
+```bash
 npm install --save @cubejs-client/ngx
 # or
 yarn add @cubejs-client/ngx

docs/pages/product/apis-integrations/javascript-sdk/vue.mdx

@@ -98,7 +98,7 @@ always use a different charting library that suits your needs:
 
 You can install Cube JavaScript Client and the Vue package with npm or Yarn:
 
-```bash{outputLines: 1,3-4}
+```bash
 # npm
 npm install --save @cubejs-client/core @cubejs-client/vue3
 

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

@@ -38,7 +38,7 @@ Response
 
 Example request:
 
-```bash{outputLines: 1,3-9,11-15}
+```bash
 # Request with http method GET
 curl \
   -H "Authorization: EXAMPLE-API-TOKEN" \
@@ -143,14 +143,14 @@ the query can't be run without post-processing.
 
 ### Example
 
-Request:
+Request with a query in the REST API format:
 
-```bash{outputLines: 2-6}
+```bash
 curl \
-  -H "Authorization: EXAMPLE-API-TOKEN" \
+  -H "Authorization: TOKEN" \
   -G \
-  --data-urlencode 'query={"measures":["users.count"],
-  "timeDimensions":[{"dimension": "users.createdAt","granularity":"day","dateRange":["2019-03-01","2019-03-31"]}]}' \
+  --data-urlencode 'query={"measures":["orders.count"]}' \
+  --data-urlencode 'format=rest'  \
   http://localhost:4000/cubejs-api/v1/sql
 ```
 
@@ -160,34 +160,89 @@ Response:
 {
   "sql": {
     "sql": [
-      "SELECT\n      date_trunc('day', (users.created_at::timestamptz AT TIME ZONE 'UTC')) \"users.created_at_date\", count(users.id) \"users.count\"\n    FROM\n      public.users AS users\n  WHERE (users.created_at >= $1::timestamptz AND users.created_at <= $2::timestamptz) GROUP BY 1 ORDER BY 1 ASC LIMIT 10000",
-      ["2019-03-01T00:00:00Z", "2019-03-31T23:59:59Z"]
-    ],
-    "timeDimensionAlias": "users.created_at_date",
-    "timeDimensionField": "users.createdAt",
-    "order": [
-      {
-        "id": "users.createdAt",
-        "desc": false
-      }
+      "SELECT sum(`base_orders__count`) `orders__count` FROM prod_pre_aggregations.base_orders_orders_by_month AS `base_orders__orders_by_month`  LIMIT 10000",
+      []
+    ]
+  }
+}
+```
+
+Request with a query in the SQL API format:
+
+```bash
+curl \
+  -H "Authorization: TOKEN" \
+  -G \
+  --data-urlencode 'query=SELECT COUNT(*) FROM orders' \
+  --data-urlencode 'format=sql'  \  
+  http://localhost:4000/cubejs-api/v1/sql
+```
+
+Response:
+
+```json
+{
+  "sql": {
+    "status": "ok",
+    "sql": [
+      "SELECT\n      count(\"base_orders\".id) \"count_uint8_1__\"\n    FROM\n      (SELECT * FROM 's3://cube-tutorial/orders.csv') AS \"base_orders\"  LIMIT 50000",
+      []
     ],
-    "cacheKeyQueries": {
-      "queries": [
-        ["select max(users.created_at) from public.users AS users", []]
-      ],
-      "renewalThreshold": 21600
-    },
-    "preAggregations": []
+    "query_type": "regular"
   }
 }
 ```
 
-<InfoBox>
+Request with a query in the SQL API format that is executed with post-processing:
 
-Note that a generated query can contain placeholders, e.g., `?` or `$1`, for parameters
-that Cube passes to an underlying data source driver later when executing the query.
+```bash
+curl \
+  -H "Authorization: TOKEN" \
+  -G \
+  --data-urlencode 'query=SELECT AVG(count) FROM (SELECT COUNT(*) AS count FROM orders) AS table' \
+  --data-urlencode 'format=sql'  \ 
+  http://localhost:4000/cubejs-api/v1/sql
+```
 
-</InfoBox>
+Response:
+
+```json
+{
+  "sql": {
+    "status": "error",
+    "error": "Provided query can not be executed without post-processing.",
+    "query_type": "post_processing"
+  }
+}
+```
+
+Request with a query in the SQL API format that is forced to be executed without
+post-processing, i.e., as a query with pushdown:
+
+```bash
+curl \
+  -H "Authorization: TOKEN" \
+  -G \
+  --data-urlencode 'query=SELECT AVG(count) FROM (SELECT COUNT(*) AS count FROM orders) AS table' \
+  --data-urlencode 'format=sql' \
+  --data-urlencode 'disable_post_processing=true'  \
+  http://localhost:4000/cubejs-api/v1/sql
+```
+
+Response:
+
+```json
+{
+  "sql": {
+    "status": "ok",
+    "sql": [
+      "SELECT \"table\".\"avg_table_count_\" \"avg_table_count_\" \nFROM (\n  SELECT AVG(\"table\".\"count\") \"avg_table_count_\" \n  FROM (\n    SELECT\n          count(\"base_orders\".id) \"count\"\n        FROM\n          (SELECT * FROM 's3://cube-tutorial/orders.csv') AS \"base_orders\" \n  ) AS \"table\"\n) AS \"table\"\nLIMIT 50000",
+      []
+    ],
+    "query_type": "pushdown"
+  }
+}
+```
 
 ## `{base_path}/v1/meta`
 
@@ -210,7 +265,7 @@ Response
 
 Example request:
 
-```bash{outputLines: 2-4}
+```bash
 curl \
   -H "Authorization: EXAMPLE-API-TOKEN" \
   -G \
@@ -282,7 +337,7 @@ contain an array of `tokens` (identifiers) of triggered jobs.
 Example request triggering builds of all pre-aggregations defined in all cubes
 using an empty security context and a `UTC` timezone:
 
-```bash{outputLines: 2-12}
+```bash
 curl \
   -d '{
     "action": "post",
@@ -300,7 +355,7 @@ curl \
 Example request triggering builds of all pre-aggregations defined in the
 `orders` cube using an empty security context and a `UTC` timezone:
 
-```bash{outputLines: 2-13}
+```bash
 curl \
   -d '{
     "action": "post",
@@ -319,7 +374,7 @@ curl \
 Example request triggering builds of the `main` pre-aggregation defined in the
 `orders` cube using an empty security context and a `UTC` timezone:
 
-```bash{outputLines: 2-13}
+```bash
 curl \
   -d '{
     "action": "post",
@@ -339,7 +394,7 @@ Example request triggering builds of the `main` pre-aggregation defined in the
 `orders` cube within date range with some security context data
 and an `America/Los_Angeles` timezone:
 
-```bash{outputLines: 2-13}
+```bash
 curl \
   -d '{
     "action": "post",
@@ -389,7 +444,7 @@ In the `status` property of the payload, you can get the following statuses:
 
 Example request:
 
-```bash{outputLines: 2-14}
+```bash
 curl \
   -d '{
     "action": "get",
@@ -442,7 +497,7 @@ the connection to the _default_ [data source][ref-datasources].
 
 Example of a successful request:
 
-```bash{outputLines: 2-12}
+```bash
 curl -i http://localhost:4000/readyz
 HTTP/1.1 200 OK
 X-Powered-By: Express
@@ -459,7 +514,7 @@ Keep-Alive: timeout=5
 
 Example of a failed response:
 
-```bash{outputLines: 2-12}
+```bash
 curl -i http://localhost:4000/readyz
 HTTP/1.1 500 Internal Server Error
 X-Powered-By: Express
@@ -481,7 +536,7 @@ existing connections to data sources.
 
 Example of a successful response:
 
-```bash{outputLines: 2-12}
+```bash
 curl -i http://localhost:4000/livez
 HTTP/1.1 200 OK
 X-Powered-By: Express
@@ -498,7 +553,7 @@ Keep-Alive: timeout=5
 
 Example of a failed response:
 
-```bash{outputLines: 2-12}
+```bash
 curl -i http://localhost:4000/livez
 HTTP/1.1 500 Internal Server Error
 X-Powered-By: Express