REST API

`/v1/load`

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 the data model.
- 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.

`/v1/sql`

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 properties
- sql - Formatted SQL query with parameters
- order - Order fields and direction used in SQL query
- cacheKeyQueries - Key names and TTL of Cube data cache
- preAggregations - 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": []
  }
}

`/v1/meta`

Get meta-information for cubes defined in the data model.

Response

cubes - Array of cubes
- name - Codename of the cube
- title - Human-readable cube name
- measures - Array of measures defined within this cube
- dimensions - Array of dimensions defined within this cube
- segments - Array of segments defined within this cube
- connectedComponent - 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": []
    }
  ]
}

`/v1/run-scheduled-refresh`

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

`/cubejs-system/v1/pre-aggregations/jobs`

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.category_and_date"]}}' \
  -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.category_and_date"],
      "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.category_and_date"],
      "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.category_and_date"],
      "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.category_and_date"],
      "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.category_and_date"],
      "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.category_and_date"],
      "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.category_and_date"],
      "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.category_and_date"],
      "contexts": [
        {
          "securityContext": {
            "tenant": "tenant_2"
          }
        }
      ],
      "timezones": ["America/Los_Angeles"],
      "dataSources": ["default"]
    }
  }
}

`/readyz`

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 of a successful request:

curl -i http://localhost:4000/readyz
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"}

Example of a failed response:

curl -i http://localhost:4000/readyz
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"}

`/livez`

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.

Example of a successful response:

curl -i http://localhost:4000/livez
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"}

Example of a failed response:

curl -i http://localhost:4000/livez
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?