SlicingDice Documentation

SlicingDice - The All-in-One Solution Documentation

Welcome to the SlicingDice 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

Count entities

Count how many unique entities you have.


A SlicingDice count entities query is equivalent to a SQL query like this:

SELECT COUNT(DISTINCT User.UserID)
FROM User WHERE ...

Query purpose

You should use count entities to know how many unique entities you have in a particular dimension that satisfy the query conditions.

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

  • How many male users from San Francisco there are on the dimension?
  • How many users accessed the page /online-demo or /platform more than 3 times in the last 7 days?
  • How many users are either male from San Francisco older than 25 or are female users from New York older than 24?

Query endpoint

In order to make a count entities query, you simply need to send a HTTPS POST request to https://api.slicingdice.com/v1/query/count/entity with an array of JSON objects (or a single JSON object) of queries identified by unique names (query-name), each containing a list of columns and conditions and operators, if any.

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 count how many unique entities there are on the dimension users, that have the name equals to Jeff and clicks equals to Pay Now between {% convert_date 'YYYY-MM-DDT00:00:00Z' '-15d' %} and {% convert_date 'YYYY-MM-DDT00:00:00Z' '-1d' %}.

SELECT COUNT([entity-id]) FROM users WHERE name = 'Jeff' AND [clicks.value] = 'Pay Now' and [clicks.date] BETWEEN '{% convert_date 'YYYY-MM-DDT00:00:00Z' '-15d' %}' 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 COUNT([entity-id]) FROM users WHERE name = 'Jeff' AND [clicks.value] = 'Pay Now' and [clicks.date] BETWEEN '{% convert_date 'YYYY-MM-DDT00:00:00Z' '-15d' %}' AND '{% convert_date 'YYYY-MM-DDT00:00:00Z' '-1d' %}';'
curl -X POST https://api.slicingdice.com/v1/query/count/entity \
    -H 'Authorization: MASTER_OR_READ_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '[
        {
            "query-name": "jeff-user-clicked-to-pay",
            "dimension": "users",
            "query": [
                {
                    "name": {
                        "equals": "Jeff"
                    }
                },
                "and",
                {
                    "clicks": {
                        "equals": "Pay Now",
                        "between": [
                            "{% convert_date 'YYYY-MM-DDT00:00:00Z' '-15d' %}",
                            "{% convert_date 'YYYY-MM-DDT00:00:00Z' '-1d' %}"
                        ]
                    }
                }
            ],
            "bypass-cache": true
        }
    ]'
from pyslicer import SlicingDice
slicingdice = SlicingDice(master_key='MASTER_API_KEY')

query_data = [
    {
        "dimension": "users",
        "query-name": "jeff-user-clicked-to-pay",
        "bypass-cache": True,
        "query": [
            {
                "name": {
                    "equals": "Jeff"
                }
            }, 
            "and", 
            {
                "clicks": {
                    "equals": "Pay Now",
                    "between": [
                        "{% convert_date 'YYYY-MM-DDT00:00:00Z' '-15d' %}", 
                        "{% convert_date 'YYYY-MM-DDT00:00:00Z' '-1d' %}"
                    ]
                }
            }
        ]
    }
]

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

        JSONArray queryData = new JSONArray()
        .put(new JSONObject()
            .put("dimension", "users")
            .put("query-name", "jeff-user-clicked-to-pay")
            .put("bypass-cache", true)
            .put("query", new JSONArray()
                .put(new JSONObject()
                    .put("name", new JSONObject()
                        .put("equals", "Jeff")))
                .put("and")
                .put(new JSONObject()
                    .put("clicks", new JSONObject()
                        .put("equals", "Pay Now")
                        .put("between", new JSONArray()
                            .put("{% convert_date 'YYYY-MM-DDT00:00:00Z' '-15d' %}")
                            .put("{% convert_date 'YYYY-MM-DDT00:00:00Z' '-1d' %}"))))));
        JSONObject result = slicingdice.countEntity(queryData);
        System.out.println(result.toString());
    }
}
require 'rbslicer'
slicingdice = SlicingDice.new(master_key: 'MASTER_API_KEY')

query_data = [
    {
        "dimension" => "users",
        "query-name" => "jeff-user-clicked-to-pay",
        "bypass-cache" => true,
        "query" => [
            {
                "name" => {
                    "equals" => "Jeff"
                }
            }, 
            "and", 
            {
                "clicks" => {
                    "equals" => "Pay Now",
                    "between" => [
                        "{% convert_date 'YYYY-MM-DDT00:00:00Z' '-15d' %}", 
                        "{% convert_date 'YYYY-MM-DDT00:00:00Z' '-1d' %}"
                    ]
                }
            }
        ]
    }
]

puts slicingdice.count_entity(query_data)

const SlicingDice = require('slicerjs');

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

const queryData = [
    {
        "dimension": "users",
        "query-name": "jeff-user-clicked-to-pay",
        "bypass-cache": true,
        "query": [
            {
                "name": {
                    "equals": "Jeff"
                }
            }, 
            "and", 
            {
                "clicks": {
                    "equals": "Pay Now",
                    "between": [
                        "{% convert_date 'YYYY-MM-DDT00:00:00Z' '-15d' %}", 
                        "{% convert_date 'YYYY-MM-DDT00:00:00Z' '-1d' %}"
                    ]
                }
            }
        ]
    }
];

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

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

$queryData = array(
    array(
        "dimension" => "users",
        "query-name" => "jeff-user-clicked-to-pay",
        "bypass-cache" => true,
        "query" => array(
            array(
                "name" => array(
                    "equals" => "Jeff"
                )
            ), 
            "and", 
            array(
                "clicks" => array(
                    "equals" => "Pay Now",
                    "between" => array(
                        "{% convert_date 'YYYY-MM-DDT00:00:00Z' '-15d' %}", 
                        "{% convert_date 'YYYY-MM-DDT00:00:00Z' '-1d' %}"
                    )
                )
            )
        )
    )
);

