SlicingDice Documentation

SlicingDice API Docs

Welcome to the SlicingDice API documentation. You'll find comprehensive guides and documentation to help you start working with SlicingDice as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Guides

How to create columns

First time checking our docs? You might want to start with the right foot by reading our Documentation Guide first.


In SlicingDice data is strongly typed and columns are responsible for organizing it. When you insert some data to your entities, you are actually storing data in one or multiple columns at a time. Think of SlicingDice's columns as regular columns in Relational Databases.

There are two main types of columns on SlicingDice: Attribute Columns and Event Columns. On this page, you can read more about the differences on Attribute and Event columns.

You should create a new column whenever you need to store an additional or a different type of data. For instance, in a database called Users, one column could be responsible for income and another for age. You can create as many columns per database as you want.

There are three ways for you to create columns:

  • Using the SlicingDice's control panel.
  • Using the /column API endpoint.
  • Using the "auto-create": ["column"] parameter when inserting data.

Pro Tip

Remember that you can also use test databases to create, list and edit columns before creating real columns on your production database.

Creating columns using the control panel

Watch this quick video below to learn step-by-step how to create columns using the SlicingDice's Control Panel.


Creating columns using /column endpoint

If you need more control over your column configurations, you can create columns manually through the /column API endpoint https://api.slicingdice.com/v1/column. Note you can create several columns in a single request, such as the following example:

$ curl -X POST https://api.slicingdice.com/v1/column \
    -H 'Authorization: MASTER_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '[
        {
            "name": "User State",
            "api-name": "state",
            "type": "string",
            "description": "State where the user lives",
            "storage": "latest-value"
        }, {
            "name": "User Age",
            "api-name": "age",
            "type": "integer",
            "storage": "latest-value"
        }
    ]'
from pyslicer import SlicingDice
slicingdice = SlicingDice(master_key='MASTER_API_KEY', uses_test_endpoint=True)

insert_data = [
    {
        "type": "string",
        "storage": "latest-value",
        "api-name": "state",
        "name": "User State",
        "description": "State where the user lives"
    }, 
    {
        "type": "integer",
        "storage": "latest-value",
        "api-name": "age",
        "name": "User Age"
    }
]
print(slicingdice.create_column(insert_data))

import com.slicingdice.jslicer.SlicingDice;
import java.io.IOException;
import org.json.JSONObject;
import org.json.JSONArray;

public class Example {
    public static void main(String[] args) throws IOException {
        SlicingDice slicingdice = new SlicingDice("MASTER_API_KEY", true);

        JSONArray insertData = new JSONArray()
        .put(new JSONObject()
            .put("type", "string")
            .put("storage", "latest-value")
            .put("api-name", "state")
            .put("name", "User State")
            .put("description", "State where the user lives"))
        .put(new JSONObject()
            .put("type", "integer")
            .put("storage", "latest-value")
            .put("api-name", "age")
            .put("name", "User Age"));
        JSONObject result = slicingdice.createColumn(insertData);
        System.out.println(result.toString());
    }
}
require 'rbslicer'
slicingdice = SlicingDice.new(master_key: 'MASTER_API_KEY', uses_test_endpoint: true)

insert_data = [
    {
        "type" => "string",
        "storage" => "latest-value",
        "api-name" => "state",
        "name" => "User State",
        "description" => "State where the user lives"
    }, 
    {
        "type" => "integer",
        "storage" => "latest-value",
        "api-name" => "age",
        "name" => "User Age"
    }
]
puts slicingdice.create_column(insert_data)

const SlicingDice = require('slicerjs');

const usesTestEndpoint = true;
const slicingdice = new SlicingDice({masterKey: 'MASTER_API_KEY'}, usesTestEndpoint);

const insertData = [
    {
        "type": "string",
        "storage": "latest-value",
        "api-name": "state",
        "name": "User State",
        "description": "State where the user lives"
    }, 
    {
        "type": "integer",
        "storage": "latest-value",
        "api-name": "age",
        "name": "User Age"
    }
];

slicingdice.createColumn(insertData).then((resp) => {
    console.log(resp);
}, (err) => {
    console.error(err);
});

<?php
use Slicer\SlicingDice;
$usesTestEndpoint = true;
$slicingdice = new SlicingDice(array("masterKey" => "MASTER_API_KEY"), $usesTestEndpoint);

$insertData = array(
    array(
        "type" => "string",
        "storage" => "latest-value",
        "api-name" => "state",
        "name" => "User State",
        "description" => "State where the user lives"
    ), 
    array(
        "type" => "integer",
        "storage" => "latest-value",
        "api-name" => "age",
        "name" => "User Age"
    )
);

