Reference
JavaScript SDK
core

@cubejs-client/core

Vanilla JavaScript client for Cube.

cube

cube(apiToken: string | () => Promise‹string›, options: CubeApiOptions): CubeApi

Creates an instance of the CubeApi. The API entry point.

import cube from '@cubejs-client/core';
const cubeApi = cube(
  'CUBE-API-TOKEN',
  { apiUrl: 'http://localhost:4000/cubejs-api/v1' }
);

You can also pass an async function or a promise that will resolve to the API token

import cube from '@cubejs-client/core';
const cubeApi = cube(
  async () => await Auth.getJwtToken(),
  { apiUrl: 'http://localhost:4000/cubejs-api/v1' }
);

Parameters:

NameTypeDescription
apiTokenstring | () => Promise‹string›API token is used to authorize requests and determine SQL database you're accessing. In the development mode, Cube will print the API token to the console on startup. In case of async function authorization is updated for options.transport on each request.
optionsCubeApiOptions-

cube(options: CubeApiOptions): CubeApi

defaultHeuristics

defaultHeuristics(newQuery: Query, oldQuery: Query, options: TDefaultHeuristicsOptions): any

defaultOrder

defaultOrder(query: Query): object

movePivotItem

movePivotItem(pivotConfig: PivotConfig, sourceIndex: number, destinationIndex: number, sourceAxis: TSourceAxis, destinationAxis: TSourceAxis): PivotConfig

CubeApi

Main class for accessing Cube API

dryRun

dryRun(query: Query | Query[], options?: LoadMethodOptions): Promise‹TDryRunResponse

dryRun(query: Query | Query[], options: LoadMethodOptions, callback?: LoadMethodCallbackTDryRunResponse›): void

Get query related meta without query execution

load

load(query: Query | Query[], options?: LoadMethodOptions): Promise‹ResultSet

load(query: Query | Query[], options?: LoadMethodOptions, callback?: LoadMethodCallbackResultSet›): void

Fetch data for the passed query.

import cube from '@cubejs-client/core';
import Chart from 'chart.js';
import chartjsConfig from './toChartjsData';
 
const cubeApi = cube('CUBE_TOKEN');
 
const resultSet = await cubeApi.load({
 measures: ['Stories.count'],
 timeDimensions: [{
   dimension: 'Stories.time',
   dateRange: ['2015-01-01', '2015-12-31'],
   granularity: 'month'
  }]
});
 
const context = document.getElementById('myChart');
new Chart(context, chartjsConfig(resultSet));

Parameters:

NameTypeDescription
queryQuery | Query[]Query object
options?LoadMethodOptions-
callback?LoadMethodCallbackResultSet-

meta

meta(options?: LoadMethodOptions): Promise‹Meta

meta(options?: LoadMethodOptions, callback?: LoadMethodCallbackMeta›): void

Get meta description of cubes available for querying.

sql

sql(query: Query | Query[], options?: LoadMethodOptions): Promise‹SqlQuery

sql(query: Query | Query[], options?: LoadMethodOptions, callback?: LoadMethodCallbackSqlQuery›): void

Get generated SQL string for the given query.

Parameters:

NameTypeDescription
queryQuery | Query[]Query object
options?LoadMethodOptions-
callback?LoadMethodCallbackSqlQuery-

subscribe

subscribe(query: Query | Query[], options: LoadMethodOptions | null, callback: LoadMethodCallbackResultSet›): void

Allows you to fetch data and receive updates over time. See Real-Time Data Fetch

cubeApi.subscribe(
  {
    measures: ['Logs.count'],
    timeDimensions: [
      {
        dimension: 'Logs.time',
        granularity: 'hour',
        dateRange: 'last 1440 minutes',
      },
    ],
  },
  options,
  (error, resultSet) => {
    if (!error) {
      // handle the update
    }
  }
);

HttpTransport

Default transport implementation.

constructor

new HttpTransport(options: TransportOptions): HttpTransport

request

request(method: string, params: any): () => Promise‹any›

Implementation of ITransport

Meta

Contains information about available cubes and it's members.

defaultTimeDimensionNameFor

defaultTimeDimensionNameFor(memberName: string): string

filterOperatorsForMember

filterOperatorsForMember(memberName: string, memberType: MemberType | MemberType[]): any

membersForQuery

membersForQuery(query: Query | null, memberType: MemberType): TCubeMeasure[] | TCubeDimension[] | TCubeMember[]

