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

Score extraction

Score data extraction query type.


A SlicingDice score data extraction query is almost identical to the result data extraction, except that it also returns the entity score according to the query conditions.

Query purpose

A SlicingDice score data extraction allows you to retrieve data while receiving the entities' relative importance given a set of conditions. For instance, you may want to get the email addresses of your users according to their purchase behavior and know the most important ones.

When using the score query, you select the entities that will be retrieved with the query parameter, exactly the same as a count entities query. Next, you define which columns you want to retrieve data from with the columns parameter.

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

  • What is the email and score of the users that accessed /sign-up or /buy-now more than 3 times in the last 7 days?
  • What is the name, email and the score of the users that opened new support-tickets between {% convert_date 'YYYY-MM-DDT00:00:00Z' '-15d' %} and {% convert_date 'YYYY-MM-DDT00:00:00Z' '-1d' %}?

Query endpoint

In order to make a score data extraction query, you simply need to send a POST request to https://api.slicingdice.com/v1/data_extraction/score with a single JSON object containing your query and columns you want to retrieve from SlicingDice.

Pro Tip

Remember that you can also use test databases to query before inserting real data to your production database.

Consider generating a free demo database key for yourself to use in all examples below, as indicated on the try before you buy page.


Query syntax and structure

The score endpoint expects a JSON object containing a single query element with a list of columns and conditions, as well as operators if applicable (just like on count entities queries). SlicingDice will only return data from the columns specified in the optional columns list. If columns is not present in the query, it will only return the existing entity IDs and their score value.

The optional limit parameter reduces the number of retrieved entities for any number. However, the page parameter is used when pagination applies. In this case, at most 1,024 entities will be returned for each page.

Suppose we have the following data stored on SlicingDice:

User
Gender
State
City
Age

user1

female

NY

New York

19

user2

female

CA

San Diego

31

user3

female

FL

Orlando

27

user4

male

WA

Seattle

22

user5

female

CA

Los Angeles

21

INSERT INTO default ([entity-id], gender, state, city, age) VALUES ("user1@slicingdice.com", "female", "NY", "New York", 19);
INSERT INTO default ([entity-id], gender, state, city, age) VALUES ("user2@slicingdice.com", "female", "CA", "San Diego", 31);
INSERT INTO default ([entity-id], gender, state, city, age) VALUES ("user3@slicingdice.com", "female", "FL", "Orlando", 27);
INSERT INTO default ([entity-id], gender, state, city, age) VALUES ("user4@slicingdice.com", "male", "WA", "Seattle", 22);
INSERT INTO default ([entity-id], gender, state, city, age) VALUES ("user5@slicingdice.com", "female", "CA", "Los Angeles", 21);
$ curl -X POST https://api.slicingdice.com/v1/sql \
    -H 'Authorization: MASTER_OR_WRITE_API_KEY' \
    -H 'Content-Type: application/sql' \
    -d 'INSERT INTO default ([entity-id], gender, state, city, age) VALUES ("user1@slicingdice.com", "female", "NY", "New York", 19); INSERT INTO default ([entity-id], gender, state, city, age) VALUES ("user2@slicingdice.com", "female", "CA", "San Diego", 31); INSERT INTO default ([entity-id], gender, state, city, age) VALUES ("user3@slicingdice.com", "female", "FL", "Orlando", 27); INSERT INTO default ([entity-id], gender, state, city, age) VALUES ("user4@slicingdice.com", "male", "WA", "Seattle", 22); INSERT INTO default ([entity-id], gender, state, city, age) VALUES ("user5@slicingdice.com", "female", "CA", "Los Angeles", 21);'
curl -X POST https://api.slicingdice.com/v1/insert \
    -H 'Authorization: MASTER_OR_WRITE_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
        "user1": {
            "gender": "female",
            "state": "NY",
            "city": "New York",
            "age": 19
        },
        "user2": {
            "gender": "female",
            "state": "CA",
            "city": "San Diego",
            "age": 31
        },
        "user3": {
            "gender": "female",
            "state": "FL",
            "city": "Orlando",
            "age": 27
        },
        "user4": {
            "gender": "male",
            "state": "WA",
            "city": "Seattle",
            "age": 22
        },
        "user5": {
            "gender": "female",
            "state": "CA",
            "city": "Los Angeles",
            "age": 21
        },
        "auto-create": ["dimension", "column"]
    }'
