@cubejs-client/core
Vanilla JavaScript client for Cube.
cube
cube(apiToken: string | () => Promise‹string›, options: CubeApiOptions): CubeApiCreates an instance of the
CubeApi. The API entry point.
| 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
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?: LoadMethodCallback‹TDryRunResponse›): voidGet query related meta without query execution
load
load(query: Query | Query[], options?: LoadMethodOptions): Promise‹ResultSet›
load(query: Query | Query[], options?: LoadMethodOptions, callback?: LoadMethodCallback‹ResultSet›): voidFetch data for the passed
query.
| Name | Type | Description |
|---|---|---|
| query | Query | Query[] | Query object |
| options? | LoadMethodOptions | - |
| callback? | LoadMethodCallback‹ResultSet› | - |
meta
meta(options?: LoadMethodOptions): Promise‹Meta›
meta(options?: LoadMethodOptions, callback?: LoadMethodCallback‹Meta›): voidGet meta description of cubes available for querying.
sql
sql(query: Query | Query[], options?: LoadMethodOptions): Promise‹SqlQuery›
sql(query: Query | Query[], options?: LoadMethodOptions, callback?: LoadMethodCallback‹SqlQuery›): voidGet generated SQL string for the given
query.
Parameters:
| Name | Type | Description |
|---|---|---|
| query | Query | Query[] | Query object |
| options? | LoadMethodOptions | - |
| callback? | LoadMethodCallback‹SqlQuery› | - |
subscribe
subscribe(query: Query | Query[], options: LoadMethodOptions | null, callback: LoadMethodCallback‹ResultSet›): voidAllows you to fetch data and receive updates over time. See Real-Time Data Fetch
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:
| Name | Type | Description |
|---|---|---|
| query | Query | null | context query to provide filtering of members available to add to this query |
| memberType | MemberType | - |
resolveMember
resolveMember‹T›(memberName: string, memberType: T | T[]): object | TCubeMemberByType‹T›Get meta information for a cube member Member meta information contains:
- T: MemberType
| Name | Type | Description |
|---|---|---|
| memberName | string | Fully qualified member name in a form Cube.memberName |
| memberType | T | 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
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.
decompose
decompose(): ObjectCan be used when you need access to the methods that can’t be used with some query types (eg
compareDateRangeQuery or blendingQuery)
drillDown
drillDown(drillDownLocator: DrillDownLocator, pivotConfig?: PivotConfig): Query | nullReturns a measure drill down query. Provided you have a measure with the defined
drillMemebers on the Orders cube
drillDown method to see the rows that contribute to that metric
order or limit to the query, you can simply spread it
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
query
query(): Query
rawData
rawData(): T[]
serialize
serialize(): ObjectCan be used to stash the
ResultSet in a storage and restored later with deserialize
series
series‹SeriesItem›(pivotConfig?: PivotConfig): Series‹SeriesItem›[]Returns an array of series with key, title and series data.
- SeriesItem
seriesNames
seriesNames(pivotConfig?: PivotConfig): SeriesNamesColumn[]Returns an array of series objects, containing
key and title parameters.
tableColumns
tableColumns(pivotConfig?: PivotConfig): TableColumn[]Returns an array of column definitions for
tablePivot.
For example:
tableColumns will group the table head and return
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:
deserialize
static deserialize‹TData›(data: Object, options?: Object): ResultSet‹TData›
- TData
| Name | Type | Description |
|---|---|---|
| data | Object | the 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
| Name | Type |
|---|---|
| format? | “currency” | “percent” | “number” |
| shortTitle | string |
| title | string |
| type | string |
BinaryFilter
| Name | Type |
|---|---|
| and? | BinaryFilter[] |
| dimension? | string |
| member? | string |
| operator | BinaryOperator |
| or? | BinaryFilter[] |
| values | string[] |
BinaryOperator
BinaryOperator: “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 |
DateRange
DateRange: string | [string, string]
DrillDownLocator
| Name | Type |
|---|---|
| xValues | string[] |
| yValues? | string[] |
Filter
Filter: BinaryFilter | UnaryFilter
LoadMethodCallback
LoadMethodCallback: function
LoadMethodOptions
| Name | Type | Optional? | Description |
|---|---|---|---|
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 |
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
Users.gender dimension on y axis
| Users Country | male, Orders.count | female, Orders.count |
|---|---|---|
| Australia | 3 | 27 |
| Germany | 10 | 12 |
| US | 5 | 7 |
Users.country dimension on y axis instead
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 |
measures on x axis. But in either case it should always be the last item of the array.
| 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. |
PivotQuery
PivotQuery: 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› |
QueryOrder
QueryOrder: “asc” | “desc”
QueryType
QueryType: “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 |
SqlQueryTuple
SqlQueryTuple: [string, boolean | string | number]
TCubeDimension
TCubeDimension: TCubeMember & object
TCubeMeasure
TCubeMeasure: TCubeMember & object
TCubeMember
| Name | Type |
|---|---|
| name | string |
| shortTitle | string |
| title | string |
| isVisible? | boolean |
| meta? | any |
| type | TCubeMemberType |
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
| 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[] |
TQueryOrderArray
TQueryOrderArray: Array‹[string, QueryOrder]›
TQueryOrderObject
TableColumn
| Name | Type |
|---|---|
| children? | TableColumn[] |
| dataIndex | string |
| format? | any |
| key | string |
| meta | any |
| shortTitle | string |
| title | string |
| type | string | number |
TimeDimension
TimeDimension: TimeDimensionComparison | TimeDimensionRanged
TimeDimensionBase
| Name | Type |
|---|---|
| dimension | string |
| granularity? | TimeDimensionGranularity |
TimeDimensionComparison
TimeDimensionComparison: TimeDimensionBase & object
TimeDimensionGranularity
TimeDimensionGranularity: “second” | “minute” | “hour” | “day” | “week” | “month” | “year”
TimeDimensionRanged
TimeDimensionRanged: 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 |
UnaryOperator
UnaryOperator: “set” | “notSet”