REST API
REST API is used to communicate with Cube backend. All requests are prefixed
with basePath described in
Backend Server Core. By default, it is set to
/cubejs-api
.
Cube uses API tokens to authorize requests and also for passing additional
security context, which can be used in the
queryRewrite
property in your cube.js
configuration file.
The API Token is passed via the Authorization Header. The token itself is a JSON Web Token, the Security section describes how to generate it.
In the development environment the token is not required for authorization, but you can still use it to pass a security context.
curl -H "Authorization: EXAMPLE-API-TOKEN" https://example.com/cubejs-api/v1/sql
If the request takes too long to be processed, Cube Backend responds with
{ "error": "Continue wait" }
and 200 status code. This is how the long polling
mechanism in Cube is implemented. Clients should continuously retry the same
query in a loop until they get a successful result. Subsequent calls to the Cube
endpoints are idempotent and don't lead to scheduling new database queries if
not required by refreshKey
. Also, receiving Continue wait
doesn't mean the
database query has been canceled, and it's actually still being processed by the
Cube. 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.
Possible reasons of Continue wait:
- The query requested is heavy, and it takes some time for the database to
process it. Clients should wait for its completion, continuously sending the
same REST API request. continueWaitTimeout can be
adjusted in order to change the time Cube waits before returning
Continue wait
message. - There are many queries requested and Cube backend queues them to save database from overloading.
Cube REST API has basic errors and HTTP Error codes for all requests.
Status | Error response | Description |
---|---|---|
400 | Error message | General error. It may be a database error, timeout, or other issue. Check error message for details. |
403 | Authorization header isn't set | You didn't provide an auth token. Provide a valid API Token or disable authorization. |
403 | Invalid token | The auth token provided is not valid. It may be expired or have invalid signature. |
500 | Error message | Cube internal server error. Check error message for details. |
For monitoring tools such as Cube Cloud proper request span annotation should be
provided in x-request-id
header of a request. Each request id should consist
of two parts: spanId
and requestSequenceId
which define x-request-id
as
whole: ${spanId}-span-${requestSequenceId}
. Values of x-request-id
header
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.
Cube supports paginated requests for the /v1/load
endpoint by including
limit
and offset
parameters in the query. For
example, the following query will retrieve rows 101-200 from the Orders
cube:
{
"dimensions": ["Orders.status"],
"measures": ["Orders.count"],
"timeDimensions": [
{
"dimension": "Orders.createdAt",
"dateRange": "last year",
"granularity": "day"
}
],
"limit": 100,
"offset": 100
}
Get the data for a query.
Parameter | Description |
---|---|
query | Either a single URL encoded Cube Query, or an array of queries |
queryType | If multiple queries are passed in query for data blending, this must be set to multi |
Response
query
- The query passed via params. It can be an array of queries and in such case it will be treated as a Data Blending query.data
- Formatted dataset of query results.annotation
- Metadata for query. Contains descriptions for all query items.title
- Human readable title from data schema.shortTitle
- Short title for visualization usage (ex. chart overlay)type
- Data type
Example request:
# Request with http method GET
curl \
-H "Authorization: EXAMPLE-API-TOKEN" \
-G \
--data-urlencode 'query={"measures":["Users.count"]}' \
http://localhost:4000/cubejs-api/v1/load
# Request with http method POST
# Use POST to fix problem with query length limits
curl \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: EXAMPLE-API-TOKEN" \
--data '{"query": {"measures":["Users.count"]}}' \
http://localhost:4000/cubejs-api/v1/load
Example response:
{
query:{
measures:[
"Users.count"
],
filters:[],
timezone:"UTC",
dimensions:[],
timeDimensions:[]
},
data:[
{
"Users.count":"700"
}
],
annotation:{
measures:{
"Users.count":{
title:"Users Count",
shortTitle:"Count",
type:"number"
}
},
dimensions:{},
segments:{},
timeDimensions:{}
}
}
Currently all fetched numericals are returned in the same format as driver returns it without any additional processing. Most of drivers return numerical values as strings instead of javascript integer or float to ensure there's no loss of significance. Client code should take care of parsing such numerical values.
Get the SQL Code generated by Cube to be executed in the database.
Parameter | Description |
---|---|
query | URLencoded Cube Query |
Response
sql
- JSON Object with the following propertiessql
- Formatted SQL query with parametersorder
- Order fields and direction used in SQL querycacheKeyQueries
- Key names and TTL of Cube data cachepreAggregations
- SQL queries used to build pre-aggregation tables
Example request:
curl \
-H "Authorization: EXAMPLE-API-TOKEN" \
-G \
--data-urlencode 'query={"measures":["Users.count"],
"timeDimensions":[{"dimension": "Users.createdAt","granularity":"day","dateRange":["2019-03-01","2019-03-31"]}]}' \
http://localhost:4000/cubejs-api/v1/sql
Example 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
}
],
cacheKeyQueries:{
queries:[
[
"select max(users.created_at) from public.users AS users",
[]
]
],
renewalThreshold:21600
},
preAggregations:[]
}
}
Get meta-information for cubes defined in data schema
Response
cubes
- Array of cubesname
- Codename of the cubetitle
- Human-readable cube namemeasures
- Array of measures defined within this cubedimensions
- Array of dimensions defined within this cubesegments
- Array of segments defined within this cubeconnectedComponent
- if it has the same value for two cubes, then there is at least one join path between them.
Example request:
curl \
-H "Authorization: EXAMPLE-API-TOKEN" \
-G \
http://localhost:4000/cubejs-api/v1/meta
Example response:
{
cubes: [
{
name: 'Users',
title: 'Users',
connectedComponent: 1,
measures: [
{
name: 'Users.count',
title: 'Users Count',
shortTitle: 'Count',
aliasName: 'users.count',
type: 'number',
aggType: 'count',
drillMembers: ['Users.id', 'Users.city', 'Users.createdAt'],
},
],
dimensions: [
{
name: 'Users.city',
title: 'Users City',
type: 'string',
aliasName: 'users.city',
shortTitle: 'City',
suggestFilterValues: true,
},
],
segments: [],
},
];
}
Trigger a scheduled refresh run to refresh pre-aggregations.
Single call to this API may be not enough to refresh everything is pending. This call just populates queue with refresh workload and should be continuously called until refresh jobs have completed; otherwise refresh jobs will be marked as orphaned, and they will be removed from the queue.
Learn more about scheduled refresh here.
Parameter | Description |
---|---|
queryingOptions | Optional URL encoded Cube Query options such as timezone |
Empty object response if scheduled successfully.
Example request:
curl \
-H "Authorization: EXAMPLE-API-TOKEN" \
-G \
--data-urlencode 'queryingOptions={"timezone":"UTC"}' \
http://localhost:4000/cubejs-api/v1/run-scheduled-refresh
Submit pre-aggregation build jobs and retrieve their refresh status.
Submitting a job
Parameter | Description | Required |
---|---|---|
action | Submitting a job requires using the post action | ✅ |
selector.contexts | An array of contexts to use | ✅ |
selector.timezones | An array of timezones to use | ❌ |
selector.datasources | An array of data source names of the pre-aggregation to build | ❌ |
selector.cubes | An array of cube names which contain the pre-aggregations to build | ❌ |
selector.preAggregations | An array of pre-aggregation names to build | ❌ |
To submit a job, send a POST
request with a payload including the action
and
selector
properties. The response will include the jobId
of the submitted
job.
Example request:
curl \
-d '{"action": "post", "selector": { "preAggregations": ["Orders.ordersByStatus"]}}' \
-H "Authorization: EXAMPLE-API-TOKEN" \
-X POST \
https://localhost:4000/cubejs-system/v1/pre-aggregations/jobs
Example response:
[
"e9a6a0c55885cea5371348500ce7d7dc",
"d1329b6c8d152e734fc4dcf7307b1b58",
"6f4ea38373663fffc4334a576574845b",
"ea903b10634b2f3141b35a2529870e89"
]
Retrieving statuses for a job
Parameter | Description | Required |
---|---|---|
action | Retrieving a job requires using the get action | ✅ |
resType | If object is specified, the response is returned as an JSON object instead of an array | ❌ |
tokens | An array of strings representing pre-aggregation build jobs | ✅ |
To retrieve the status of a previously submitted job, send a POST
request with
a tokens
property.
Example request:
curl \
-d '{"action": "get", "tokens": ["e9a6a0c55885cea5371348500ce7d7dc","d1329b6c8d152e734fc4dcf7307b1b58","6f4ea38373663fffc4334a576574845b","ea903b10634b2f3141b35a2529870e89"]}' \
-H "Authorization: EXAMPLE-API-TOKEN" \
-X POST \
https://localhost:4000/cubejs-system/v1/pre-aggregations/jobs
Example response:
[
{
"token": "e9a6a0c55885cea5371348500ce7d7dc",
"table": "prod_pre_aggregations.orders_category_and_date_hod0x3hf_03krd5ns_1hop3hn",
"status": "processing",
"selector": {
"cubes": ["Orders"],
"preAggregations": ["Orders.categoryAndDate"],
"contexts": [
{
"securityContext": {
"tenant": "tenant_1"
}
}
],
"timezones": ["UTC"],
"dataSources": ["default"]
}
},
{
"token": "d1329b6c8d152e734fc4dcf7307b1b58",
"table": "prod_pre_aggregations.orders_category_and_date_mzfp445f_r2h2isa5_1hop3hn",
"status": "processing",
"selector": {
"cubes": ["Orders"],
"preAggregations": ["Orders.categoryAndDate"],
"contexts": [
{
"securityContext": {
"tenant": "tenant_1"
}
}
],
"timezones": ["America/Los_Angeles"],
"dataSources": ["default"]
}
},
{
"token": "6f4ea38373663fffc4334a576574845b",
"table": "prod_pre_aggregations.orders_category_and_date_hod0x3hf_03krd5ns_1hop3hn",
"status": "missing_partition",
"selector": {
"cubes": ["Orders"],
"preAggregations": ["Orders.categoryAndDate"],
"contexts": [
{
"securityContext": {
"tenant": "tenant_2"
}
}
],
"timezones": ["UTC"],
"dataSources": ["default"]
}
},
{
"token": "ea903b10634b2f3141b35a2529870e89",
"table": "prod_pre_aggregations.orders_category_and_date_mzfp445f_r2h2isa5_1hop3hn",
"status": "missing_partition",
"selector": {
"cubes": ["Orders"],
"preAggregations": ["Orders.categoryAndDate"],
"contexts": [
{
"securityContext": {
"tenant": "tenant_2"
}
}
],
"timezones": ["America/Los_Angeles"],
"dataSources": ["default"]
}
}
]
Example request with resType: object
:
curl \
-d '{"action": "get", "resType": "object", "tokens": ["e9a6a0c55885cea5371348500ce7d7dc","d1329b6c8d152e734fc4dcf7307b1b58","6f4ea38373663fffc4334a576574845b","ea903b10634b2f3141b35a2529870e89"]}' \
-H "Authorization: EXAMPLE-API-TOKEN" \
-X POST \
https://localhost:4000/cubejs-system/v1/pre-aggregations/jobs
Example response with resType: object
:
{
"e9a6a0c55885cea5371348500ce7d7dc": {
"table": "prod_pre_aggregations.orders_category_and_date_hod0x3hf_03krd5ns_1hop3hn",
"status": "processing",
"selector": {
"cubes": ["Orders"],
"preAggregations": ["Orders.categoryAndDate"],
"contexts": [
{
"securityContext": {
"tenant": "tenant_1"
}
}
],
"timezones": ["UTC"],
"dataSources": ["default"]
}
},
"d1329b6c8d152e734fc4dcf7307b1b58": {
"table": "prod_pre_aggregations.orders_category_and_date_mzfp445f_r2h2isa5_1hop3hn",
"status": "processing",
"selector": {
"cubes": ["Orders"],
"preAggregations": ["Orders.categoryAndDate"],
"contexts": [
{
"securityContext": {
"tenant": "tenant_1"
}
}
],
"timezones": ["America/Los_Angeles"],
"dataSources": ["default"]
}
},
"6f4ea38373663fffc4334a576574845b": {
"table": "prod_pre_aggregations.orders_category_and_date_hod0x3hf_03krd5ns_1hop3hn",
"status": "missing_partition",
"selector": {
"cubes": ["Orders"],
"preAggregations": ["Orders.categoryAndDate"],
"contexts": [
{
"securityContext": {
"tenant": "tenant_2"
}
}
],
"timezones": ["UTC"],
"dataSources": ["default"]
}
},
"ea903b10634b2f3141b35a2529870e89": {
"table": "prod_pre_aggregations.orders_category_and_date_mzfp445f_r2h2isa5_1hop3hn",
"status": "missing_partition",
"selector": {
"cubes": ["Orders"],
"preAggregations": ["Orders.categoryAndDate"],
"contexts": [
{
"securityContext": {
"tenant": "tenant_2"
}
}
],
"timezones": ["America/Los_Angeles"],
"dataSources": ["default"]
}
}
}
Returns the ready state of the deployment.
Single-tenant: Ensures the orchestration layer is operational and tests the
connection to the default dataSource
.
Multi-tenant: Tests connections per-tenant. If no connections exist, it will report as successful.
Example request:
curl -i http://localhost:4000/readyz
Successful example response:
HTTP/1.1 200 OK
X-Powered-By: Express
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
Content-Length: 19
ETag: W/"13-MyluqxoYxC0tUxBeZCnbaWYVLhg"
Date: Mon, 18 Jan 2021 15:39:57 GMT
Connection: keep-alive
Keep-Alive: timeout=5
{"health":"HEALTH"}
Failure example response:
HTTP/1.1 500 Internal Server Error
X-Powered-By: Express
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
Content-Length: 19
ETag: W/"13-MyluqxoYxC0tUxBeZCnbaWYVLhg"
Date: Mon, 18 Jan 2021 15:39:57 GMT
Connection: keep-alive
Keep-Alive: timeout=5
{"health":"DOWN"}
Returns the liveness state of the deployment. This is confirmed by testing any
existing connections to dataSource
. If no connections exist, it will report as
successful.
curl -i http://localhost:4000/livez
Successful example response:
HTTP/1.1 200 OK
X-Powered-By: Express
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
Content-Length: 19
ETag: W/"13-MyluqxoYxC0tUxBeZCnbaWYVLhg"
Date: Mon, 18 Jan 2021 15:39:57 GMT
Connection: keep-alive
Keep-Alive: timeout=5
{"health":"HEALTH"}
Failure example response:
HTTP/1.1 500 Internal Server Error
X-Powered-By: Express
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
Content-Length: 19
ETag: W/"13-MyluqxoYxC0tUxBeZCnbaWYVLhg"
Date: Mon, 18 Jan 2021 15:39:57 GMT
Connection: keep-alive
Keep-Alive: timeout=5
{"health":"DOWN"}
Did you find this page useful?