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

Saved queries


This section will explain only JSON particularities if you're using a SQL Driver you can skip this guide.

Saved queries are here to help you re-using those queries that you repeat over and over again. Instead of re-writing the entire query whenever you need to analyze your data, save it and call by name.

SQL Drivers

Currently, saved queries are not supported on our SQL Drivers.

Saving a query

In order to save a query, generate a POST request to https://api.slicingdice.com/v1/query/saved containing a name, its type and the query itself. Since the name will be used in the query URL, only alphanumeric a-zA-Z0-9 and - characters are allowed.

The type parameter accepts the following values determining to which query will be executed:

Request for saving a query

 curl -X POST https://api.slicingdice.com/v1/query/saved \
    -H 'Authorization: MASTER_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
        "name": "my-saved-query",
        "type": "count/entity",
        "query": [
            {
                "state": {
                    "equals": "NY"
                }
            },
            "or",
            {
                "state": {
                    "equals": "CA"
                }
            }
        ],
        "dimension": "users"
    }'
from pyslicer import SlicingDice
slicingdice = SlicingDice(master_key='MASTER_API_KEY')

query_data = {
    "query": [
        {
            "state": {
                "equals": "NY"
            }
        }, 
        "or", 
        {
            "state": {
                "equals": "CA"
            }
        }
    ],
    "type": "count/entity",
    "name": "my-saved-query",
    "dimension": "users"
}

print(slicingdice.create_saved_query(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("type", "count/entity")
        .put("name", "my-saved-query")
        .put("dimension", "users");
        JSONObject result = slicingdice.createSavedQuery(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"
            }
        }
    ],
    "type" => "count/entity",
    "name" => "my-saved-query",
    "dimension" => "users"
}

puts slicingdice.create_saved_query(query_data)

const SlicingDice = require('slicerjs');

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

const queryData = {
    "query": [
        {
            "state": {
                "equals": "NY"
            }
        }, 
        "or", 
        {
            "state": {
                "equals": "CA"
            }
        }
    ],
    "type": "count/entity",
    "name": "my-saved-query",
    "dimension": "users"
};

slicingdice.createSavedQuery(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"
            )
        )
    ),
    "type" => "count/entity",
    "name" => "my-saved-query",
    "dimension" => "users"
);

print_r($slicingdice->createSavedQuery($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"}
                        }}
                    }
                }},
                {"type", "count/entity"},
                {"name", "my-saved-query"},
                {"dimension", "users"}
            };

            var result = slicingdice.CreateSavedQuery(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",
                },
            },
        },
        "type": "count/entity",
        "name": "my-saved-query",
        "dimension": "users",
    }

    fmt.Println(slicingdice.CreateSavedQuery(queryData))
}

After making this request above, the API response will be in the format below:

{
    "status": "success",
    "name": "my-saved-query",
    "type": "count/entity",
    "query": [
        {
            "state": {
                "equals": "ny"
            }
        },
        "or",
        {
            "state": {
                "equals": "ca"
            }
        }
    ],
    "dimension": "users",
    "cache-period": 60,
    "took": 0.17
}

Let's understand each component of the API response:

  • status - Indicating whether the request was successfully processed or not.
  • name - Name of the query you saved.
  • type - Type of the query you saved.
  • query - Query you saved.
  • took - Time spent processing this request, in seconds.

Listing saved queries

Great, query is now saved. We can check all our saved queries with a simple GET request to https://api.slicingdice.com/v1/query/saved like this example below.

 curl -X GET https://api.slicingdice.com/v1/query/saved \
    -H 'Authorization: MASTER_OR_READ_API_KEY' \
    -H 'Content-Type: application/json'
from pyslicer import SlicingDice
slicingdice = SlicingDice(master_key='MASTER_API_KEY')

print(slicingdice.get_saved_queries())

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 result = slicingdice.getSavedQueries();
        System.out.println(result.toString());
    }
}
require 'rbslicer'
slicingdice = SlicingDice.new(master_key: 'MASTER_API_KEY')

puts slicingdice.get_saved_queries()

const SlicingDice = require('slicerjs');

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

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

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

print_r($slicingdice->getSavedQueries());
?>
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 result = slicingdice.GetSavedQueries();
            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)

    fmt.Println(slicingdice.GetSavedQueries())
}

After making this request above, the API response will be in the format below:

{
    "status": "success",
    "saved-queries": [
        {
            "name": "my-saved-query",
            "type": "count/entity",
            "query": [
                {
                    "state": {
                        "equals": "ny"
                    }
                },
                "or",
                {
                    "state": {
                        "equals": "ca"
                    }
                }
            ],
            "cache-period": 60,
            "dimension": "users"
        }
    ],
    "took": 0.029
}

Using a saved query

Now that we have a saved query, let's use it. In order to achieve this, issue a GET request to https://api.slicingdice.com/v1/query/saved/:query_name, where :query_name must be replaced by the name given to the query on its creation.

 curl -X GET https://api.slicingdice.com/v1/query/saved/my-saved-query \
    -H 'Authorization: MASTER_OR_READ_API_KEY' \
    -H 'Content-Type: application/json'
from pyslicer import SlicingDice
slicingdice = SlicingDice(master_key='MASTER_API_KEY')

print(slicingdice.get_saved_query("my-saved-query"))
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 result = slicingdice.getSavedQuery("my-saved-query");
        System.out.println(result.toString());
    }
}
require 'rbslicer'
slicingdice = SlicingDice.new(master_key: 'MASTER_API_KEY')