Get all members of a specific type for a given query. If empty query is provided no filtering is done based on query context and all available members are retrieved.

Parameters:

NameTypeDescription
queryQuery | nullcontext query to provide filtering of members available to add to this query
memberTypeMemberType-

resolveMember

resolveMemberT›(memberName: string, memberType: T | T[]): object | TCubeMemberByType‹T›

Get meta information for a cube member Member meta information contains:

{
  name,
  title,
  shortTitle,
  type,
  description,
  format
}

Type parameters:

Parameters:

NameTypeDescription
memberNamestringFully qualified member name in a form Cube.memberName
memberTypeT | T[]-

ProgressResult

stage

stage(): string

timeElapsed

timeElapsed(): string

ResultSet

Provides a convenient interface for data manipulation.

annotation

annotation(): QueryAnnotations

chartPivot

chartPivot(pivotConfig?: PivotConfig): ChartPivotRow[]

Returns normalized query result data in the following format.

You can find the examples of using the pivotConfig here

// For the query
{
  measures: ['Stories.count'],
  timeDimensions: [{
    dimension: 'Stories.time',
    dateRange: ['2015-01-01', '2015-12-31'],
    granularity: 'month'
  }]
}
 
// ResultSet.chartPivot() will return
[
  { "x":"2015-01-01T00:00:00", "Stories.count": 27120, "xValues": ["2015-01-01T00:00:00"] },
  { "x":"2015-02-01T00:00:00", "Stories.count": 25861, "xValues": ["2015-02-01T00:00:00"]  },
  { "x":"2015-03-01T00:00:00", "Stories.count": 29661, "xValues": ["2015-03-01T00:00:00"]  },
  //...
]
 

When using chartPivot() or seriesNames(), you can pass aliasSeries in the pivotConfig to give each series a unique prefix. This is useful for blending queries which use the same measure multiple times.

// For the queries
{
  measures: ['Stories.count'],
  timeDimensions: [
    {
      dimension: 'Stories.time',
      dateRange: ['2015-01-01', '2015-12-31'],
      granularity: 'month',
    },
  ],
},
{
  measures: ['Stories.count'],
  timeDimensions: [
    {
      dimension: 'Stories.time',
      dateRange: ['2015-01-01', '2015-12-31'],
      granularity: 'month',
    },
  ],
  filters: [
    {
      member: 'Stores.read',
      operator: 'equals',
      value: ['true'],
    },
  ],
},
 
// ResultSet.chartPivot({ aliasSeries: ['one', 'two'] }) will return
[
  {
    x: '2015-01-01T00:00:00',
    'one,Stories.count': 27120,
    'two,Stories.count': 8933,
    xValues: ['2015-01-01T00:00:00'],
  },
  {
    x: '2015-02-01T00:00:00',
    'one,Stories.count': 25861,
    'two,Stories.count': 8344,
    xValues: ['2015-02-01T00:00:00'],
  },
  {
    x: '2015-03-01T00:00:00',
    'one,Stories.count': 29661,
    'two,Stories.count': 9023,
    xValues: ['2015-03-01T00:00:00'],
  },
  //...
];

decompose

decompose(): Object

Can be used when you need access to the methods that can't be used with some query types (eg compareDateRangeQuery or blendingQuery)

resultSet.decompose().forEach((currentResultSet) => {
  console.log(currentResultSet.rawData());
});

drillDown

drillDown(drillDownLocator: DrillDownLocator, pivotConfig?: PivotConfig): Query | null

Returns a measure drill down query.

Provided you have a measure with the defined drillMemebers on the Orders cube

measures: {
  count: {
    type: `count`,
    drillMembers: [Orders.status, Users.city, count],
  },
  // ...
}

Then you can use the drillDown method to see the rows that contribute to that metric

resultSet.drillDown(
  {
    xValues,
    yValues,
  },
  // you should pass the `pivotConfig` if you have used it for axes manipulation
  pivotConfig
)

the result will be a query with the required filters applied and the dimensions/measures filled out

{
  measures: ['Orders.count'],
  dimensions: ['Orders.status', 'Users.city'],
  filters: [
    // dimension and measure filters
  ],
  timeDimensions: [
    //...
  ]
}

In case when you want to add order or limit to the query, you can simply spread it

// An example for React
const drillDownResponse = useCubeQuery(
   {
     ...drillDownQuery,
     limit: 30,
     order: {
       'Orders.ts': 'desc'
     }
   },
   {
     skip: !drillDownQuery
   }
 );

