SlicingDice API Docs

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    Documentation

Quickstart guide

This page will help you get started with SlicingDice very easy and quick.

The goal of this guide is to help you get started with SlicingDice in 15 minutes or less. If you have any trouble following the steps please let us know so we can help you and improve it.

Introduction

At the end of this guide, you can expect to:

  • Understand what columns and entities are;
  • Know how to create a database;
  • Know how to create attribute and event columns;
  • Insert attribute and event data in an existing database;
  • Analyze data with different types of queries: count entity, count event and aggregation;
  • Retrieve stored data using data extraction queries;

Use case selection

In order to have a better and personalized experience on this guide, please select below the use case that looks like more similar to yours, as it will facilitate your learning and understanding.

Please select one:

Use case description:
<% useCase.description %>


Creating a database

A database on SlicingDice is exactly the same as in a relational database, it contains tables and columns as you will see below.

For the purpose of this quickstart, you don't need to create a database, as we will be using an auto-generated demo API key below and our /test endpoint with a brand new ephemeral database created exclusively for you. You don't need to do anything, we have already placed this demo API key on all examples present on this guide.

This is the API key we will be using in this guide:

You can later check this page to see a step by step guide of how to create a production database using our control panel.

Anyway, don't worry about it for now.


Inserting data

As you selected the <% useCase.name %> use case, consider you have this data on the spreadsheet below and that you want to insert it on SlicingDice.

As you can see above, we have some rows and columns.

Rows

The rows are identifying the entities. As you can read on our Glossary, an entity is basically to "whom" the data will be associated and stored on SlicingDice. They are like a primary key in relational databases.

To make things clear, let's use the data table from spreadsheet above. As you can see, there are <% useCase.entities().length %> entities on that table (such as <% useCase.entities()[0] %>, <% useCase.entities()[1] %>, etc). These identifiers are the Entity ID for whom you are going to insert data in the columns <% useCase.columns()[0] %>, <% useCase.columns()[1] %>, etc.

Just for you to know, when you create a database or a table, SlicingDice automatically creates a Unique ID attribute column called Entity ID (with API name entity-id) for that table. This column will be transparently used by SlicingDice to store the Entity ID of all entities you insert on the table.

Columns

There are two types of columns on SlicingDice: Attribute Columns and Event Columns.

Again, take a look on the spreadsheet above, as you can see, the <% useCase.eventColumns()[0] %> column is storing event data (the value and a timestamp), and the other columns are storing attributes, like <% useCase.attributeColumns()[0] %>.

  • Attribute Columns is a column type used to store any data not associated to a date/time. For example: storing the value <% useCase.insertData[useCase.entities()[0]][useCase.attributeColumns()[0]] %> for the <% useCase.attributeColumns()[0] %> column. In this case the column and its value is not associated to a specific date/time.

  • Event Columns is a column type used to store data that is associated to a date/time. For example: storing the value <% useCase.insertData[useCase.entities()[0]][useCase.eventColumns()[0]][0].value %> on the date/time <% useCase.insertData[useCase.entities()[0]][useCase.eventColumns()[0]][0].date %> for the <% useCase.eventColumns()[0] %> event column. In this case it's important to know when the event happened.

You can later check this page for a detailed comparison on attribute and event columns, but for now you are all set to move forward.

JSON representation

As you can see below, the data presented in the spreadsheet is now represented as a JSON request, that is the format we use to send insertion requests to SlicingDice.

Pro Tip

If you add a new column or a new row on the spreadsheet above, it will automatically update this JSON request below. So before moving forward and pushing the Insert Button, play with it, add some values on the spreadsheet or change what is there.

Where are the tables and columns?

As you probably noticed, we inserted data on SlicingDice without creating any table or column in advance. The reason for that is because on the insertion request we used the "auto-create": ["table", "column"] parameter, that dynamically creates a table and a column if it doesn't exist yet. You can later access this page to read more about the auto-create parameter.

It's also possible to create columns in advance at any time, as you can see on this how to create columns page. Anyway, for the purpose of this quickstart, you don't need to worry about column creation.


Quick recap