puts slicingdice.get_saved_query("my-saved-query")
const SlicingDice = require('slicerjs');

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

slicingdice.getSavedQueries("my-saved-query").then((resp) => {
    console.log(resp);
}, (err) => {
    console.error(err);
});

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

print_r($slicingdice->getSavedQuery("my-saved-query"));
?>
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 result = slicingdice.GetSavedQuery("my-saved-query");
            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)

    fmt.Println(slicingdice.GetSavedQuery("my-saved-query"))
}

After making this request above, the API response will be in the format below:

{
    "status": "success",
    "type": "count/entity",
    "query": [
        {
            "state": {
                "equals": "ny"
            }
        },
        "or",
        {
            "state": {
                "equals": "ca"
            }
        }
    ],
    "dimension": "users",
    "result": 42,
    "took": 0.151
}

As you can see, this works quite similar to regular queries. You may have noticed that query shows the executed query for the given results. This way, you can easily debug your saved queries.


Updating a saved query

Now, what to do if you notice your saved query has a mistake? Don't worry. You can always update a saved query by issuing a PUT request to the query endpoint https://api.slicingdice.com/v1/query/saved/:query_name. Nevertheless you cannot change its name.

 curl -X PUT https://api.slicingdice.com/v1/query/saved/my-saved-query \
    -H 'Authorization: MASTER_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
        "type": "count/entity",
        "query": [
            {
                "state": {
                    "equals": "NY"
                }
            },
            "or",
            {
                "state": {
                    "equals": "CA"
                }
            }
        ],
        "dimension": "users"
    }'
from pyslicer import SlicingDice
slicingdice = SlicingDice(master_key='MASTER_API_KEY')

query_data = {
    "query": [
        {
            "state": {
                "equals": "NY"
            }
        }, 
        "or", 
        {
            "state": {
                "equals": "CA"
            }
        }
    ],
    "type": "count/entity",
    "dimension": "users"
}

print(slicingdice.update_saved_query("my-saved-query", 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("type", "count/entity")
        .put("dimension", "users");
      
        JSONObject result = slicingdice.updateSavedQuery("my-saved-query", 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"
            }
        }
    ],
    "type" => "count/entity",
    "dimension" => "users"
}

puts slicingdice.update_saved_query("my-saved-query", query_data)

const SlicingDice = require('slicerjs');

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

const queryData = {
    "query": [
        {
            "state": {
                "equals": "NY"
            }
        }, 
        "or", 
        {
            "state": {
                "equals": "CA"
            }
        }
    ],
    "type": "count/entity",
    "dimension": "users"
};

slicingdice.updateSavedQuery("my-saved-query", 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"
            )
        )
    ),
    "type" => "count/entity",
    "dimension" => "users"
);

print_r($slicingdice->updateSavedQuery("my-saved-query", $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"}
                        }}
                    }
                }},
                {"type", "count/entity"},
                {"dimension", "users"}
            };

            var result = slicingdice.UpdateSavedQuery("my-saved-query", 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",
                },
            },
        },
        "type": "count/entity",
        "dimension": "users",
    }

    fmt.Println(slicingdice.UpdateSavedQuery("my-saved-query", queryData))
}

After making this request above, the API response will be in the format below:

{
    "status": "success",
    "type": "count/entity",
    "query": [
        {
            "state": {
                "equals": "ny"
            }
        },
        "or",
        {
            "state": {
                "equals": "ca"
            }
        }
    ],
    "cache-period": 60,
    "took": 0.169
}

Deleting a saved query

Finally, say you only wanted to use a saved query for a while and, now, it isn't necessary anymore. In this case, you can delete it by issuing a DELETE request.

 curl -X DELETE https://api.slicingdice.com/v1/query/saved/my-saved-query \
    -H 'Authorization: MASTER_API_KEY' \
    -H 'Content-Type: application/json'
from pyslicer import SlicingDice
slicingdice = SlicingDice(master_key='MASTER_API_KEY')

print(slicingdice.delete_saved_query("my-saved-query"))
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 result = slicingdice.deleteSavedQuery("my-saved-query");
        System.out.println(result.toString());
    }
}
require 'rbslicer'
slicingdice = SlicingDice.new(master_key: 'MASTER_API_KEY')

puts slicingdice.delete_saved_query("my-saved-query")
const SlicingDice = require('slicerjs');

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

slicingdice.deleteSavedQuery("my-saved-query").then((resp) => {
    console.log(resp);
}, (err) => {
    console.error(err);
});
<?php
use Slicer\SlicingDice;
$slicingdice = new SlicingDice(array("masterKey" => "MASTER_API_KEY"));

print_r($slicingdice->deleteSavedQuery("my-saved-query"));
?>
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 result = slicingdice.DeleteSavedQuery("my-saved-query");
            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)

    fmt.Println(slicingdice.DeleteSavedQuery("my-saved-query"))
}

After making this request above, the API response will be in the format below:

{
    "status": "success",
    "took": 0.06,
    "cache-period": 60,
    "deleted-query": "my-saved-query",
    "query": [
        {
            "state": {
                "equals": "ny"
            }
        },
        "or",
        {
            "state": {
                "equals": "ca"
            }
        }
    ],
    "type": "count\/entity"
}

Saved queries