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

Top values


A SlicingDice top values query is equivalent to a SQL query like this:

SELECT TableName.ColumnName, 
       COUNT(*) 
FROM   TableName 
WHERE  TableName.ColumnName LIKE '%string%' 
GROUP  BY TableName.ColumnName 
ORDER  BY COUNT(*) DESC; 

Query purpose

You should use top values to know what are the most common values for a specific column and how many times was the value inserted.

All values are returned as strings by this query. This allows you to use predicates such as starts-with, ends-with, contains and not-contains and get top values based on substrings even for numeric columns.

For instance, contains has a behavior similar to SQL LIKE. It takes into account only the entities whose column value has at least one of the contains elements as a substring. An entity with "blog-title": "my personal blog" will be taken into account for "contains": ["person"].

Top values are ideal to answer this kind of questions:

  • What are the most common values for the column name?
  • What are the most common values for the column name that start with san?
  • What are the most common values for the column name that contain fran?
  • What are the most common values for the column name that do not contain cisco?

Query endpoint

In order to make a top values query, you simply need to send a POST request to https://api.slicingdice.com/v1/query/top_values with a single JSON object of queries identified by unique names as keys, each containing a column and a condition.

Pro Tip

Remember that you can also use a test database 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

In this query below we will list what are the top 3 most common values for the column name, where the values contains the string eff on dimension users.

SELECT name FROM users WHERE name LIKE '%eff%' GROUP by name LIMIT 3;
$ curl -X POST https://api.slicingdice.com/v1/sql \
    -H 'Authorization: MASTER_OR_WRITE_API_KEY' \
    -H 'Content-Type: application/sql' \
    -d 'SELECT name FROM users WHERE name LIKE '%eff%' GROUP by name LIMIT 3;'
 curl -X POST https://api.slicingdice.com/v1/query/top_values \
    -H 'Authorization: MASTER_OR_READ_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
        "name-contains-eff": {
            "name": 3,
            "contains": [
                "eff"
            ],
            "dimension": "users"
        }
    }'
from pyslicer import SlicingDice
slicingdice = SlicingDice(master_key='MASTER_API_KEY')

query_data = {
    "name-contains-eff": {
        "dimension": "users",
        "contains": [
            "eff"
        ],
        "name": 3
    }
}

print(slicingdice.top_values(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("name-contains-eff", new JSONObject()
            .put("dimension", "users")
            .put("contains", new JSONArray()
                .put("eff"))
            .put("name", 3));
        JSONObject result = slicingdice.topValues(queryData);
        System.out.println(result.toString());
    }
}
require 'rbslicer'
slicingdice = SlicingDice.new(master_key: 'MASTER_API_KEY')

query_data = {
    "name-contains-eff" => {
        "dimension" => "users",
        "contains" => [
            "eff"
        ],
        "name" => 3
    }
}

puts slicingdice.top_values(query_data)

const SlicingDice = require('slicerjs');

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

const queryData = {
    "name-contains-eff": {
        "dimension": "users",
        "contains": [
            "eff"
        ],
        "name": 3
    }
};

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

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

$queryData = array(
    "name-contains-eff" => array(
        "dimension" => "users",
        "contains" => array(
            "eff"
        ),
        "name" => 3
    )
);

print_r($slicingdice->topValues($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>{
                {"name-contains-eff", new Dictionary<string, dynamic>{
                    {"dimension", "users"},
                    {"contains", new List<dynamic>{
                        "eff"
                    }},
                    {"name", 3}
                }}
            };

            var result = slicingdice.TopValues(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{}{
        "name-contains-eff": map[string]interface{}{
            "dimension": "users",
            "contains": []interface{}{
                "eff",
            },
            "name": 3,
        },
    }

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

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

{
    "status": "success",
    "result": {
        "name-contains-eff": {
            "name": [
                {
                    "value": "jeff",
                    "quantity": 5
                }, {
                    "value": "geffrey",
                    "quantity": 3
                }, {
                    "value": "effen",
                    "quantity": 1
                }
            ]
        }
    },
    "took": 0.103
}

Let's understand each component of the API response:

  • status - Indicating whether the request was successfully processed or not.
  • result - JSON Object mapping <query-name> to its results
    • <query-name> - JSON Object containing results of <query-name>
      • quantity - Number of occurrences of the value.
      • value - Value stored on SlicingDice.
  • took - Time spent processing this request, in seconds.

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

The top values query has no support for operators, just for predicate, that are listed below.

Supported predicates

This is the list of supported predicates for the top values query.

starts-with

Selects only values that starts with at least one of the substrings given by starts-with.

Usage example: What are the top values in the name column that starts-with eff?

ends-with

Selects only values that ends with at least one of the substrings given by ends-with.

Usage example: What are the top values in the name column that ends-with eff?

contains

Selects only values that contains at least one of the substrings given by contains.

Usage example: What are the top values in the name column that contains eff?

not-contains

Selects only values that do not contain at least one of the substrings given by not-contains.

Usage example: What are the top values in the name column that not-contains eff?

equals

Selects only values that are equal to one of the substrings given by starts-with.

Usage example: Was the value eff inserted in the name column and what is the quantity?

not-equals

Selects only values that are not equal to any of the substrings given by starts-with.

Usage example: What are the top values in the name column that is not-equals to eff?

bypass-cache (optional)

Usage example: 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 Top values query examples to see a lot of top values query examples.


What's Next

Exists