Documentation
APIs & integrations
JavaScript SDK

JavaScript SDK

Cube is visualization-agnostic, so you can build any user interface for your application.

You can directly query Cube Backend using JSON Query Format via HTTP API or WebSockets and visualize analytical data with tools of your choice. However, it's much easier to use the Cube JavaScript client and bindings for popular frameworks such as React, Angular, and Vue.

The client has methods to communicate with Cube API Gateway and retrieve and process data. It is designed to work with existing charting libraries including Chart.js, D3.js, and more.

Cube JavaScript Client

The client provides methods to solve common tasks:

Abstract from the transport and query data. You can fetch data from Cube Backend or subscribe to real-time updates regardless of the protocol, be it HTTP or WebSockets.

Transform data for visualization. You can pivot the result set to display as a chart or as a table, split into series or table columns.

Simplify work with complex query types. You can build Drill Down queries and decompose the results of compare date range queries or Data Blending queries.

Learn more in the documentation for the @cubejs-client/core package.

Example Usage

Here are the typical steps to query and visualize analytical data:

  • Import the @cubejs-client/core package. This package provides all the necessary methods.
  • Create an instance of Cube JavaScript Client. The client is initialized with Cube API URL. In development mode, the default URL is http://localhost:4000/cubejs-api/v1 (opens in a new tab). The client is also initialized with an API token, but it takes effect only in production.
  • Query data from Cube Backend. The client accepts a query, which is a plain JavaScript object. See Query Format for details.
  • Transform data for visualization. The result set has convenient methods, such as series and chartPivot, to prepare data for charting.
  • Visualize the data. Use tools of your choice to draw charts and create visualizations.

See an example of using Cube with vanilla JavaScript and Chart.js library. Note that you can always use a different charting library that suits your needs:

Getting Started

You can install Cube JavaScript Client with npm or Yarn:

# npm
npm install --save @cubejs-client/core

# Yarn
yarn add @cubejs-client/core

Now you can build your application from scratch or connect to one of our supported data visualization tools.

Data format

The REST API uses JSON to serialize and transfer result sets. Numbers, e.g., values of numeric measures, are represented as strings.

By default, JavaScript SDK also returns numbers as strings because an automatic conversion might lead to a precision loss. In JavaScript, only numbers between Number.MAX_SAFE_INTEGER (opens in a new tab) and Number.MIN_SAFE_INTEGER can be safely parsed from strings. However, there's no guarantee that a measure value or a column value from a supported data source would not be outside of this range.

If you'd like Cube to convert strings to numbers anyway, you can use the castNumerics option for that:

import cube from '@cubejs-client/core'
 
const cubeApi = cube(CUBE_API_TOKEN, {
  apiUrl: CUBE_API_URL
})
 
const resultSet = await cubeApi.load(query, {
  castNumerics: true
})
 
console.log(resultSet.tablePivot())
Privacy and SecurityReact