from pyslicer import SlicingDice
slicingdice = SlicingDice(master_key='MASTER_API_KEY')

insert_data = {
    "user4": {
        "gender": "male",
        "state": "WA",
        "age": 22,
        "city": "Seattle"
    },
    "user5": {
        "gender": "female",
        "state": "CA",
        "age": 21,
        "city": "Los Angeles"
    },
    "user2": {
        "gender": "female",
        "state": "CA",
        "age": 31,
        "city": "San Diego"
    },
    "user3": {
        "gender": "female",
        "state": "FL",
        "age": 27,
        "city": "Orlando"
    },
    "user1": {
        "gender": "female",
        "state": "NY",
        "age": 19,
        "city": "New York"
    },
    "auto-create": [
        "dimension", 
        "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");

        JSONObject insertData = new JSONObject()
        .put("user4", new JSONObject()
            .put("gender", "male")
            .put("state", "WA")
            .put("age", 22)
            .put("city", "Seattle"))
        .put("user5", new JSONObject()
            .put("gender", "female")
            .put("state", "CA")
            .put("age", 21)
            .put("city", "Los Angeles"))
        .put("user2", new JSONObject()
            .put("gender", "female")
            .put("state", "CA")
            .put("age", 31)
            .put("city", "San Diego"))
        .put("user3", new JSONObject()
            .put("gender", "female")
            .put("state", "FL")
            .put("age", 27)
            .put("city", "Orlando"))
        .put("user1", new JSONObject()
            .put("gender", "female")
            .put("state", "NY")
            .put("age", 19)
            .put("city", "New York"))
        .put("auto-create", new JSONArray()
            .put("dimension")
            .put("column"));

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

insert_data = {
    "user4" => {
        "gender" => "male",
        "state" => "WA",
        "age" => 22,
        "city" => "Seattle"
    },
    "user5" => {
        "gender" => "female",
        "state" => "CA",
        "age" => 21,
        "city" => "Los Angeles"
    },
    "user2" => {
        "gender" => "female",
        "state" => "CA",
        "age" => 31,
        "city" => "San Diego"
    },
    "user3" => {
        "gender" => "female",
        "state" => "FL",
        "age" => 27,
        "city" => "Orlando"
    },
    "user1" => {
        "gender" => "female",
        "state" => "NY",
        "age" => 19,
        "city" => "New York"
    },
    "auto-create" => [
        "dimension", 
        "column"
    ]
}

puts slicingdice.insert(insert_data)

const SlicingDice = require('slicerjs');

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

const insertData = {
    "user4": {
        "gender": "male",
        "state": "WA",
        "age": 22,
        "city": "Seattle"
    },
    "user5": {
        "gender": "female",
        "state": "CA",
        "age": 21,
        "city": "Los Angeles"
    },
    "user2": {
        "gender": "female",
        "state": "CA",
        "age": 31,
        "city": "San Diego"
    },
    "user3": {
        "gender": "female",
        "state": "FL",
        "age": 27,
        "city": "Orlando"
    },
    "user1": {
        "gender": "female",
        "state": "NY",
        "age": 19,
        "city": "New York"
    },
    "auto-create": [
        "dimension", 
        "column"
    ]
};

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

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

$insertData = array(
    "user4" => array(
        "gender" => "male",
        "state" => "WA",
        "age" => 22,
        "city" => "Seattle"
    ),
    "user5" => array(
        "gender" => "female",
        "state" => "CA",
        "age" => 21,
        "city" => "Los Angeles"
    ),
    "user2" => array(
        "gender" => "female",
        "state" => "CA",
        "age" => 31,
        "city" => "San Diego"
    ),
    "user3" => array(
        "gender" => "female",
        "state" => "FL",
        "age" => 27,
        "city" => "Orlando"
    ),
    "user1" => array(
        "gender" => "female",
        "state" => "NY",
        "age" => 19,
        "city" => "New York"
    ),
    "auto-create" => array(
        "dimension", 
        "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");

            var insertData = new Dictionary<string, dynamic>{
                {"user4", new Dictionary<string, dynamic>{
                    {"gender", "male"},
                    {"state", "WA"},
                    {"age", 22},
                    {"city", "Seattle"}
                }},
                {"user5", new Dictionary<string, dynamic>{
                    {"gender", "female"},
                    {"state", "CA"},
                    {"age", 21},
                    {"city", "Los Angeles"}
                }},
                {"user2", new Dictionary<string, dynamic>{
                    {"gender", "female"},
                    {"state", "CA"},
                    {"age", 31},
                    {"city", "San Diego"}
                }},
                {"user3", new Dictionary<string, dynamic>{
                    {"gender", "female"},
                    {"state", "FL"},
                    {"age", 27},
                    {"city", "Orlando"}
                }},
                {"user1", new Dictionary<string, dynamic>{
                    {"gender", "female"},
                    {"state", "NY"},
                    {"age", 19},
                    {"city", "New York"}
                }},
                {"auto-create", new List<dynamic>{
                    "dimension", 
                    "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)

    insertData := map[string]interface{}{
        "user4": map[string]interface{}{
            "gender": "male",
            "state": "WA",
            "age": 22,
            "city": "Seattle",
        },
        "user5": map[string]interface{}{
            "gender": "female",
            "state": "CA",
            "age": 21,
            "city": "Los Angeles",
        },
        "user2": map[string]interface{}{
            "gender": "female",
            "state": "CA",
            "age": 31,
            "city": "San Diego",
        },
        "user3": map[string]interface{}{
            "gender": "female",
            "state": "FL",
            "age": 27,
            "city": "Orlando",
        },
        "user1": map[string]interface{}{
            "gender": "female",
            "state": "NY",
            "age": 19,
            "city": "New York",
        },
        "auto-create": []interface{}{
            "dimension",
            "column",
        },
    }

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

In this query below we will retrieve only the city and state from users that are either from NY or CA, or male, or have between 18 and 25 years old.

SELECT city, state, score FROM default WHERE state = 'NY' or state = 'CA' or gender = 'male' or age BETWEEN 17 AND 25;
$ curl -X POST https://api.slicingdice.com/v1/sql \
    -H 'Authorization: MASTER_OR_WRITE_API_KEY' \
    -H 'Content-Type: application/sql' \
    -d 'SELECT city, state, score FROM default WHERE state = 'NY' or state = 'CA' or gender = 'male' or age BETWEEN 17 AND 25;'
 curl -X POST https://api.slicingdice.com/v1/data_extraction/score \
    -H 'Authorization: MASTER_OR_READ_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
        "query": [
            {
                "state": { "equals": "NY" }
            },
            "or",
            {
                "state": { "equals": "CA" }
            },
            "or",
            {
                "gender": { "equals": "male" }
            },
            "or",
            {
                "age": { "range": [ 18, 25 ] }
            }
        ],
        "columns": [
            "city",
            "state"
        ],
        "limit": 3
    }'
from pyslicer import SlicingDice
slicingdice = SlicingDice(master_key='MASTER_API_KEY')

query_data = {
    "query": [
        {
            "state": {
                "equals": "NY"
            }
        }, 
        "or", 
        {
            "state": {
                "equals": "CA"
            }
        }, 
        "or", 
        {
            "gender": {
                "equals": "male"
            }
        }, 
        "or", 
        {
            "age": {
                "range": [
                    18, 
                    25
                ]
            }
        }
    ],
    "limit": 3,
    "columns": [
        "city", 
        "state"
    ]
}

print(slicingdice.score(query_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");

        JSONObject queryData = new JSONObject()
        .put("query", new JSONArray()
            .put(new JSONObject()
                .put("state", new JSONObject()
                    .put("equals", "NY")))
            .put("or")
            .put(new JSONObject()
                .put("state", new JSONObject()
                    .put("equals", "CA")))
            .put("or")
            .put(new JSONObject()
                .put("gender", new JSONObject()
                    .put("equals", "male")))
            .put("or")
            .put(new JSONObject()
                .put("age", new JSONObject()
                    .put("range", new JSONArray()
                        .put(18)
                        .put(25)))))
        .put("limit", 3)
        .put("columns", new JSONArray()
            .put("city")
            .put("state"));
        JSONObject result = slicingdice.score(queryData);
        System.out.println(result.toString());
    }
}
require 'rbslicer'
slicingdice = SlicingDice.new(master_key: 'MASTER_API_KEY')

query_data = {
    "query" => [
        {
            "state" => {
                "equals" => "NY"
            }
        }, 
        "or", 
        {
            "state" => {
                "equals" => "CA"
            }
        }, 
        "or", 
        {
            "gender" => {
                "equals" => "male"
            }
        }, 
        "or", 
        {
            "age" => {
                "range" => [
                    18, 
                    25
                ]
            }
        }
    ],
    "limit" => 3,
    "columns" => [
        "city", 
        "state"
    ]
}

puts slicingdice.score(query_data)

const SlicingDice = require('slicerjs');

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

const queryData = {
    "query": [
        {
            "state": {
                "equals": "NY"
            }
        }, 
        "or", 
        {
            "state": {
                "equals": "CA"
            }
        }, 
        "or", 
        {
            "gender": {
                "equals": "male"
            }
        }, 
        "or", 
        {
            "age": {
                "range": [
                    18, 
                    25
                ]
            }
        }
    ],
    "limit": 3,
    "columns": [
        "city", 
        "state"
    ]
};

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

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

$queryData = array(
    "query" => array(
        array(
            "state" => array(
                "equals" => "NY"
            )
        ), 
        "or", 
        array(
            "state" => array(
                "equals" => "CA"
            )
        ), 
        "or", 
        array(
            "gender" => array(
                "equals" => "male"
            )
        ), 
        "or", 
        array(
            "age" => array(
                "range" => array(
                    18, 
                    25
                )
            )
        )
    ),
    "limit" => 3,
    "columns" => array(
        "city", 
        "state"
    )
);

print_r($slicingdice->score($queryData));
?>
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");

            var queryData = new Dictionary<string, dynamic>{
                {"query", new List<dynamic>{
                    new Dictionary<string, dynamic>{
                        {"state", new Dictionary<string, dynamic>{
                            {"equals", "NY"}
                        }}
                    }, 
                    "or", 
                    new Dictionary<string, dynamic>{
                        {"state", new Dictionary<string, dynamic>{
                            {"equals", "CA"}
                        }}
                    }, 
                    "or", 
                    new Dictionary<string, dynamic>{
                        {"gender", new Dictionary<string, dynamic>{
                            {"equals", "male"}
                        }}
                    }, 
                    "or", 
                    new Dictionary<string, dynamic>{
                        {"age", new Dictionary<string, dynamic>{
                            {"range", new List<dynamic>{
                                18, 
                                25
                            }}
                        }}
                    }
                }},
                {"limit", 3},
                {"columns", new List<dynamic>{
                    "city", 
                    "state"
                }}
            };

            var result = slicingdice.Score(queryData);
            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)

    queryData := map[string]interface{}{
        "query": []interface{}{
            map[string]interface{}{
                "state": map[string]interface{}{
                    "equals": "NY",
                },
            },
            "or",
            map[string]interface{}{
                "state": map[string]interface{}{
                    "equals": "CA",
                },
            },
            "or",
            map[string]interface{}{
                "gender": map[string]interface{}{
                    "equals": "male",
                },
            },
            "or",
            map[string]interface{}{
                "age": map[string]interface{}{
                    "range": []interface{}{
                        18,
                        25,
                    },
                },
            },
        },
        "limit": 3,
        "columns": []interface{}{
            "city",
            "state",
        },
    }

    fmt.Println(slicingdice.Result(Score))
}

The API response for this query above will be in the format below:

{
    "status": "success",
    "data": {
        "user1": {
            "city": "New York",
            "state": "NY",
            "score": 2
            // +1 for living in NY
            // +1 for being in the age range
        },
        "user2": {
            "city": "San Diego",
            "state": "CA",
            "score": 1
            // +1 for living in CA
        },
        "user4": {
            "city": "Seattle"
            "state": "WA",
            "score": 3
            // +1 for living in WA
            // +1 for being male
            // +1 for being in the age range
        },
        "user5": {
            "city": "Los Angeles",
            "state": "CA",
            "score": 2
            // +1 for living in CA
            // +1 for being in the age range
        }
    },
    "page": 1,
    "next-page": null,
    "took": 0.093
}

Let's understand each component of the API response:

  • status - Indicating whether the request was successfully processed or not.
  • data - Retrieved data as inserted.
  • page - Current retrieved page - only applies when more than 1,024 entities were retrieved.
  • next-page - Next page for retrieval - only applies when more than 1,024 entities were retrieved.
  • page-token - Token to retrieve the next page - only applies when more than 1,024 entities were retrieved.
  • took - Time spent processing this request, in seconds.

Retrieving all the data

If you simply want to see all the data you have stored without filtering out any entities or choosing which columns you want on the score you can use the query types and parameters listed below.

Retrieving all entities

To retrieve all the entities you don't need to specify the query parameter on your json, the SlicingDice will automatically get all the entities for you.

Score total has a limit of 100 entities

To optimize the all entities operation, SlicingDice limits the total result to 100 entities. You still can specify the limit, but it should be lower than or equal to 100.

SELECT city, state, score FROM default;
$ curl -X POST https://api.slicingdice.com/v1/sql \
    -H 'Authorization: MASTER_OR_WRITE_API_KEY' \
    -H 'Content-Type: application/sql' \
    -d 'SELECT city, state, score FROM default;'
 curl -X POST https://api.slicingdice.com/v1/data_extraction/score \
    -H 'Authorization: MASTER_OR_READ_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
        "columns": [
            "city",
            "state"
        ]
    }'
from pyslicer import SlicingDice
slicingdice = SlicingDice(master_key='MASTER_API_KEY')

query_data = {
    "columns": [
        "city", 
        "state"
    ]
}

print(slicingdice.score(query_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");

        JSONObject queryData = new JSONObject()
        .put("columns", new JSONArray()
            .put("city")
            .put("state"));
        JSONObject result = slicingdice.score(queryData);
        System.out.println(result.toString());
    }
}
require 'rbslicer'
slicingdice = SlicingDice.new(master_key: 'MASTER_API_KEY')

query_data = {
    "columns" => [
        "city", 
        "state"
    ]
}

puts slicingdice.score(query_data)

const SlicingDice = require('slicerjs');

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

const queryData = {
    "columns": [
        "city", 
        "state"
    ]
};

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

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

$queryData = array(
    "columns" => array(
        "city", 
        "state"
    )
);

print_r($slicingdice->score($queryData));
?>
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");

            var queryData = new Dictionary<string, dynamic>{
                {"columns", new List<dynamic>{
                    "city", 
                    "state"
                }}
            };

            var result = slicingdice.Score(queryData);
            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)

    queryData := map[string]interface{}{
        "columns": []interface{}{
            "city",
            "state",
        },
    }

    fmt.Println(slicingdice.Result(Score))
}