print_r($slicingdice->createColumn($insertData));
?>
using System.Collections.Generic;
using Slicer;
using Newtonsoft.Json;

namespace SlicerTester.Console
{
    class Program
    {
        static void Main(string[] args)
        {
            var slicingdice = new SlicingDice(masterKey: "MASTER_API_KEY", usesTestEndpoint: true);

            var insertData = new List<dynamic>{
                new Dictionary<string, dynamic>{
                    {"type", "string"},
                    {"storage", "latest-value"},
                    {"api-name", "state"},
                    {"name", "User State"},
                    {"description", "State where the user lives"}
                }, 
                new Dictionary<string, dynamic>{
                    {"type", "integer"},
                    {"storage", "latest-value"},
                    {"api-name", "age"},
                    {"name", "User Age"}
                }
            };

            var result = slicingdice.createColumn(insertData);
            System.Console.WriteLine(JsonConvert.SerializeObject(result).ToString());
        }
    }
}
package main
import (
    "fmt"
    "github.com/SlicingDice/slicingdice-go/slicingdice"
)
func main() {
    keys := new(slicingdice.APIKey)
    keys.MasterKey = "MASTER_API_KEY"
    slicingdice := slicingdice.New(keys, 60)
    slicingdice.Test = true

    insertData := []interface{}{
        map[string]interface{}{
            "type": "string",
            "storage": "latest-value",
            "api-name": "state",
            "name": "User State",
            "description": "State where the user lives",
        },
        map[string]interface{}{
            "type": "integer",
            "storage": "latest-value",
            "api-name": "age",
            "name": "User Age",
        },
    }

    fmt.Println(slicingdice.createColumn(insertData))
}

Request parameters

The following parameters apply to all data types:

  • name (required)
    Column name as it'll show in control panel, up to 64 characters. All characters are allowed, except ' and ".

  • type (required)
    The actual type of the column according to the supported data types.

  • api-name (optional)
    Column name, up to 64 characters, as it'll be referenced in API requests. Usually, the api-name is a lowercase version of the name, replacing spaces and non-alphanumeric characters by dashes. If you don't inform an api-name, one will be automatically generated for you. For instance, given a column name My Column 3, the correspondent api-name is my-column-3. Only alphanumeric a-zA-Z0-9 and - characters are allowed. Please refer to SlicingDice's reserved words to learn which words cannot be used in this parameter.

  • description (optional)
    Describe what this column is about, useful when the api-name isn't very meaningful or may introduce ambiguity.

  • storage (required, except for unique-id, boolean and any event column)
    Defines whether the column stores only the latest value inserted (latest-value) or all inserted values (list-of-values).

  • dimension (optional)
    The dimension that the column will be created, if you don't specify a dimension the column will be created at the default dimension.

Request response to column creation

The column creation POST request above will result in this response below:

{
    "status": "success",
    "api-name": [
        "state", "age"
    ]
}

Response elements:

  • status - Request status, informing whether it was successful or not.
  • api-name - The api-name of created columns.

Important

Please note that, after creating a column, you cannot change its api-name or type parameters.


Creating columns using the auto-create parameter

When inserting data through the API, SlicingDice can be told to create new columns whenever it reads an api-name not previously associated to a column. This behavior is non default and it must be triggered by adding "auto-create": ["column"] on the outermost level of your insert request. Failure to add this parameter will cause an API error instead of allowing the column creation.

In the following example of an insertion command the columns state, age, and clicks will be automatically created with the respective types defined to string, integer, and string-event. Note the position of the "auto-create" key on the dictionary structure.

Entities
State
Age
Clicks

Entity1

CA

32

buy now button - {% convert_date 'YYYY-MM-DDT10:22:10Z' '-5d' %}

$ curl -X POST https://api.slicingdice.com/v1/insert \
    -H 'Authorization: MASTER_OR_WRITE_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
        "Entity1": {
            "state": "CA",
            "age": 32,
            "clicks": {
                "value": "buy now button",
                "date": "{% convert_date 'YYYY-MM-DDT10:22:10Z' '-5d' %}"
            }
        },
        "auto-create": ["column"]
    }'
from pyslicer import SlicingDice
slicingdice = SlicingDice(master_key='MASTER_API_KEY', uses_test_endpoint=True)