Before moving to the queries, just to recap, you have just successfully inserted data on SlicingDice for <% useCase.entities().length %> entities, using <% useCase.columns().length %> columns, which <% useCase.attributeColumns().length %> of them is/are attribute column(s) (such as <% useCase.attributeColumns()[0] %>) and <% useCase.eventColumns().length %> is/are event column(s) (such as <% useCase.eventColumns()[0] %>). You have also used the "auto-create": ["table", "column"] parameter so a default table and all the columns were automatically created for you during the data insertion.

Great! Now you are ready to start making queries on your data.


Querying data

SlicingDice's API supports making all types of queries you would normally do using SQL.

Result data extraction query

Let's start by making sure the data you inserted above is actually correctly stored on SlicingDice. In order to do that, we will use the result data extraction query type.

When using the result data extraction query, you select the entities that will be retrieved with the query parameter and next you define which columns you want to retrieve data from with the columns parameter.

Result data extraction queries are ideal to answer this kind of questions:

Let's make the following query:
<% useCase.resultQueryQuestion %>


Count entities query

Now that we know the data was correctly inserted, we can move to the more analytical queries, such as count entities.

You should use count entities to know how many unique (distinct) entities you have in a particular table that satisfies the query conditions.

Count entities queries are ideal to answer this kind of questions:

Let's make the following query:
<% useCase.countEntitiesQuestion %>


Count events query

Counting entities is great, but what if we want to count events, like how many times a specific event happened within a certain period of time?

You should use count events query to know exactly that, the number of times some data was inserted for event columns.

Count event queries are ideal to answer this kind of questions:

Let's make the following query:
<% useCase.countEventsQuestion %>


Aggregation queries

Now it's time for the most powerful query type supported by SlicingDice, aggregations.

Aggregation is really powerful for generating insights from the data by calculating metrics, such as maximum, minimum, sum and average, as well as crossing data from different columns to generate pivot tables. If you have already used to relational databases, imagine the power of crossing data from different columns and tables without the performance hit of multiple JOIN operations.

Aggregation queries are ideal to answer this kind of questions:

SlicingDice support multiple sub-types of aggregation queries, such as: multi-level aggregation, metrics aggregation, filtered aggregation, date histogram aggregation and the combinations of all these queries together.

Single level aggregation

Let's start with a simple aggregation, like a single level query aggregation.

Let's make the following query:
<% useCase.singleLevelAggregationQuestion %>

Multi-level aggregation

Now let's move for a multi-level aggregation, that will basically take all the Top X values for the column A and cross it with all the available values of the column B, in order to find the final Top Z values and its quantity of entities.

Let's make the following query:
<% useCase.multiLevelAggregationQuestion %>

Filtered date histogram metrics aggregation

To finish, let's make a really powerful analytical query, that will use almost all types of aggregation queries supported by SlicingDice.

In this query below we will be using a filter and a metric on a date histogram aggregation. This basically means that, we will first filter the entities that we want to perform the aggregation on, then we will define the metric we want to see and finally for which period of time we want this metric to be calculated.

Let's make the following query:
<% useCase.filteredAggregationQuestion %>


Result data extraction with metrics

As a final example, let's imagine you want to retrieve again the data you stored on SlicingDice, but now also calculating some metrics for it. In order to do that, you can again use the result data extraction query as shown in this first example, but now with some additional parameters, that will allow you to perform calculations (metrics) while retrieving data.

Let's make the following query:
<% useCase.resultWithMetricsQuestion %>


Quick recap

Considering all the queries you ran so far, you are now prepared to make really powerful data analytics using SlicingDice.

Above you learned how to retrieve the original data you stored on SlicingDice using the result data extraction query, also applying some metrics for columns. You have also learned how to count entities, count events and aggregations.

There is also other type of queries supported by SlicingDice, such as top values, exists and total, but for a short quickstart guide you are really well covered.


Next steps

If you still want to read and play a bit more to consolidate the knowledge on how to insert and query data on SlicingDice, please check these two really cool dynamic tools we prepared:

If you want to review the data insertion and querying flows in a more detailed way, we recommend you to read the how to insert data and how to make queries pages.

If you are comfortable with what you just saw on this guide, you can now go deeper into the column data types, list of operators, predicates and parameters we support on SlicingDice.


Quickstart guide

This page will help you get started with SlicingDice very easy and quick.