Retrieving all columns

To retrieve all the columns you simply need to specify the value all on the columns parameter, with this parameter SlicingDice will automatically retrieve all the columns (except the event columns) on your data extraction score.

SELECT * FROM default WHERE state = 'NY' OR state = 'CA';
$ curl -X POST https://api.slicingdice.com/v1/sql \
    -H 'Authorization: MASTER_OR_WRITE_API_KEY' \
    -H 'Content-Type: application/sql' \
    -d 'SELECT * FROM default WHERE state = 'NY' OR state = 'CA';'
 curl -X POST https://api.slicingdice.com/v1/data_extraction/score \
    -H 'Authorization: MASTER_OR_READ_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
        "query": [
            {
                "state": { "equals": "NY" }
            },
            "or",
            {
                "state": { "equals": "CA" }
            }
        ],
        "columns": "all",
        "limit": 3
    }'
from pyslicer import SlicingDice
slicingdice = SlicingDice(master_key='MASTER_API_KEY')

query_data = {
    "query": [
        {
            "state": {
                "equals": "NY"
            }
        }, 
        "or", 
        {
            "state": {
                "equals": "CA"
            }
        }
    ],
    "limit": 3,
    "columns": "all"
}

print(slicingdice.score(query_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");

        JSONObject queryData = new JSONObject()
        .put("query", new JSONArray()
            .put(new JSONObject()
                .put("state", new JSONObject()
                    .put("equals", "NY")))
            .put("or")
            .put(new JSONObject()
                .put("state", new JSONObject()
                    .put("equals", "CA"))))
        .put("limit", 3)
        .put("columns", "all");
        JSONObject result = slicingdice.score(queryData);
        System.out.println(result.toString());
    }
}
require 'rbslicer'
slicingdice = SlicingDice.new(master_key: 'MASTER_API_KEY')