pivot

pivot(pivotConfig?: PivotConfig): PivotRow[]

Base method for pivoting ResultSet data. Most of the times shouldn't be used directly and chartPivot or tablePivot should be used instead.

You can find the examples of using the pivotConfig here

// For query
{
  measures: ['Stories.count'],
  timeDimensions: [{
    dimension: 'Stories.time',
    dateRange: ['2015-01-01', '2015-03-31'],
    granularity: 'month'
  }]
}
 
// ResultSet.pivot({ x: ['Stories.time'], y: ['measures'] }) will return
[
  {
    xValues: ["2015-01-01T00:00:00"],
    yValuesArray: [
      [['Stories.count'], 27120]
    ]
  },
  {
    xValues: ["2015-02-01T00:00:00"],
    yValuesArray: [
      [['Stories.count'], 25861]
    ]
  },
  {
    xValues: ["2015-03-01T00:00:00"],
    yValuesArray: [
      [['Stories.count'], 29661]
    ]
  }
]

query

query(): Query

rawData

rawData(): T[]

serialize

serialize(): Object

Can be used to stash the ResultSet in a storage and restored later with deserialize

series

seriesSeriesItem›(pivotConfig?: PivotConfig): Series‹SeriesItem›[]

Returns an array of series with key, title and series data.

// For the query
{
  measures: ['Stories.count'],
  timeDimensions: [{
    dimension: 'Stories.time',
    dateRange: ['2015-01-01', '2015-12-31'],
    granularity: 'month'
  }]
}
 
// ResultSet.series() will return
[
  {
    key: 'Stories.count',
    title: 'Stories Count',
    series: [
      { x: '2015-01-01T00:00:00', value: 27120 },
      { x: '2015-02-01T00:00:00', value: 25861 },
      { x: '2015-03-01T00:00:00', value: 29661 },
      //...
    ],
  },
]

Type parameters:

  • SeriesItem

seriesNames

seriesNames(pivotConfig?: PivotConfig): SeriesNamesColumn[]

Returns an array of series objects, containing key and title parameters.

// For query
{
  measures: ['Stories.count'],
  timeDimensions: [{
    dimension: 'Stories.time',
    dateRange: ['2015-01-01', '2015-12-31'],
    granularity: 'month'
  }]
}
 
// ResultSet.seriesNames() will return
[
  {
    key: 'Stories.count',
    title: 'Stories Count',
    yValues: ['Stories.count'],
  },
]

tableColumns

tableColumns(pivotConfig?: PivotConfig): TableColumn[]

Returns an array of column definitions for tablePivot.

For example:

// For the query
{
  measures: ['Stories.count'],
  timeDimensions: [{
    dimension: 'Stories.time',
    dateRange: ['2015-01-01', '2015-12-31'],
    granularity: 'month'
  }]
}
 
// ResultSet.tableColumns() will return
[
  {
    key: 'Stories.time',
    dataIndex: 'Stories.time',
    title: 'Stories Time',
    shortTitle: 'Time',
    type: 'time',
    format: undefined,
  },
  {
    key: 'Stories.count',
    dataIndex: 'Stories.count',
    title: 'Stories Count',
    shortTitle: 'Count',
    type: 'count',
    format: undefined,
  },
  //...
]

In case we want to pivot the table axes

// Let's take this query as an example
{
  measures: ['Orders.count'],
  dimensions: ['Users.country', 'Users.gender']
}
 
// and put the dimensions on `y` axis
resultSet.tableColumns({
  x: [],
  y: ['Users.country', 'Users.gender', 'measures']
})

then tableColumns will group the table head and return

{
  key: 'Germany',
  type: 'string',
  title: 'Users Country Germany',
  shortTitle: 'Germany',
  meta: undefined,
  format: undefined,
  children: [
    {
      key: 'male',
      type: 'string',
      title: 'Users Gender male',
      shortTitle: 'male',
      meta: undefined,
      format: undefined,
      children: [
        {
          // ...
          dataIndex: 'Germany.male.Orders.count',
          shortTitle: 'Count',
        },
      ],
    },
    {
      // ...
      shortTitle: 'female',
      children: [
        {
          // ...
          dataIndex: 'Germany.female.Orders.count',
          shortTitle: 'Count',
        },
      ],
    },
  ],
},
// ...

tablePivot

