@cubejs-client/core

Vanilla JavaScript Cube.js client.

cubejs(apiToken: string | () => Promise<string>, options: CubeJSApiOptions): CubejsApi

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

import cubejs from '@cubejs-client/core';
const cubejsApi = cubejs(
  'CUBEJS-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 cubejs from '@cubejs-client/core';
const cubejsApi = cubejs(
  async () => await Auth.getJwtToken(),
  { apiUrl: 'http://localhost:4000/cubejs-api/v1' }
);
Parameters:
NameTypeDescription
apiTokenstring | () => Promise<string>
optionsCubeJSApiOptions
cubejs(options: CubeJSApiOptions): CubejsApi

areQueriesEqual(query1: DeeplyReadonly<Query> | null, query2: DeeplyReadonly<Query> | null): boolean

defaultHeuristics(newState: TDefaultHeuristicsState, oldQuery: Query, options: TDefaultHeuristicsOptions): TDefaultHeuristicsResponse

defaultOrder(query: DeeplyReadonly<Query>): object

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

validateQuery(query: DeeplyReadonly<Query> | null | undefined): Query

Main class for accessing Cube.js API

dryRun(query: DeeplyReadonly<Query | Query[]>, options?: LoadMethodOptions): Promise<DryRunResponse>
dryRun(query: DeeplyReadonly<Query | Query[]>, options: LoadMethodOptions, callback?: LoadMethodCallback<DryRunResponse>): void

Get query related meta without query execution

load<QueryType>(query: QueryType, options?: LoadMethodOptions): Promise<ResultSet<QueryRecordType<QueryType>>>

Type parameters:

  • QueryType: DeeplyReadonly<Query | Query[]>
load<QueryType>(query: QueryType, options?: LoadMethodOptions, callback?: LoadMethodCallback<ResultSet<QueryRecordType<QueryType>>>): void

Fetch data for the passed query.

import cubejs from '@cubejs-client/core';
import Chart from 'chart.js';
import chartjsConfig from './toChartjsData';

const cubejsApi = cubejs('CUBEJS_TOKEN');

const resultSet = await cubejsApi.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));

Type parameters:

  • QueryType: DeeplyReadonly<Query | Query[]>
Parameters:
NameTypeDescription
queryQueryType
options?LoadMethodOptions
callback?LoadMethodCallback<ResultSet<QueryRecordType<QueryType>>>
load<QueryType>(query: QueryType, options?: LoadMethodOptions, callback?: LoadMethodCallback<ResultSet>, responseFormat?: string): Promise<ResultSet<QueryRecordType<QueryType>>>

Type parameters:

  • QueryType: DeeplyReadonly<Query | Query[]>

meta(options?: LoadMethodOptions): Promise<Meta>
meta(options?: LoadMethodOptions, callback?: LoadMethodCallback<Meta>): void

Get meta description of cubes available for querying.

sql(query: DeeplyReadonly<Query | Query[]>, options?: LoadMethodOptions): Promise<SqlQuery>
sql(query: DeeplyReadonly<Query | Query[]>, options?: LoadMethodOptions, callback?: LoadMethodCallback<SqlQuery>): void

Get generated SQL string for the given query.

Parameters:
NameTypeDescription
queryDeeplyReadonly<Query | Query[]>
options?LoadMethodOptions
callback?LoadMethodCallback<SqlQuery>

subscribe<QueryType>(query: QueryType, options: LoadMethodOptions | null, callback: LoadMethodCallback<ResultSet<QueryRecordType<QueryType>>>): void

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

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

Type parameters:

  • QueryType: DeeplyReadonly<Query | Query[]>

Default transport implementation.

new HttpTransport(options: TransportOptions): HttpTransport

request(method: string, params: any): ITransportResponse<ResultSet>

Contains information about available cubes and it's members.

 cubes: Cube[] 

An array of all available cubes with their members

 cubesMap: Record<string, Pick<Cube, "dimensions" | "measures" | "segments">> 

A map of all cubes where the key is a cube name

 meta: MetaResponse 

Raw meta response

defaultTimeDimensionNameFor(memberName: string): string

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