query_data = {
    "query" => [
        {
            "state" => {
                "equals" => "NY"
            }
        }, 
        "or", 
        {
            "state" => {
                "equals" => "CA"
            }
        }
    ],
    "limit" => 3,
    "columns" => "all"
}

puts slicingdice.score(query_data)

const SlicingDice = require('slicerjs');

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

const queryData = {
    "query": [
        {
            "state": {
                "equals": "NY"
            }
        }, 
        "or", 
        {
            "state": {
                "equals": "CA"
            }
        }
    ],
    "limit": 3,
    "columns": "all"
};

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

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

$queryData = array(
    "query" => array(
        array(
            "state" => array(
                "equals" => "NY"
            )
        ), 
        "or", 
        array(
            "state" => array(
                "equals" => "CA"
            )
        )
    ),
    "limit" => 3,
    "columns" => "all"
);

print_r($slicingdice->score($queryData));
?>
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");

            var queryData = new Dictionary<string, dynamic>{
                {"query", new List<dynamic>{
                    new Dictionary<string, dynamic>{
                        {"state", new Dictionary<string, dynamic>{
                            {"equals", "NY"}
                        }}
                    }, 
                    "or", 
                    new Dictionary<string, dynamic>{
                        {"state", new Dictionary<string, dynamic>{
                            {"equals", "CA"}
                        }}
                    }
                }},
                {"limit", 3},
                {"columns", "all"}
            };

            var result = slicingdice.Score(queryData);
            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)

    queryData := map[string]interface{}{
        "query": []interface{}{
            map[string]interface{}{
                "state": map[string]interface{}{
                    "equals": "NY",
                },
            },
            "or",
            map[string]interface{}{
                "state": map[string]interface{}{
                    "equals": "CA",
                },
            },
        },
        "limit": 3,
        "columns": "all",
    }

    fmt.Println(slicingdice.Result(Score))
}