tablePivot(pivotConfig?: PivotConfig): Array‹object›

Returns normalized query result data prepared for visualization in the table format.

You can find the examples of using the pivotConfig here

For example:

// For the query
{
  measures: ['Stories.count'],
  timeDimensions: [{
    dimension: 'Stories.time',
    dateRange: ['2015-01-01', '2015-12-31'],
    granularity: 'month'
  }]
}
 
// ResultSet.tablePivot() will return
[
  { "Stories.time": "2015-01-01T00:00:00", "Stories.count": 27120 },
  { "Stories.time": "2015-02-01T00:00:00", "Stories.count": 25861 },
  { "Stories.time": "2015-03-01T00:00:00", "Stories.count": 29661 },
  //...
]

deserialize

static deserializeTData›(data: Object, options?: Object): ResultSet‹TData›

import { ResultSet } from '@cubejs-client/core';
 
const resultSet = await cubeApi.load(query);
// You can store the result somewhere
const tmp = resultSet.serialize();
 
// and restore it later
const resultSet = ResultSet.deserialize(tmp);

Type parameters:

  • TData

Parameters:

NameTypeDescription
dataObjectthe result of serialize
options?Object-

getNormalizedPivotConfig

static getNormalizedPivotConfig(query: PivotQuery, pivotConfig?: Partial‹PivotConfig›): PivotConfig

SqlQuery

rawQuery

rawQuery(): SqlData

sql

sql(): string

ITransport

request

request(method: string, params: any): () => Promise‹void›

Types

Annotation

NameType
format?"currency" | "percent" | "number"
shortTitlestring
titlestring
typestring

BinaryFilter

NameType
and?BinaryFilter[]
dimension?string
member?string
operatorBinaryOperator
or?BinaryFilter[]
valuesstring[]

BinaryOperator

BinaryOperator: "equals" | "notEquals" | "contains" | "notContains" | "gt" | "gte" | "lt" | "lte" | "inDateRange" | "notInDateRange" | "beforeDate" | "afterDate"

ChartPivotRow

NameType
xstring
xValuesstring[]

Column

NameType
keystring
series[]
titlestring

CubeApiOptions

NameTypeDescription
apiUrlstringURL of your Cube API. By default, in the development environment it is http://localhost:4000/cubejs-api/v1
credentials?"omit" | "same-origin" | "include"-
headers?Record‹string, string›-
parseDateMeasures?boolean-
pollInterval?number-
transport?ITransportTransport implementation to use. HttpTransport will be used by default.

DateRange

DateRange: string | [string, string]

DrillDownLocator

NameType
xValuesstring[]
yValues?string[]

Filter

Filter: BinaryFilter | UnaryFilter

LoadMethodCallback

LoadMethodCallback: function

LoadMethodOptions

NameTypeOptional?Description
castNumericsboolean✅ YesPass true if you'd like all members with the number type to be automatically converted to JavaScript Number type. Note that this is a potentially unsafe operation since numbers more than Number.MAX_SAFE_INTEGER (opens in a new tab) or less than Number.MIN_SAFE_INTEGER can't be represented as JavaScript Number
mutexKeystring✅ YesKey to store the current request's MUTEX inside the mutexObj. MUTEX object is used to reject orphaned queries results when new queries are sent. For example: if two queries are sent with the same mutexKey only the last one will return results.
mutexObjObject✅ YesObject to store MUTEX
progressCallback✅ Yes
subscribeboolean✅ YesPass true to use continuous fetch behavior.

LoadResponse

NameType
pivotQueryPivotQuery
queryTypeQueryType
resultsLoadResponseResult‹T›[]

LoadResponseResult

NameType
annotationQueryAnnotations
dataT[]
lastRefreshTimestring
queryQuery

MemberType

MemberType: "measures" | "dimensions" | "segments"

PivotConfig

Configuration object that contains information about pivot axes and other options.

Let's apply pivotConfig and see how it affects the axes

// Example query
{
  measures: ['Orders.count'],
  dimensions: ['Users.country', 'Users.gender']
}

If we put the Users.gender dimension on y axis

resultSet.tablePivot({
  x: ['Users.country'],
  y: ['Users.gender', 'measures']
})

The resulting table will look the following way

Users Countrymale, Orders.countfemale, Orders.count
Australia327
Germany1012
US57

Now let's put the Users.country dimension on y axis instead

resultSet.tablePivot({
  x: ['Users.gender'],
  y: ['Users.country', 'measures'],
});