membersForQuery(query: DeeplyReadonly<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
queryDeeplyReadonly<Query> | null
memberTypeMemberType

membersGroupedByCube(): any

resolveMember<T>(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:

  • T: MemberType
Parameters:
NameTypeDescription
memberNamestring
memberTypeT | T[]

stage(): string

timeElapsed(): string

Provides a convenient interface for data manipulation.

annotation(): QueryAnnotations

categories(pivotConfig?: PivotConfig): ChartPivotRow[]

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(): ResultSet[]

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(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(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

rawData(): T[]

serialize(): SerializedResult

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

series<SeriesItem>(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(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(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(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 },
  //...
]

tableRow(): ChartPivotRow

totalRow(pivotConfig?: PivotConfig): ChartPivotRow

static deserialize<TData>(data: Object, options?: Object): ResultSet<TData>
import { ResultSet } from '@cubejs-client/core';

const resultSet = await cubejsApi.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
dataObject
options?Object

static getNormalizedPivotConfig(query: PivotQuery, pivotConfig?: Partial<PivotConfig>): PivotConfig

rawQuery(): SqlData

sql(): string

 dimension? : string 

deprecated Use member instead.

 member? : string 

 operator: BinaryOperator 

 values: string[] 

request(method: string, params: Record<string, unknown>): ITransportResponse<R>

 subscribe: function 

 unsubscribe? : function 

 dimensions? : string[] 

 filters? : Filter[] 

 limit? : null | number 

 measures? : string[] 

 offset? : number 

 order? : TQueryOrderObject | TQueryOrderArray 

 renewQuery? : boolean 

 responseFormat? : "compact" | "default" 

 segments? : string[] 

 timeDimensions? : TimeDimension[] 

 timezone? : string 

 total? : boolean 

 ungrouped? : boolean 

 dimension? : string 

deprecated Use member instead.

 member? : string 

 operator: BinaryOperator 

 values: string[] 

 dimension: string 

 granularity? : TimeDimensionGranularity 

 dimension? : string 

deprecated Use member instead.

 member? : string 

 operator: UnaryOperator 

 values? : never 

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

NameType
isVisible?boolean
meta?any
namestring
shortTitlestring
titlestring
typeTCubeMemberType

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

NameType
xstring
xValuesstring[]

 ChartType: "line" | "bar" | "table" | "area" | "number" | "pie" 

NameType
keystring
series[]
titlestring

NameType
dimensionsTCubeDimension[]
measuresTCubeMeasure[]
namestring
segmentsTCubeSegment[]
titlestring

NameTypeDescription
apiUrlstringURL of your Cube.js Backend. 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
resType?"default" | "compact"
transport?ITransport<any>Transport implementation to use. [HttpTransport](#http-transport) will be used by default.

 CubeMember: TCubeMeasure | TCubeDimension | TCubeSegment 

 DateRange: string | [string, string] 

NameType
xValuesstring[]
yValues?string[]

NameType
normalizedQueriesQuery[]
pivotQueryPivotQuery
queryOrderArray<object>
queryTypeQueryType
transformedQueriesTransformedQuery[]

 ExtractMembers: T extends object ? Names : never | T extends object ? Names : never | T extends object ? ExtractTimeMembers<U> : never 

 ExtractTimeMember: T extends object ? Dimension | `${Dimension & string}.${Granularity & string}` : never 

 ExtractTimeMembers: T extends readonly [infer First] ? ExtractTimeMember<First> | ExtractTimeMembers<Rest> : never 

 Filter: BinaryFilter | UnaryFilter | LogicalOrFilter | LogicalAndFilter 

NameType
namestring
titlestring

NameType
additiveboolean
measurestring
type"count" | "countDistinct" | "sum" | "min" | "max" | "number" | "countDistinctApprox"

 LoadMethodCallback: function 

NameTypeDescription
progressCallback?
cubejsApi?CubejsApiA Cube.js API instance. If not provided will be taken from `CubeProvider`
mutexKey?stringKey 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.
mutexObj?ObjectObject to store MUTEX
subscribe?booleanPass `true` to use continuous fetch behavior.

NameType
pivotQueryPivotQuery
queryTypeQueryType
resultsLoadResponseResult<T>[]

NameType
annotationQueryAnnotations
dataT[]
dbTypestring
extDbTypestring
externalboolean | null
lastRefreshTimestring
queryQuery
requestId?string
total?number
transformedQuery?TransformedQuery
usedPreAggregations?Record<string, UsedPreAggregation>

NameType
andFilter[]

NameType
orFilter[]

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

NameType
cubesCube[]

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](#result-set-chart-pivot)
fillMissingDates?boolean | nullIf `true` missing dates on the time dimensions will be filled with `0` for all measures.Note: the `fillMissingDates` option set 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: Query & object 

NameType
xValuesArray<string | number>
yValuesArrayArray<[string[], number]>

 PreAggregationType: "rollup" | "rollupJoin" | "rollupLambda" | "originalSql" 

NameType
stagestring
timeElapsednumber

NameType
dimensionsRecord<string, Annotation>
measuresRecord<string, Annotation>
timeDimensionsRecord<string, Annotation>

 QueryArrayRecordType: T extends readonly [infer First] ? SingleQueryRecordType<First> | QueryArrayRecordType<Rest & DeeplyReadonly<Query[]>> : never 

 QueryOrder: "asc" | "desc" 

 QueryRecordType: T extends DeeplyReadonly<Query[]> ? QueryArrayRecordType<T> : T extends DeeplyReadonly<Query> ? SingleQueryRecordType<T> : never 

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

NameType
loadResponseLoadResponse<T>

NameType
keystring
seriesT[]
titlestring

NameType
keystring
titlestring
yValuesstring[]

 SingleQueryRecordType: ExtractMembers<T> extends never ? any : object 

NameType
aliasNameToMemberRecord<string, string>
cacheKeyQueriesSqlQueryTuple[]
dataSourceboolean
externalboolean
preAggregationsany[]
rollupMatchResultsany[]
sqlSqlQueryTuple

 SqlQueryTuple: [string, any[], any] 

 TCubeDimension: BaseCubeMember & object 

 TCubeMeasure: BaseCubeMember & object 

NameType
isVisible?boolean
meta?any
namestring
shortTitlestring
titlestring
typeTCubeMemberType

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

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

 TCubeSegment: Omit<BaseCubeMember, "type"> 

NameType
metaMeta
sessionGranularity?TimeDimensionGranularity

NameType
chartType?ChartType
pivotConfigPivotConfig | null
queryQuery
shouldApplyHeuristicOrderboolean

NameType
chartType?ChartType
queryQuery

deprecated use DryRunResponse

NameType
normalizedQueriesQuery[]
pivotQueryPivotQuery
queryOrderArray<object>
queryTypeQueryType
transformedQueriesTransformedQuery[]

NameType
nameTimeDimensionGranularity | undefined
titlestring

NameType
idstring
orderQueryOrder | "none"
titlestring

 TQueryOrderArray: Array<[string, QueryOrder]> 

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

 TimeDimension: TimeDimensionComparison | TimeDimensionRanged 

 TimeDimensionComparison: TimeDimensionBase & TimeDimensionComparisonFields 

NameType
compareDateRangeArray<DateRange>
dateRange?never

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

 TimeDimensionRanged: TimeDimensionBase & TimeDimensionRangedFields 

NameType
dateRange?DateRange

NameType
allFiltersWithinSelectedDimensionsboolean
granularityHierarchiesRecord<string, string[]>
hasMultipliedMeasuresboolean
hasNoTimeDimensionsWithoutGranularityboolean
isAdditiveboolean
leafMeasureAdditiveboolean
leafMeasuresstring[]
measureToLeafMeasures?Record<string, LeafMeasure[]>
measuresstring[]
sortedDimensionsstring[]
sortedTimeDimensions[[string, string]]

NameTypeDescription
apiUrlstringpath to `/cubejs-api/v1`
authorizationstring[jwt auth token](security)
credentials?"omit" | "same-origin" | "include"
headers?Record<string, string>custom headers
method?"GET" | "PUT" | "POST" | "PATCH"

 UnaryOperator: "set" | "notSet" 

NameType
targetTableNamestring
typePreAggregationType

 GRANULARITIES: TGranularityMap[] 

Did you find this page useful?