Retrieving all entities with all columns

You can use this two techniques above together so you will be able to retrieve all the entities and all the columns at the same time.

SELECT * FROM default;
$ curl -X POST https://api.slicingdice.com/v1/sql \
    -H 'Authorization: MASTER_OR_WRITE_API_KEY' \
    -H 'Content-Type: application/sql' \
    -d 'SELECT * FROM default;'
curl -X POST https://api.slicingdice.com/v1/data_extraction/score \
    -H 'Authorization: MASTER_OR_READ_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
        "columns": "all"
    }'
from pyslicer import SlicingDice
slicingdice = SlicingDice(master_key='MASTER_API_KEY')

query_data = {
    "columns": "all"
}

print(slicingdice.score(query_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");

        JSONObject queryData = new JSONObject()
        .put("columns", "all");
        JSONObject result = slicingdice.score(queryData);
        System.out.println(result.toString());
    }
}
require 'rbslicer'
slicingdice = SlicingDice.new(master_key: 'MASTER_API_KEY')

query_data = {
    "columns" => "all"
}

puts slicingdice.score(query_data)

const SlicingDice = require('slicerjs');

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

const queryData = {
    "columns": "all"
};

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

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

$queryData = array(
    "columns" => "all"
);

print_r($slicingdice->score($queryData));
?>
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");

            var queryData = new Dictionary<string, dynamic>{
                {"columns", "all"}
            };

            var result = slicingdice.Score(queryData);
            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)

    queryData := map[string]interface{}{
        "columns": "all",
    }

    fmt.Println(slicingdice.Result(Score))
}

