Edit this page

Getting Started

1. Scaffold the project

Run the following command to get started with Cube.js, specifying the project name and optionally your database using the -d flag.

$ npx cubejs-cli create <project name> -d <database type>

You can find all available databases here. For example, to create a new project with the Postgres database, use the following:

$ npx cubejs-cli create hello-world -d postgres

Once run, the create command will create a new project directory that contains the scaffolding for your new Cube.js project. This includes all the files necessary to spin up the Cube.js backend and some example schema files to highlight the format of the Cube.js Data Schema layer.

The .env file in this project directory contains placeholders for the relevant database credentials. Setting credentials is covered in the Connecting to the Database section.

Manually creating Data Schema files

You can also add schema files to the schema folder manually:

// schema/users.js

cube(`Users`, {
   measures: {
     type: `count`
   },

   dimensions: {
     age: {
       type: `number`,
       sql: `age`
     },

     createdAt: {
       type: `time`,
       sql: `createdAt`
     },

     country: {
       type: `string`,
       sql: `country`
     }
   }
});

Example Usage

Vanilla Javascript

Instantiate the Cube.js API and then use it to fetch data. CubejsApi.load() accepts a query, which is a plain Javascript object. Learn more about the query format here.

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

const cubejsApi = cubejs(
  'YOUR-CUBEJS-API-TOKEN',
  { apiUrl: 'http://localhost:4000/cubejs-api/v1' },
);

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));

React

Import cubejs and QueryRenderer components, and use them to fetch the data. In the example below, we use recharts to visualize data.

import React from 'react';
import { LineChart, Line, XAxis, YAxis } from 'recharts';
import cubejs from '@cubejs-client/core';
import { QueryRenderer } from '@cubejs-client/react';

const cubejsApi = cubejs(
  'YOUR-CUBEJS-API-TOKEN',
  { apiUrl: 'http://localhost:4000/cubejs-api/v1' },
);

export default () => {
  return (
    <QueryRenderer
      query={{
        measures: ['Stories.count'],
        dimensions: ['Stories.time.month']
      }}
      cubejsApi={cubejsApi}
      render={({ resultSet }) => {
        if (!resultSet) {
          return 'Loading...';
        }

        return (
          <LineChart data={resultSet.rawData()}>
            <XAxis dataKey="Stories.time"/>
            <YAxis/>
            <Line type="monotone" dataKey="Stories.count" stroke="#8884d8"/>
          </LineChart>
        );
      }}
    />
  )
}

Vue

Import cubejs and QueryRenderer components, and use them to fetch the data. In the example below, we use vue-chartkick to visualize data.

<template>
  <div class="hello">
    <query-renderer :cubejs-api="cubejsApi" :query="query">
      <template v-slot="{ measures, resultSet, loading }">
        <line-chart :data="transformData(resultSet)"></line-chart>
      </template>
    </query-renderer>
  </div>
</template>

<script>
import cubejs from '@cubejs-client/core';
import { QueryRenderer } from '@cubejs-client/vue';
import Vue from 'vue';
import VueChartkick from 'vue-chartkick';
import Chart from 'chart.js';

Vue.use(VueChartkick, { adapter: Chart });

const cubejsApi = cubejs(
  'YOUR-CUBEJS-API-TOKEN',
  { apiUrl: 'http://localhost:4000/cubejs-api/v1' },
);

export default {
  name: 'HelloWorld',
  components: {
    QueryRenderer,
  },
  props: {
    msg: String,
  },
  data() {
    const query = {
      measures: ['LineItems.count', 'LineItems.quantity', 'Orders.count'],
      timeDimensions: [
        {
          dimension: 'LineItems.createdAt',
          granularity: 'month',
        },
      ],
    };

    return {
      cubejsApi,
      query,
    };
  },
  methods: {
    transformData(resultSet) {
      const seriesNames = resultSet.seriesNames();
      const pivot = resultSet.chartPivot();
      const series = [];
      seriesNames.forEach((e) => {
        const data = pivot.map(p => [p.x, p[e.key]]);
        series.push({ name: e.key, data });
      });
      return series;
    },
  },
};
</script>

Angular

Add CubejsClientModule to your app.module.ts file:

import { CubejsClientModule } from '@cubejs-client/ngx';
import { environment } from '../../environments/environment';

const cubejsOptions = {
  token: environment.CUBEJS_API_TOKEN,
  options: { apiUrl: environment.CUBEJS_API_URL }
};

@NgModule({
  declarations: [
    ...
  ],
  imports: [
    ...,
    CubejsClientModule.forRoot(cubejsOptions)
  ],
  providers: [...],
  bootstrap: [...]
})
export class AppModule { }

Then you can inject CubejsClient into your components or services:

import { CubejsClient } from '@cubejs-client/ngx';

export class AppComponent {
  constructor(private cubejs:CubejsClient){}

  ngOnInit(){
    this.cubejs.load({
      measures: ["some_measure"]
    }).subscribe(
      resultSet => {
        this.data = resultSet.chartPivot();
      },
      err => console.log('HTTP Error', err)
    );
  }
}