@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:
| 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.js Backend will print the API token to the console on on startup. In case of async function authorization is updated for options.transport on each request. |
| options | CubeJSApiOptions | - |
▸ cubejs(options: CubeJSApiOptions): CubejsApi
Main class for accessing Cube.js API
▸ load(query: Query, options?: LoadMethodOptions): Promise‹ResultSet›
▸ load(query: Query, options?: LoadMethodOptions, callback?: LoadMethodCallback‹ResultSet›): 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));
Parameters:
| Name | Type | Description |
|---|---|---|
| query | Query | Query object |
| options? | LoadMethodOptions | - |
| callback? | LoadMethodCallback‹ResultSet› | - |
▸ meta(options?: LoadMethodOptions): Promise‹Meta›
▸ meta(options?: LoadMethodOptions, callback?: LoadMethodCallback‹Meta›): void
Get meta description of cubes available for querying.
▸ sql(query: Query, options?: LoadMethodOptions): Promise‹SqlQuery›
▸ sql(query: Query, options?: LoadMethodOptions, callback?: LoadMethodCallback‹SqlQuery›): void
Get generated SQL string for the given query.
Parameters:
| Name | Type | Description |
|---|---|---|
| query | Query | Query object |
| options? | LoadMethodOptions | - |
| callback? | LoadMethodCallback‹SqlQuery› | - |
Default transport implementation.
+ new HttpTransport(options: TransportOptions): HttpTransport
▸ request(method: string, params: any): () => Promise‹any›
Implementation of ITransport
Contains information about available cubes and it's members.
▸ defaultTimeDimensionNameFor(memberName: string): string
▸ filterOperatorsForMember(memberName: string, memberType: MemberType): any
▸ 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:
| Name | Type | Description |
|---|---|---|
| query | Query | null | context query to provide filtering of members available to add to this query |
| memberType | MemberType | - |
▸ resolveMember(memberName: string, memberType: MemberType): Object
Get meta information for a cube member Member meta information contains:
{
name,
title,
shortTitle,
type,
description,
format
}
Parameters:
| Name | Type | Description |
|---|---|---|
| memberName | string | Fully qualified member name in a form Cube.memberName |
| memberType | MemberType | - |
▸ stage(): string
▸ timeElapsed(): string
Provides a convenient interface for data manipulation.
+ new ResultSet(loadResponse: LoadResponse‹T›, options?: Object): ResultSet
Creates a new instance of ResultSet based on LoadResponse data.
import cubejs, { ResultSet } from '@cubejs-client/core';
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 copy = new ResultSet(resultSet.loadResponse);
▸ annotation(): QueryAnnotations
▸ 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"] },
//...
]
▸ 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: [
//...
]
}
▸ pivot(pivotConfig?: PivotConfig): PivotRow[]
Base method for pivoting ResultSet data. Most of the times shouldn't be used directly and chartPivot or (tablePivot)[#table-pivot] 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(): Object
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 },
//...
]
▸ 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:
| Name | Type | Description |
|---|---|---|
| data | Object | the result of serialize |
| options? | Object | - |
▸ static getNormalizedPivotConfig(query: Query, pivotConfig?: Partial‹PivotConfig›): PivotConfig
▸ rawQuery(): SqlData
▸ sql(): string
▸ request(method: string, params: any): () => Promise‹void›
| Name | Type |
|---|---|
| format? | "currency" | "percentage" |
| shortTitle | string |
| title | string |
| type | string |
| Name | Type |
|---|---|
| x | string |
| xValues | string[] |
| Name | Type |
|---|---|
| key | string |
| series | [] |
| title | string |
| Name | Type | Description |
|---|---|---|
| apiUrl | string | URL 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› | - |
| pollInterval? | number | - |
| transport? | ITransport | Transport implementation to use. HttpTransport will be used by default. |
| Name | Type |
|---|---|
| xValues | string[] |
| yValues? | string[] |
| Name | Type |
|---|---|
| dimension? | string |
| member? | string |
| operator | string |
| values? | string[] |
Ƭ LoadMethodCallback: function
| Name | Type | Description |
|---|---|---|
| progressCallback? | - | |
| mutexKey? | string | 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 | Object to store MUTEX |
| subscribe? | boolean | Pass true to use continuous fetch behavior. |
| Name | Type |
|---|---|
| annotation | QueryAnnotations |
| data | T[] |
| lastRefreshTime | string |
| query | Query |
Ƭ MemberType: "measures" | "dimensions" | "segments"
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 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 |
|---|---|---|
| fillMissingDates? | boolean | null | If 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. |
| Name | Type |
|---|---|
| xValues | Array‹string | number› |
| yValuesArray | Array‹[string[], number]› |
| Name | Type |
|---|---|
| stage | string |
| timeElapsed | number |
| Name | Type |
|---|---|
| dimensions? | string[] |
| filters? | Filter[] |
| limit? | number |
| measures? | string[] |
| offset? | number |
| order? | object |
| renewQuery? | boolean |
| segments? | string[] |
| timeDimensions? | TimeDimension[] |
| timezone? | string |
| ungrouped? | boolean |
| Name | Type |
|---|---|
| dimensions | Record‹string, Annotation› |
| measures | Record‹string, Annotation› |
| timeDimensions | Record‹string, Annotation› |
Ƭ QueryOrder: "asc" | "desc"
| Name | Type |
|---|---|
| key | string |
| series | T[] |
| title | string |
| Name | Type |
|---|---|
| key | string |
| title | string |
| yValues | string[] |
| Name | Type |
|---|---|
| sql | SqlData |
| Name | Type |
|---|---|
| aliasNameToMember | Record‹string, string› |
| cacheKeyQueries | object |
| dataSource | boolean |
| external | boolean |
| sql | SqlQueryTuple |
Ƭ SqlQueryTuple: [string, boolean | string | number]
Ƭ TCubeDimension: TCubeMember & object
Ƭ TCubeMeasure: TCubeMember & object
| Name | Type |
|---|---|
| name | string |
| shortTitle | string |
| title | string |
| type | TCubeMemberType |
Ƭ TCubeMemberType: "time" | "number" | "string" | "boolean"
| Name | Type |
|---|---|
| children? | TableColumn[] |
| dataIndex | string |
| format? | any |
| key | string |
| meta | any |
| shortTitle | string |
| title | string |
| type | string | number |
| Name | Type |
|---|---|
| dateRange? | string | string[] |
| dimension | string |
| granularity? | TimeDimensionGranularity |
Ƭ TimeDimensionGranularity: "hour" | "day" | "week" | "month" | "year"
| 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 |