Retrieving metrics

You're able to ask SlicingDice for some metrics about your entities on data extraction score queries, imagine that you want to know the average of clicks per user on your system, you can do that simply passing average metric on columns parameter, as you can see on the example below.

SELECT city, state, AVG([clicks.value]), score FROM default WHERE (state = 'NY' OR state = 'CA') AND [clicks.date] BETWEEN '{% convert_date 'YYYY-MM-DDT00:00:00Z' '-5d' %}' AND '{% convert_date 'YYYY-MM-DDT00:00:00Z' '-1d' %}';
$ curl -X POST https://api.slicingdice.com/v1/sql \
    -H 'Authorization: MASTER_OR_WRITE_API_KEY' \
    -H 'Content-Type: application/sql' \
    -d 'SELECT city, state, AVG([clicks.value]), score FROM default WHERE (state = 'NY' OR state = 'CA') AND [clicks.date] BETWEEN '{% convert_date 'YYYY-MM-DDT00:00:00Z' '-5d' %}' AND '{% convert_date 'YYYY-MM-DDT00:00:00Z' '-1d' %}';'
 curl -X POST https://api.slicingdice.com/v1/data_extraction/score \
    -H 'Authorization: MASTER_OR_READ_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
        "query": [
            {
                "state": { "equals": "NY" }
            },
            "or",
            {
                "state": { "equals": "CA" }
            }
        ],
        "columns": [
            "city",
            "state",
            {
            	"avg": "clicks",
            	"between": ["-5 days", "now"]
            }
        ],
        "limit": 3
    }'
