docs-mintlify/reference/javascript-sdk/reference/cubejs-client-core.mdx
cubecube(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' }
);
If you need to set up cancellation for all requests made by this API instance:
import cube from '@cubejs-client/core';
// Create a controller for managing request cancellation
const controller = new AbortController();
const { signal } = controller;
const cubeApi = cube(
'CUBE-API-TOKEN',
{
apiUrl: 'http://localhost:4000/cubejs-api/v1',
signal: signal
}
);
// Later when you need to cancel all pending requests:
// controller.abort();
Parameters:
| Name | Type | Description |
|---|---|---|
| apiToken | string | () => 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. |
| options | CubeApiOptions | - |
cube(options: CubeApiOptions): CubeApi
defaultHeuristicsdefaultHeuristics(newQuery: Query, oldQuery: Query, options: TDefaultHeuristicsOptions): any
defaultOrderdefaultOrder(query: Query): object
movePivotItemmovePivotItem(pivotConfig: PivotConfig, sourceIndex: number, destinationIndex: number, sourceAxis: TSourceAxis, destinationAxis: TSourceAxis): PivotConfig
CubeApiMain class for accessing Cube API
dryRundryRun(query: Query | Query[], options?: LoadMethodOptions): Promise‹TDryRunResponse›
dryRun(query: Query | Query[], options: LoadMethodOptions, callback?: LoadMethodCallback‹TDryRunResponse›): void
Get query related meta without query execution
loadload(query: Query | Query[], options?: LoadMethodOptions): Promise‹ResultSet›
load(query: Query | Query[], options?: LoadMethodOptions, callback?: LoadMethodCallback‹ResultSet›): 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));
You can also use AbortController to cancel a request:
import cube from '@cubejs-client/core';
const cubeApi = cube('CUBE_TOKEN');
// Create an AbortController instance
const controller = new AbortController();
const { signal } = controller;
try {
// Pass the signal to the load method
const resultSetPromise = cubeApi.load(
{
measures: ['Orders.count'],
dimensions: ['Orders.status']
},
{ signal }
);
// To cancel the request at any time:
// controller.abort();
const resultSet = await resultSetPromise;
// Process the result
} catch (error) {
if (error.name === 'AbortError') {
console.log('Request was cancelled');
} else {
console.error('Error loading data:', error);
}
}
Parameters:
| Name | Type | Description |
|---|---|---|
| query | Query | Query[] | Query object |
| options? | LoadMethodOptions | - |
| callback? | LoadMethodCallback‹ResultSet› | - |
metameta(options?: LoadMethodOptions): Promise‹Meta›
meta(options?: LoadMethodOptions, callback?: LoadMethodCallback‹Meta›): void
Get meta description of cubes available for querying.
sqlsql(query: Query | Query[], options?: LoadMethodOptions): Promise‹SqlQuery›
sql(query: Query | Query[], options?: LoadMethodOptions, callback?: LoadMethodCallback‹SqlQuery›): void
Get generated SQL string for the given query.
Parameters:
| Name | Type | Description |
|---|---|---|
| query | Query | Query[] | Query object |
| options? | LoadMethodOptions | - |
| callback? | LoadMethodCallback‹SqlQuery› | - |
subscribesubscribe(query: Query | Query[], options: LoadMethodOptions | null, callback: LoadMethodCallback‹ResultSet›): 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
}
}
);
HttpTransportDefault transport implementation.
new HttpTransport(options: TransportOptions): HttpTransport
requestrequest(method: string, params: any): () => Promise‹any›
Implementation of ITransport
MetaContains information about available cubes and it's members.
defaultTimeDimensionNameFordefaultTimeDimensionNameFor(memberName: string): string
filterOperatorsForMemberfilterOperatorsForMember(memberName: string, memberType: MemberType | MemberType[]): any
membersForQuerymembersForQuery(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:
| Name | Type | Description |
|---|---|---|
| query | Query | null | context query to provide filtering of members available to add to this query |
| memberType | MemberType | - |
resolveMemberresolveMember‹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:
Parameters:
| Name | Type | Description |
|---|---|---|
| memberName | string | Fully qualified member name in a form Cube.memberName |
| memberType | T | T[] | - |
ProgressResultstagestage(): string
timeElapsedtimeElapsed(): string
ResultSetProvides a convenient interface for data manipulation.
annotationannotation(): QueryAnnotations
chartPivotchartPivot(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',
values: ['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'],
},
//...
];
decomposedecompose(): 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());
});
drillDowndrillDown(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
}
);
pivotpivot(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]
]
}
]
queryquery(): Query
rawDatarawData(): T[]
serializeserialize(): Object
Can be used to stash the ResultSet in a storage and restored later with deserialize
seriesseries‹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:
seriesNamesseriesNames(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'],
},
]
tableColumnstableColumns(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',
},
],
},
],
},
// ...
tablePivottablePivot(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
staticdeserialize‹TData›(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:
Parameters:
| Name | Type | Description |
|---|---|---|
| data | Object | the result of serialize |
| options? | Object | - |
getNormalizedPivotConfig
staticgetNormalizedPivotConfig(query: PivotQuery, pivotConfig?: Partial‹PivotConfig›): PivotConfig
SqlQueryrawQueryrawQuery(): SqlData
sqlsql(): string
ITransportrequestrequest(method: string, params: any): () => Promise‹void›
Annotation| Name | Type |
|---|---|
| format? | "currency" | "percent" | "number" |
| shortTitle | string |
| title | string |
| type | string |
CacheModeCacheMode: "stale-if-slow" | "stale-while-revalidate" | "must-revalidate" | "no-cache"
Cache mode options for query execution. See cache control for details on available strategies.
BinaryFilter| Name | Type |
|---|---|
| and? | BinaryFilter[] |
| dimension? | string |
| member? | string |
| operator | BinaryOperator |
| or? | BinaryFilter[] |
| values | string[] |
BinaryOperatorBinaryOperator: "equals" | "notEquals" | "contains" | "notContains" | "gt" | "gte" | "lt" | "lte" | "inDateRange" | "notInDateRange" | "beforeDate" | "afterDate"
ChartPivotRow| Name | Type |
|---|---|
| x | string |
| xValues | string[] |
Column| Name | Type |
|---|---|
| key | string |
| series | [] |
| title | string |
CubeApiOptions| Name | Type | Description |
|---|---|---|
| apiUrl | string | URL 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? | ITransport | Transport implementation to use. HttpTransport will be used by default. |
| signal? | AbortSignal | AbortSignal to cancel requests |
DateRangeDateRange: string | [string, string]
DrillDownLocator| Name | Type |
|---|---|
| xValues | string[] |
| yValues? | string[] |
FilterFilter: BinaryFilter | UnaryFilter
LoadMethodCallbackLoadMethodCallback: function
LoadMethodOptions| Name | Type | Optional? | Description |
|---|---|---|---|
cache | CacheMode | ✅ Yes | Server-side cache policy for query execution. Does not control client-side caching. See cache control for details on available strategies. |
castNumerics | boolean | ✅ Yes | Pass 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 or less than Number.MIN_SAFE_INTEGER can't be represented as JavaScript Number |
mutexKey | string | ✅ Yes | Key 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 | Object | ✅ Yes | Object to store MUTEX |
progressCallback | ✅ Yes | ||
subscribe | boolean | ✅ Yes | Pass true to use continuous fetch behavior. |
signal | AbortSignal | ✅ Yes | AbortSignal to cancel the request. This allows you to manually abort requests using AbortController. |
baseRequestId | string | ✅ Yes | Base request ID (spanId) to be used for the request. If not provided a random request ID will be generated. |
LoadResponse| Name | Type |
|---|---|
| pivotQuery | PivotQuery |
| queryType | QueryType |
| results | LoadResponseResult‹T›[] |
LoadResponseResult| Name | Type |
|---|---|
| annotation | QueryAnnotations |
| data | T[] |
| lastRefreshTime | string |
| query | Query |
MemberTypeMemberType: "measures" | "dimensions" | "segments"
PivotConfigConfiguration 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 Country | male, Orders.count | female, Orders.count |
|---|---|---|
| Australia | 3 | 27 |
| Germany | 10 | 12 |
| US | 5 | 7 |
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 Gender | Australia, Orders.count | Germany, Orders.count | US, Orders.count |
|---|---|---|---|
| male | 3 | 10 | 5 |
| female | 27 | 12 | 7 |
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 Gender | measures | Australia | Germany | US |
|---|---|---|---|---|
| male | Orders.count | 3 | 10 | 5 |
| female | Orders.count | 27 | 12 | 7 |
| Name | Type | Description |
|---|---|---|
| aliasSeries? | string[] | Give each series a prefix alias. Should have one entry for each query:measure. See chartPivot |
| fillMissingDates? | boolean | null | true by default. If set to true, missing dates on the time dimensions will be filled with fillWithValue or 0 by default for all measures. Note: setting this option to true will override any order applied to the query. |
| fillWithValue? | string | null | Value to autofill all the missing date's measure. |
| x? | string[] | Dimensions to put on x or rows axis. |
| y? | string[] | Dimensions to put on y or columns axis. |
PivotQueryPivotQuery: Query & object
PivotRow| Name | Type |
|---|---|
| xValues | Array‹string | number› |
| yValuesArray | Array‹[string[], number]› |
ProgressResponse| Name | Type |
|---|---|
| stage | string |
| timeElapsed | number |
Query| Name | Type |
|---|---|
| dimensions? | string[] |
| filters? | Filter[] |
| limit? | number |
| measures? | string[] |
| offset? | number |
| order? | TQueryOrderObject | TQueryOrderArray |
| renewQuery? | boolean |
| segments? | string[] |
| timeDimensions? | TimeDimension[] |
| timezone? | string |
| ungrouped? | boolean |
QueryAnnotations| Name | Type |
|---|---|
| dimensions | Record‹string, Annotation› |
| measures | Record‹string, Annotation› |
| timeDimensions | Record‹string, Annotation› |
QueryOrderQueryOrder: "asc" | "desc"
QueryTypeQueryType: "regularQuery" | "compareDateRangeQuery" | "blendingQuery"
Series| Name | Type |
|---|---|
| key | string |
| series | T[] |
| title | string |
SeriesNamesColumn| Name | Type |
|---|---|
| key | string |
| title | string |
| yValues | string[] |
SqlApiResponse| Name | Type |
|---|---|
| sql | SqlData |
SqlData| Name | Type |
|---|---|
| aliasNameToMember | Record‹string, string› |
| cacheKeyQueries | object |
| dataSource | boolean |
| external | boolean |
| sql | SqlQueryTuple |
SqlQueryTupleSqlQueryTuple: [string, boolean | string | number]
TCubeDimensionTCubeDimension: TCubeMember & object
TCubeMeasureTCubeMeasure: TCubeMember & object
TCubeMember| Name | Type |
|---|---|
| name | string |
| shortTitle | string |
| title | string |
| isVisible? | boolean |
| meta? | any |
| type | TCubeMemberType |
TCubeMemberByTypeTCubeMemberByType: T extends "measures" ? TCubeMeasure : T extends "dimensions" ? TCubeDimension : T extends "segments" ? TCubeSegment : never
TCubeMemberTypeTCubeMemberType: "time" | "number" | "string" | "boolean"
TCubeSegmentTCubeSegment: Pick‹TCubeMember, "name" | "shortTitle" | "title"›
TDefaultHeuristicsOptions| Name | Type |
|---|---|
| meta | Meta |
| sessionGranularity? | TimeDimensionGranularity |
TDryRunResponse| Name | Type |
|---|---|
| normalizedQueries | Query[] |
| pivotQuery | PivotQuery |
| queryOrder | Array‹object› |
| queryType | QueryType |
TFlatFilter| Name | Type |
|---|---|
| dimension? | string |
| member? | string |
| operator | BinaryOperator |
| values | string[] |
TQueryOrderArrayTQueryOrderArray: Array‹[string, QueryOrder]›
TQueryOrderObjectTableColumn| Name | Type |
|---|---|
| children? | TableColumn[] |
| dataIndex | string |
| format? | any |
| key | string |
| meta | any |
| shortTitle | string |
| title | string |
| type | string | number |
TimeDimensionTimeDimension: TimeDimensionComparison | TimeDimensionRanged
TimeDimensionBase| Name | Type |
|---|---|
| dimension | string |
| granularity? | TimeDimensionGranularity |
TimeDimensionComparisonTimeDimensionComparison: TimeDimensionBase & object
TimeDimensionGranularityTimeDimensionGranularity: "second" | "minute" | "hour" | "day" | "week" | "month" | "year"
TimeDimensionRangedTimeDimensionRanged: TimeDimensionBase & object
TransportOptions| Name | Type | Description |
|---|---|---|
| apiUrl | string | path to /cubejs-api/v1 |
| authorization | string | jwt auth token |
| credentials? | "omit" | "same-origin" | "include" | - |
| headers? | Record‹string, string› | custom headers |
| signal? | AbortSignal | AbortSignal to cancel requests |
UnaryFilter| Name | Type |
|---|---|
| and? | UnaryFilter[] |
| dimension? | string |
| member? | string |
| operator | UnaryOperator |
| or? | UnaryFilter[] |
| values? | never |
UnaryOperatorUnaryOperator: "set" | "notSet"