@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
defaultHeuristics(newQuery: Query, oldQuery: Query, options: TDefaultHeuristicsOptions): any
defaultOrder(query: Query): object
movePivotItem(pivotConfig: PivotConfig, sourceIndex: number, destinationIndex: number, sourceAxis: TSourceAxis, destinationAxis: TSourceAxis): PivotConfig
Main class for accessing Cube.js API
dryRun(query: Query | Query[], options?: LoadMethodOptions): Promise‹TDryRunResponse›
dryRun(query: Query | Query[], options: LoadMethodOptions, callback?: LoadMethodCallback‹TDryRunResponse›): void
Get query related meta without query execution
load(query: Query | Query[], options?: LoadMethodOptions): Promise‹ResultSet›
load(query: 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[] | 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 | 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› | - |
subscribe(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
cubejsApi.subscribe(
{
measures: ['Logs.count'],
timeDimensions: [
{
dimension: 'Logs.time',
granularity: 'hour',
dateRange: 'last 1440 minutes',
},
],
},
options,
(error, resultSet) => {
if (!error) {
// handle the update
}
}
);
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 | 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‹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:
Name | Type | Description |
---|---|---|
memberName | string | Fully qualified member name in a form Cube.memberName |
memberType | T | T[] | - |
stage(): string
timeElapsed(): string
Provides a convenient interface for data manipulation.
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"] },
//...
]
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(): 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(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)[#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: PivotQuery, pivotConfig?: Partial‹PivotConfig›): PivotConfig
rawQuery(): SqlData
sql(): string
request(method: string, params: any): () => Promise‹void›
Name | Type |
---|---|
format? | "currency" | "percent" | "number" |
shortTitle | string |
title | string |
type | string |
Name | Type |
---|---|
and? | BinaryFilter[] |
dimension? | string |
member? | string |
operator | BinaryOperator |
or? | BinaryFilter[] |
values | string[] |
BinaryOperator: "equals" | "notEquals" | "contains" | "notContains" | "gt" | "gte" | "lt" | "lte" | "inDateRange" | "notInDateRange" | "beforeDate" | "afterDate"
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› | - |
parseDateMeasures? | boolean | - |
pollInterval? | number | - |
transport? | ITransport | Transport implementation to use. HttpTransport will be used by default. |
DateRange: string | [string, string]
Name | Type |
---|---|
xValues | string[] |
yValues? | string[] |
Filter: BinaryFilter | UnaryFilter
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 |
---|---|
pivotQuery | PivotQuery |
queryType | QueryType |
results | LoadResponseResult‹T›[] |
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 |
---|---|---|
aliasSeries? | string[] | Give each series a prefix alias. Should have one entry for each query:measure. See chartPivot |
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. |
PivotQuery: Query & object
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? | TQueryOrderObject | TQueryOrderArray |
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"
QueryType: "regularQuery" | "compareDateRangeQuery" | "blendingQuery"
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 |
TCubeMemberByType: T extends "measures" ? TCubeMeasure : T extends "dimensions" ? TCubeDimension : T extends "segments" ? TCubeSegment : never
TCubeMemberType: "time" | "number" | "string" | "boolean"
TCubeSegment: Pick‹TCubeMember, "name" | "shortTitle" | "title"›
Name | Type |
---|---|
meta | Meta |
sessionGranularity? | TimeDimensionGranularity |
Name | Type |
---|---|
normalizedQueries | Query[] |
pivotQuery | PivotQuery |
queryOrder | Array‹object› |
queryType | QueryType |
Name | Type |
---|---|
dimension? | string |
member? | string |
operator | BinaryOperator |
values | string[] |
Name | Type |
---|---|
id | string |
order | QueryOrder | "none" |
title | string |
TQueryOrderArray: Array‹[string, QueryOrder]›
Name | Type |
---|---|
children? | TableColumn[] |
dataIndex | string |
format? | any |
key | string |
meta | any |
shortTitle | string |
title | string |
type | string | number |
TimeDimension: TimeDimensionComparison | TimeDimensionRanged
Name | Type |
---|---|
dimension | string |
granularity? | TimeDimensionGranularity |
TimeDimensionComparison: TimeDimensionBase & object
TimeDimensionGranularity: "second" | "minute" | "hour" | "day" | "week" | "month" | "year"
TimeDimensionRanged: TimeDimensionBase & object
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 |
Name | Type |
---|---|
and? | UnaryFilter[] |
dimension? | string |
member? | string |
operator | UnaryOperator |
or? | UnaryFilter[] |
values? | never |
UnaryOperator: "set" | "notSet"