from pyslicer import SlicingDice
slicingdice = SlicingDice(master_key='MASTER_API_KEY')

query_data = {
    "query": [
        {
            "state": {
                "equals": "NY"
            }
        }, 
        "or", 
        {
            "state": {
                "equals": "CA"
            }
        }
    ],
    "limit": 3,
    "columns": [
        "city", 
        "state", 
        {
            "avg": "clicks",
            "between": [
                "-5 days", 
                "now"
            ]
        }
    ]
}

print(slicingdice.score(query_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");

        JSONObject queryData = new JSONObject()
        .put("query", new JSONArray()
            .put(new JSONObject()
                .put("state", new JSONObject()
                    .put("equals", "NY")))
            .put("or")
            .put(new JSONObject()
                .put("state", new JSONObject()
                    .put("equals", "CA"))))
        .put("limit", 3)
        .put("columns", new JSONArray()
            .put("city")
            .put("state")
            .put(new JSONObject()
                .put("avg", "clicks")
                .put("between", new JSONArray()
                    .put("-5 days")
                    .put("now"))));
        JSONObject result = slicingdice.score(queryData);
        System.out.println(result.toString());
    }
}
require 'rbslicer'
slicingdice = SlicingDice.new(master_key: 'MASTER_API_KEY')

query_data = {
    "query" => [
        {
            "state" => {
                "equals" => "NY"
            }
        }, 
        "or", 
        {
            "state" => {
                "equals" => "CA"
            }
        }
    ],
    "limit" => 3,
    "columns" => [
        "city", 
        "state", 
        {
            "avg" => "clicks",
            "between" => [
                "-5 days", 
                "now"
            ]
        }
    ]
}

puts slicingdice.score(query_data)

const SlicingDice = require('slicerjs');

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

const queryData = {
    "query": [
        {
            "state": {
                "equals": "NY"
            }
        }, 
        "or", 
        {
            "state": {
                "equals": "CA"
            }
        }
    ],
    "limit": 3,
    "columns": [
        "city", 
        "state", 
        {
            "avg": "clicks",
            "between": [
                "-5 days", 
                "now"
            ]
        }
    ]
};

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

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

$queryData = array(
    "query" => array(
        array(
            "state" => array(
                "equals" => "NY"
            )
        ), 
        "or", 
        array(
            "state" => array(
                "equals" => "CA"
            )
        )
    ),
    "limit" => 3,
    "columns" => array(
        "city", 
        "state", 
        array(
            "avg" => "clicks",
            "between" => array(
                "-5 days", 
                "now"
            )
        )
    )
);

print_r($slicingdice->score($queryData));
?>
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");

            var queryData = new Dictionary<string, dynamic>{
                {"query", new List<dynamic>{
                    new Dictionary<string, dynamic>{
                        {"state", new Dictionary<string, dynamic>{
                            {"equals", "NY"}
                        }}
                    }, 
                    "or", 
                    new Dictionary<string, dynamic>{
                        {"state", new Dictionary<string, dynamic>{
                            {"equals", "CA"}
                        }}
                    }
                }},
                {"limit", 3},
                {"columns", new List<dynamic>{
                    "city", 
                    "state", 
                    new Dictionary<string, dynamic>{
                        {"avg", "clicks"},
                        {"between", new List<dynamic>{
                            "-5 days", 
                            "now"
                        }}
                    }
                }}
            };

            var result = slicingdice.Score(queryData);
            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)

    queryData := map[string]interface{}{
        "query": []interface{}{
            map[string]interface{}{
                "state": map[string]interface{}{
                    "equals": "NY",
                },
            },
            "or",
            map[string]interface{}{
                "state": map[string]interface{}{
                    "equals": "CA",
                },
            },
        },
        "limit": 3,
        "columns": []interface{}{
            "city",
            "state",
            map[string]interface{}{
                "avg": "clicks",
                "between": []interface{}{
                    "-5 days",
                    "now",
                },
            },
        },
    }

    fmt.Println(slicingdice.Result(Score))
}

