Skip to content

Commit 43a1cb1

Browse files
authored
docs(api): add pagination instructions to REST API reference (cube-js#5300)
1 parent ac6b59c commit 43a1cb1

File tree

1 file changed

+37
-8
lines changed

1 file changed

+37
-8
lines changed

docs/content/API-Reference/REST-API.mdx

Lines changed: 37 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -40,18 +40,23 @@ curl -H "Authorization: EXAMPLE-API-TOKEN" https://example.com/cubejs-api/v1/sql
4040
### <--{"id" : "Prerequisites"}--> Continue wait
4141

4242
If the request takes too long to be processed, Cube.js Backend responds with
43-
`{ "error": "Continue wait" }` and 200 status code.
44-
This is how the long polling mechanism in Cube is implemented.
45-
Clients should continuously retry the same query in a loop until they get a successful result.
46-
Subsequent calls to the Cube endpoints are idempotent and don't lead to scheduling new database queries if not required by `refreshKey`.
47-
Also, receiving `Continue wait` doesn't mean the database query has been canceled, and it's actually still being processed by the Cube.
48-
Database queries that weren't started and are no longer waited by the client's long polling loop will be marked as orphaned and removed from the querying queue.
43+
`{ "error": "Continue wait" }` and 200 status code. This is how the long polling
44+
mechanism in Cube is implemented. Clients should continuously retry the same
45+
query in a loop until they get a successful result. Subsequent calls to the Cube
46+
endpoints are idempotent and don't lead to scheduling new database queries if
47+
not required by `refreshKey`. Also, receiving `Continue wait` doesn't mean the
48+
database query has been canceled, and it's actually still being processed by the
49+
Cube. Database queries that weren't started and are no longer waited by the
50+
client's long polling loop will be marked as orphaned and removed from the
51+
querying queue.
4952

5053
Possible reasons of **Continue wait**:
5154

5255
- The query requested is heavy, and it takes some time for the database to
53-
process it. Clients should wait for its completion, continuously sending the same REST API request.
54-
[continueWaitTimeout](config#queue-options) can be adjusted in order to change the time Cube waits before returning `Continue wait` message.
56+
process it. Clients should wait for its completion, continuously sending the
57+
same REST API request. [continueWaitTimeout](config#queue-options) can be
58+
adjusted in order to change the time Cube waits before returning
59+
`Continue wait` message.
5560
- There are many queries requested and Cube.js backend queues them to save
5661
database from overloading.
5762

@@ -76,6 +81,30 @@ should be unique for each separate request. `spanId` should define user
7681
interaction span such us `Continue wait` retry cycle and it's value shouldn't
7782
change during one single interaction.
7883

84+
### <--{"id" : "Prerequisites"}--> Pagination
85+
86+
Cube supports paginated requests for the `/v1/load` endpoint by including
87+
[`limit` and `offset` parameters][ref-api-ref-query-format] in the query. For
88+
example, the following query will retrieve rows 101-200 from the `Orders` cube:
89+
90+
```json
91+
{
92+
"dimensions": ["Orders.status"],
93+
"measures": ["Orders.count"],
94+
"timeDimensions": [
95+
{
96+
"dimension": "Orders.createdAt",
97+
"dateRange": "last year",
98+
"granularity": "day"
99+
}
100+
],
101+
"limit": 100,
102+
"offset": 100
103+
}
104+
```
105+
106+
[ref-api-ref-query-format]: /query-format#query-properties
107+
79108
## API Reference
80109

81110
### <--{"id" : "API Reference"}--> /v1/load

0 commit comments

Comments
 (0)