print_r($slicingdice->countEntity($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 List<dynamic>{
                new Dictionary<string, dynamic>{
                    {"dimension", "users"},
                    {"query-name", "jeff-user-clicked-to-pay"},
                    {"bypass-cache", true},
                    {"query", new List<dynamic>{
                        new Dictionary<string, dynamic>{
                            {"name", new Dictionary<string, dynamic>{
                                {"equals", "Jeff"}
                            }}
                        }, 
                        "and", 
                        new Dictionary<string, dynamic>{
                            {"clicks", new Dictionary<string, dynamic>{
                                {"equals", "Pay Now"},
                                {"between", new List<dynamic>{
                                    "{% convert_date 'YYYY-MM-DDT00:00:00Z' '-15d' %}", 
                                    "{% convert_date 'YYYY-MM-DDT00:00:00Z' '-1d' %}"
                                }}
                            }}
                        }
                    }}
                }
            };

            var result = slicingdice.CountEntity(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 := []interface{}{
        map[string]interface{}{
            "dimension": "users",
            "query-name": "jeff-user-clicked-to-pay",
            "bypass-cache": true,
            "query": []interface{}{
                map[string]interface{}{
                    "name": map[string]interface{}{
                        "equals": "Jeff",
                    },
                },
                "and",
                map[string]interface{}{
                    "clicks": map[string]interface{}{
                        "equals": "Pay Now",
                        "between": []interface{}{
                            "{% convert_date 'YYYY-MM-DDT00:00:00Z' '-15d' %}",
                            "{% convert_date 'YYYY-MM-DDT00:00:00Z' '-1d' %}",
                        },
                    },
                },
            },
        },
    }

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

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

{
    "status": "success",
    "result": {
        "jeff-user-clicked-to-pay": 1
    },
    "took": 0.103
}

Let's understand each component of the API response:

  • status - Indicating whether the request was successfully processed or not.
  • result - Query name (jeff-user-clicked-to-pay) and the total number of entities that matches all query conditions (1).
  • took - Time spent processing this request, in seconds.

Counting the entire dimension

In this query below we will count how many unique entities there are on the entire dimension users.
Note that the "query" parameter is not specified on json.

SELECT COUNT(*) FROM users;
$ curl -X POST https://api.slicingdice.com/v1/sql \
    -H 'Authorization: MASTER_OR_WRITE_API_KEY' \
    -H 'Content-Type: application/sql' \
    -d 'SELECT COUNT(*) FROM users;'
curl -X POST https://api.slicingdice.com/v1/query/count/entity \
    -H 'Authorization: MASTER_OR_READ_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '[
        {
            "query-name": "users-entities-total",
            "dimension": "users",
            "bypass-cache": true
        }
    ]'
from pyslicer import SlicingDice
slicingdice = SlicingDice(master_key='MASTER_API_KEY')

query_data = [
    {
        "dimension": "users",
        "query-name": "users-entities-total",
        "bypass-cache": True
    }
]

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

        JSONArray queryData = new JSONArray()
        .put(new JSONObject()
            .put("dimension", "users")
            .put("query-name", "users-entities-total")
            .put("bypass-cache", true));
        JSONObject result = slicingdice.countEntity(queryData);
        System.out.println(result.toString());
    }
}
require 'rbslicer'
slicingdice = SlicingDice.new(master_key: 'MASTER_API_KEY')

query_data = [
    {
        "dimension" => "users",
        "query-name" => "users-entities-total",
        "bypass-cache" => true
    }
]

puts slicingdice.count_entity(query_data)

const SlicingDice = require('slicerjs');

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

const queryData = [
    {
        "dimension": "users",
        "query-name": "users-entities-total",
        "bypass-cache": true
    }
];

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

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

$queryData = array(
    array(
        "dimension" => "users",
        "query-name" => "users-entities-total",
        "bypass-cache" => true
    )
);

print_r($slicingdice->countEntity($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 List<dynamic>{
                new Dictionary<string, dynamic>{
                    {"dimension", "users"},
                    {"query-name", "users-entities-total"},
                    {"bypass-cache", true}
                }
            };

            var result = slicingdice.CountEntity(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 := []interface{}{
        map[string]interface{}{
            "dimension": "users",
            "query-name": "users-entities-total",
            "bypass-cache": true,
        },
    }

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

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

{
	"status": "success",
	"result": {
		"users-entities-total": 1
	},
	"took": 0.035
}
  • status - Indicating whether the request was successfully processed or not.
  • result - Query name (users-entities-total) and the total number of entities on the dimension users.
  • 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

This is the list of supported operators for the count entities query.

and

Usage example: How many entities have the name equal to Jeff and age equal to 18?

or

Usage example: How many entities have the name equal to Jeff or age equal to 18?

not

Usage example: How many entities name equal to Jeff by age not equal to 18?

freqgroup

Usage example: How many entities have the purchased in 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 predicates

This is the list of supported predicates for the count entities 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 results.

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: How many entities have users that have a name that starts with j?

ends-with

Selects only values that end with the requested substring.

Usage example: How many entities have products that have a name that ends with ona?

contains

Selects only values that contain the requested substring.

Usage example: How many entities have countries that contain m?

not-contains

Selects only values that do not contain the requested substring.

Usage example: How many entities have countries that 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 results.

Supported parameters

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.

query-name (optional)

You can send multiple queries in the same request, so when you send more than one query, these queries must be identified by unique names.

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 Count entities query examples to see a lot of examples of count entities queries.


What's Next

Count events