You can see more details about this on columns query parameters section.


Query operators, predicates and parameters

This section is focused on API-based JSON endpoint if you're using SQL to make your queries feel free to skip this part.

Supported operators

This is the list of supported operators to be used exclusively in the query part of the score data extraction query. As you can see, the list of operators is the same supported for the count-entities query type.

and

Usage example: Filter all entities that have the name equal to "Jeff" and age equal to 18.

or

Usage example: Filter all entities that have the name equal to "Jeff" or age equal to 18.

not

Usage example: Filter all entities that name equal to "Jeff" by age not equal to 18.

freqgroup

Usage example: Filter all entities that have the purchased on "NY" or on "CA" at least two times when summing up both occurrences.

Note that minfreq parameter is required to define a minimum frequency when evaluating the summed up frequencies.

Supported parameters

This is the list of supported parameters for the score data extraction query.

columns (optional)

Define which columns must be retrieved in the query. If not present, the query only returns entity IDs.

If "columns": "all" all the columns will be retrieved.

limit (optional)

Define the maximum number of entities that can be retrieved.

page-token (optional)

Fetch the next page of scores when pagination occurred.

order (optional)

Order values by ascending or descending order.

Supported metrics predicates

The list below contains all the supported metrics predicates that can be applied for the following data types while retrieving its values:

1 . Requires the use of between predicate.

min

Answers the question: What is the minimum stored value in the age column?

max

Answers the question: What is the maximum stored value in the age column?

sum

Answers the question: What is the sum of all stored values in the purchases column?

avg

Answers the question: What is the average of all stored values in the age column?

between

Selects only data stored within given between time range

Note that this predicate is required for all event column.

Supported query predicates

The list below contains all the supported predicates that can be used in the query part of the score data extraction query.

equals

Usage example: How many entities have the column name equals to Jeff?

not-equals

Usage example: How many entities have the column name not-equals to Jeff?

range

Usage example: How many entities have the column age in the range from 0 to 18?

Note that range includes the beginning but not the ending in the scores.

gt or greater-than

Usage example: How many entities have the column age greater than 50?"

gte or greater-than-or-equal

Usage example: How many entities have the column age greater than or equal to 18?".

lt or less-than

Usage example: How many entities have the column age less than 50?"

lte or less-than-or-equal

Usage example: How many entities have the column age less than or equal to 21?".

starts-with

Selects only values that start with the requested substring.

Usage example: What users have a name that starts with j?

ends-with

Selects only values that end with the requested substring.

Usage example: What products have a name that ends with ona?

contains

Selects only values that contain the requested substring.

Usage example: What countries contain m?

not-contains

Selects only values that do not contain the requested substring.

Usage example: What countries not contains m?

between

Usage example: How many entities have the column clicks equal to "pay now" between the dates {% convert_date 'YYYY-MM-DDT00:00:00Z' '-15d' %} and {% convert_date 'YYYY-MM-DDT00:00:00Z' '-1d' %}?

Note that this predicate is required for all event column. In count queries, it must be used with the equals predicate. between includes both the beginning and the ending in the scores.

minfreq

Usage example: How many entities have the column clicks equal to "pay now" at least 2 times between the dates {% convert_date 'YYYY-MM-DDT00:00:00Z' '-15d' %} and {% convert_date 'YYYY-MM-DDT00:00:00Z' '-1d' %}?

Note that the minfreq parameter must be used with the equals and between parameters in the same query.

bypass-cache (optional)

Boolean value defining to bypass or not the cache mechanism. Use "bypass-cache": true to ignore cached data. bypass-cache is false by default, meaning that all queries will be cached.

dimension (optional)

In which the query should be performed over.

If you do not provide a value to dimension, the query will be performed over the default dimension.


Query examples

You can check the Score query examples to see a lot of score queries examples


What's Next

Pagination