insert_data = {
    "Entity1": {
        "state": "CA",
        "age": 32,
        "clicks": {
            "date": "{% convert_date 'YYYY-MM-DDT10:22:10Z' '-5d' %}",
            "value": "buy now button"
        }
    },
    "auto-create": [
        "column"
    ]
}

print(slicingdice.insert(insert_data))

import com.slicingdice.jslicer.SlicingDice;
import java.io.IOException;
import org.json.JSONObject;
import org.json.JSONArray;

public class Example {
    public static void main(String[] args) throws IOException {
        SlicingDice slicingdice = new SlicingDice("MASTER_API_KEY", true);

        JSONObject insertData = new JSONObject()
        .put("Entity1", new JSONObject()
            .put("state", "CA")
            .put("age", 32)
            .put("clicks", new JSONObject()
                .put("date", "{% convert_date 'YYYY-MM-DDT10:22:10Z' '-5d' %}")
                .put("value", "buy now button")))
        .put("auto-create", new JSONArray()
            .put("column"));

        JSONObject result = slicingdice.insert(insertData);
        System.out.println(result.toString());
    }
}
require 'rbslicer'
slicingdice = SlicingDice.new(master_key: 'MASTER_API_KEY', uses_test_endpoint: true)

insert_data = {
    "Entity1" => {
        "state" => "CA",
        "age" => 32,
        "clicks" => {
            "date" => "{% convert_date 'YYYY-MM-DDT10:22:10Z' '-5d' %}",
            "value" => "buy now button"
        }
    },
    "auto-create" => [
        "column"
    ]
}

puts slicingdice.insert(insert_data)

const SlicingDice = require('slicerjs');

const usesTestEndpoint = true;
const slicingdice = new SlicingDice({masterKey: 'MASTER_API_KEY'}, usesTestEndpoint);

const insertData = {
    "Entity1": {
        "state": "CA",
        "age": 32,
        "clicks": {
            "date": "{% convert_date 'YYYY-MM-DDT10:22:10Z' '-5d' %}",
            "value": "buy now button"
        }
    },
    "auto-create": [
        "column"
    ]
};

slicingdice.insert(insertData).then((resp) => {
    console.log(resp);
}, (err) => {
    console.error(err);
});

<?php
use Slicer\SlicingDice;
$usesTestEndpoint = true;
$slicingdice = new SlicingDice(array("masterKey" => "MASTER_API_KEY"), $usesTestEndpoint);

$insertData = array(
    "Entity1" => array(
        "state" => "CA",
        "age" => 32,
        "clicks" => array(
            "date" => "{% convert_date 'YYYY-MM-DDT10:22:10Z' '-5d' %}",
            "value" => "buy now button"
        )
    ),
    "auto-create" => array(
        "column"
    )
);

print_r($slicingdice->insert($insertData));
?>
using System.Collections.Generic;
using Slicer;
using Newtonsoft.Json;

namespace SlicerTester.Console
{
    class Program
    {
        static void Main(string[] args)
        {
            var slicingdice = new SlicingDice(masterKey: "MASTER_API_KEY", usesTestEndpoint: true);

            var insertData = new Dictionary<string, dynamic>{
                {"Entity1", new Dictionary<string, dynamic>{
                    {"state", "CA"},
                    {"age", 32},
                    {"clicks", new Dictionary<string, dynamic>{
                        {"date", "{% convert_date 'YYYY-MM-DDT10:22:10Z' '-5d' %}"},
                        {"value", "buy now button"}
                    }}
                }},
                {"auto-create", new List<dynamic>{
                    "column"
                }}
            };

            var result = slicingdice.Insert(insertData);
            System.Console.WriteLine(JsonConvert.SerializeObject(result).ToString());
        }
    }
}
package main
import (
    "fmt"
    "github.com/SlicingDice/slicingdice-go/slicingdice"
)
func main() {
    keys := new(slicingdice.APIKey)
    keys.MasterKey = "MASTER_API_KEY"
    slicingdice := slicingdice.New(keys, 60)
    slicingdice.Test = true

    insertData := map[string]interface{}{
        "Entity1": map[string]interface{}{
            "state": "CA",
            "age": 32,
            "clicks": map[string]interface{}{
                "date": "{% convert_date 'YYYY-MM-DDT10:22:10Z' '-5d' %}",
                "value": "buy now button",
            },
        },
        "auto-create": []interface{}{
            "column",
        },
    }

    fmt.Println(slicingdice.Insert(insertData))
}

When using "auto-create": ["column"], a column's data type is automatically identified based on the first entry ever insert to that column. The guidelines taken by SlicingDice when making this educated guess are described here.