Rakam

Create Recipe

We have an embedded IDE for developing recipes for Rakam. The files are pushed to GIT and synchronized to Rakam via recipes.

The language that we're using is Jsonnet, it allows us to build composable models & reports & dashboards. You can find the documentation of Jsonnet from here and some example Rakam recipes from here.

Directory structure

The recipes must have a file called _config.jsonnet that contains info about the recipe. Here is how it looks like:

{
  version: 1.0, // will be used when the users upgrade their recipes
  label: 'The label will be shown in recipe page',
  description: 'The description will be shown in recipe page',
  image: 'The URL of the image for the recipe (optional)',
  tags: ['marketing'], // the tags will be converted to the categories in recipe page for discovery
  databases: ["snowflake"] // if your recipe only works in some databases, list them here: Allowed values are the slug of the warehouses (see https://docs.rakam.io/docs/supported-warehouses),
  variables: { // see the info in below
     example: {
        label: 'Example',
        type: 'string',
        default: 'Example value'
     }
  }
}
{
  name: 'example model',
  measures: {
    all_rows: {
      aggregation: 'count'
    }
  },
  dimensions: {
    category: {
      column: 'category'
    }
  }
}
{
   name: 'example dashboard',
   reports: [
    // Report
   ]
}

We compile the following files with the appropriate suffixes in your repo:

Suffix

Model Name

Schema

.model.jsonnet

Model

See the spec below

.dashboard.jsonnet

Dashboard

See the spec below

.models.jsonnet

Array of Model

See the spec below

.dashboards.jsonnet

Array of Dashboard

See the spec below

Project recipes

(in beta, available upon request)
If you want to manage your models via code, you can enable the project recipes and make the model page read-only. Once you commit a new model to your GIT repository or change the model definition, we will sync the model definitions on Rakam automatically via webhooks.

Publishing your recipe on Rakam

All of our public recipes are in this repository: rakam-io/recipes.
You can fork the repo, commit your integration and create a pull request in order to publish your own recipes on Rakam. Once the PR is merged, your recipe will be automatically visible to all users of Rakam.

Building recipe from the current project

You can export the project as a JSON dump by using the export button in the recipe page. The JSON file can be converted to Jsonnet files using the following snippet: https://github.com/rakam-io/recipes#converting-json-dump-to-recipe

Variables

You can customize your recipe using the variables. They allow you to get data from the user who is installing the recipe. If you want them to customize the recipe or enter the required values, define the variables under _config.jsonnet and they will be visible as form components to the user while installing the recipes. The values the user entered will be injected into your recipe using external variables in Jsonnet. (i.e std.extVar('variableName')). You can find the documentation about external variables here. Here are the allowed values for the type of variables:

Type names

Description

Extra Properties

numeric, string, boolean`

primitive values

dropdown, choice

being used for allowing the user to select one or more items.

multiple: true and choices: []

model, dimension, measure

can be used if you need extra model definitions in your recipe.

table, schema, and table-column

can be used if you want to use it to provide database relations.

target

can be used if you want the user to select the target a materialized SQL model.

Updated 6 months ago

Create Recipe


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.