in this case the Users.country values will be laid out on y or columns axis

Users GenderAustralia, Orders.countGermany, Orders.countUS, Orders.count
male3105
female27127

It's also possible to put the measures on x axis. But in either case it should always be the last item of the array.

resultSet.tablePivot({
  x: ['Users.gender', 'measures'],
  y: ['Users.country'],
});
Users GendermeasuresAustraliaGermanyUS
maleOrders.count3105
femaleOrders.count27127
NameTypeDescription
aliasSeries?string[]Give each series a prefix alias. Should have one entry for each query:measure. See chartPivot
fillMissingDates?boolean | nulltrue by default. If set to true, missing dates on the time dimensions will be filled with 0 for all measures. Note: setting this option to true will override any order applied to the query.
x?string[]Dimensions to put on x or rows axis.
y?string[]Dimensions to put on y or columns axis.

PivotQuery

PivotQuery: Query & object

PivotRow

NameType
xValuesArray‹string | number›
yValuesArrayArray‹[string[], number]›

ProgressResponse

NameType
stagestring
timeElapsednumber

Query

NameType
dimensions?string[]
filters?Filter[]
limit?number
measures?string[]
offset?number
order?TQueryOrderObject | TQueryOrderArray
renewQuery?boolean
segments?string[]
timeDimensions?TimeDimension[]
timezone?string
ungrouped?boolean

QueryAnnotations

NameType
dimensionsRecord‹string, Annotation
measuresRecord‹string, Annotation
timeDimensionsRecord‹string, Annotation

QueryOrder

QueryOrder: "asc" | "desc"

QueryType

QueryType: "regularQuery" | "compareDateRangeQuery" | "blendingQuery"

Series

NameType
keystring
seriesT[]
titlestring

SeriesNamesColumn

NameType
keystring
titlestring
yValuesstring[]

SqlApiResponse

NameType
sqlSqlData

SqlData

NameType
aliasNameToMemberRecord‹string, string›
cacheKeyQueriesobject
dataSourceboolean
externalboolean
sqlSqlQueryTuple

SqlQueryTuple

SqlQueryTuple: [string, boolean | string | number]

TCubeDimension

TCubeDimension: TCubeMember & object

TCubeMeasure

TCubeMeasure: TCubeMember & object

TCubeMember

NameType
namestring
shortTitlestring
titlestring
isVisible?boolean
meta?any
typeTCubeMemberType

TCubeMemberByType

TCubeMemberByType: T extends "measures" ? TCubeMeasure : T extends "dimensions" ? TCubeDimension : T extends "segments" ? TCubeSegment : never

TCubeMemberType

TCubeMemberType: "time" | "number" | "string" | "boolean"

TCubeSegment

TCubeSegment: Pick‹TCubeMember, "name" | "shortTitle" | "title"›

TDefaultHeuristicsOptions

NameType
metaMeta
sessionGranularity?TimeDimensionGranularity

TDryRunResponse

NameType
normalizedQueriesQuery[]
pivotQueryPivotQuery
queryOrderArray‹object›
queryTypeQueryType

TFlatFilter

NameType
dimension?string
member?string
operatorBinaryOperator
valuesstring[]

TQueryOrderArray

TQueryOrderArray: Array‹[string, QueryOrder]›

TQueryOrderObject

TableColumn

NameType
children?TableColumn[]
dataIndexstring
format?any
keystring
metaany
shortTitlestring
titlestring
typestring | number

TimeDimension

TimeDimension: TimeDimensionComparison | TimeDimensionRanged

TimeDimensionBase

NameType
dimensionstring
granularity?TimeDimensionGranularity

TimeDimensionComparison

TimeDimensionComparison: TimeDimensionBase & object

TimeDimensionGranularity

TimeDimensionGranularity: "second" | "minute" | "hour" | "day" | "week" | "month" | "year"

TimeDimensionRanged

TimeDimensionRanged: TimeDimensionBase & object

TransportOptions

NameTypeDescription
apiUrlstringpath to /cubejs-api/v1
authorizationstringjwt auth token
credentials?"omit" | "same-origin" | "include"-
headers?Record‹string, string›custom headers

UnaryFilter

NameType
and?UnaryFilter[]
dimension?string
member?string
operatorUnaryOperator
or?UnaryFilter[]
values?never

UnaryOperator

UnaryOperator: "set" | "notSet"