SlicingDice API Docs

SlicingDice API Docs

Welcome to the SlicingDice API documentation. You'll find comprehensive guides and documentation to help you start working with SlicingDice as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Documentation

Java

Java client/SDK for SlicingDice

You can use the SlicingDice's Java client/SDK to rapidly start inserting and querying your data, without having to handle with all the API HTTP requests yourself.

Installing the client

Click here to download our Java client as a jar file. After downloading it, you only need to import the jar into your project path.

Also, our Java client can be installed via Maven by adding the following configurations in our pom.xml.

<repository>
    <id>slicingdice-clients</id>
    <url>https://packagecloud.io/slicingdice/clients/maven2</url>
    <releases>
        <enabled>true</enabled>
    </releases>
    <snapshots>
        <enabled>true</enabled>
    </snapshots>
</repository>
<dependency>
    <groupId>com.slicingdice</groupId>
    <artifactId>jslicer</artifactId>
    <version>2.0.2</version>
</dependency>

Please note the client has the following dependencies:

Maven can be used to install the dependencies with the following configurations.

<dependency>
    <groupId>org.asynchttpclient</groupId>
    <artifactId>async-http-client</artifactId>
    <version>2.4.2</version>
</dependency>
<dependency>
    <groupId>org.json</groupId>
    <artifactId>json</artifactId>
    <version>20180130</version>
</dependency>
</dependency>

Source code

SlicingDice's Java client/SDK source code is available on Github .

Build Status: CircleCI


Tests and Examples

At the Java client/SDK Github repository, you will find examples of data insertion and queries with their respective expected result messages. You take advantage of all these examples to test the client and also learn how to use it.


Using the client

SlicingDice class encapsulates logic for sending requests to the API. Its methods are thin layers around the API endpoints, so their parameters and return values are JSON-like dict and lists objects with the same syntax as the API endpoints.

import java.io.IOException;
import org.json.JSONArray;
import org.json.JSONObject;
import com.slicingdice.jslicer.SlicingDice;

public class Example {
    public static void main( String[] args ) throws IOException
    {
        SlicingDice client = new SlicingDice("API_KEY");

        // Creating a column
        // Inserting data
        JSONObject insertData = new JSONObject()
                .put("user1@slicingdice.com",
                        new JSONObject()
                                .put("age", 22))
                .put("auto-create", new JSONArray()
                        .put("dimension")
                        .put("column"));
        System.out.println(client.insert(insertData).get().getResponseBody());

        // Querying data
        JSONObject queryData = new JSONObject()
                .put("query-name", "users-between-20-and-40")
                .put("query",
                        new JSONArray()
                                .put(new JSONObject()
                                        .put("age",
                                                new JSONObject()
                                                        .put("range",
                                                                new JSONArray()
                                                                        .put(20)
                                                                        .put(40)))));
        System.out.println(client.countEntity(queryData).get().getResponseBody());
    }
}

API Keys

API keys are configured with the client constructor, as presented in the example below.

import com.simbiose.jslicer.SlicerDicer


public class App
{
    public static void main( String[] args ) throws IOException
    {
        SlicingDice slicingDice = new SlicingDice("MASTER_API_KEY", "CUSTOM_API_KEY", "WRITE_API_KEY", "READ_API_KEY");
    }
}

Constructor

public SlicingDice(
    String masterKey, 
    String customKey, 
    String writeKey,
    String readKey, 
    int timeout)

// Short form
public SlicingDice(String masterKey, boolean usesTestEndPoint)
  • masterKey (String) - Master API Key to used to authenticate requests on SlicingDice API.
  • customKey (String) - Custom API Key to used to authenticate requests on SlicingDice API.
  • writeKey (String) - Write API Key to used to authenticate requests on SlicingDice API.
  • readKey (String) - Read API Key to used to authenticate requests on SlicingDice API.
  • timeout (int) - Amount of time, in seconds, to wait for results for each request.

`close()` method

You'll need to call close() method if you want to properly end the Java client, this method will shut down the threads used on async http.

Methods

  • Future<Response> getDatabase() - Get current database, identified by the given API key. This method corresponds to a GET request at /database.
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.Future;
import org.asynchttpclient.Response;

public class Example {

    public static void main(String[] args) throws InterruptedException, ExecutionException, IOException {
        final SlicingDice slicingDice = new SlicingDice("MASTER_API_KEY");
        final Future<Response> result = slicingDice.getDatabase();
        System.out.println(result.get().getResponseBody());

        slicingDice.close();
    }
}
  • Future<Response> getColumns() - Get all created columns, both active and inactive ones organized by table. This method corresponds to a GET request at /column.
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.Future;
import org.asynchttpclient.Response;

public class Example {

    public static void main(String[] args) throws InterruptedException, ExecutionException, IOException {
        final SlicingDice slicingDice = new SlicingDice("MASTER_API_KEY");
        final Future<Response> result = slicingDice.getColumns();
        System.out.println(result.get().getResponseBody());

        slicingDice.close();
    }
}
  • Future<Response> createColumn(JSONObject data) - Create a new column. This method corresponds to a POST request at /column.
import java.io.IOException;
import org.json.JSONObject;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.Future;
import org.asynchttpclient.Response;

public class Example {

    public static void main(String[] args) throws InterruptedException, ExecutionException, IOException {
        final SlicingDice slicingDice = new SlicingDice("MASTER_API_KEY");
        final JSONObject column = new JSONObject()
                .put("name", "Year")
                .put("api-name", "year")
                .put("type", "integer")
                .put("description", "Year of manufacturing")
                .put("storage", "latest-value");
        final Future<Response> result = slicingDice.createColumn(column);
        System.out.println(result.get().getResponseBody());

        slicingDice.close();
    }
}
  • Future<Response> insert(JSONObject data) - Insert data to existing entities or create new entities, if necessary. This method corresponds to a POST request at /insert.
import org.json.JSONArray;
import org.json.JSONObject;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.Future;
import org.asynchttpclient.Response;

public class Example {

    public static void main(String[] args) throws InterruptedException, ExecutionException, IOException {
        final SlicingDice slicingDice = new SlicingDice("MASTER_OR_WRITE_API_KEY");
        final SONObject insertData = new JSONObject()
                .put("user1@slicingdice.com", new JSONObject()
                        .put("car-model", "Ford Ka")
                        .put("year", 2016))
                .put("user2@slicingdice.com", new JSONObject()
                        .put("car-model", "Honda Fit")
                        .put("year", 2016))
                .put("user3@slicingdice.com", new JSONObject()
                        .put("car-model", "Toyota Corolla")
                        .put("year", 2010)
                        .put("test-drives", new JSONArray()
                                .put(new JSONObject()
                                        .put("value", "NY")
                                        .put("date", "2016-08-17T13:23:47+00:00"))
                                .put(new JSONObject()
                                        .put("value", "NY")
                                        .put("date", "2016-08-17T13:23:47+00:00"))
                                .put(new JSONObject()
                                        .put("value", "NY")
                                        .put("date", "2016-04-05T10:20:30Z"))))
                .put("customer5@mycustomer.com", new JSONObject()
                        .put("car-model", "Ford Ka")
                        .put("year", 2005)
                        .put("test-drives", new JSONObject()
                                .put("value", "NY")
                                .put("date", "2016-08-17T13:23:47+00:00")))
                .put("auto-create", new JSONArray()
                        .put("dimension")
                        .put("column"));
        final Future<Response> result = slicingDice.insert(insertData);
        System.out.println(result.get().getResponseBody());

        slicingDice.close();
    }
}
  • Future<Response> existsEntity(JSONArray ids[, String table]) - Verify which entities exist in a table (uses default table if not provided) given a list of entity IDs. This method corresponds to a POST request at /query/exists/entity.
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.Future;
import org.asynchttpclient.Response;
import org.json.JSONArray;
import org.json.JSONObject;

public class Example {

    public static void main(String[] args) throws InterruptedException, ExecutionException, IOException {
        final SlicingDice slicingDice = new SlicingDice("MASTER_OR_READ_API_KEY");
        final JSONArray ids = new JSONArray()
                .put("user1@slicingdice.com")
                .put("user2@slicingdice.com")
                .put("user3@slicingdice.com");
        Future<Response> result = slicingDice.existsEntity(ids);
        System.out.println(result.get().getResponseBody());

        slicingDice.close();
    }
}
  • Future<Response> countEntityTotal([Collection<String> tables]) - Count the number of stored entities in given tables (or in all tables by default). This method corresponds to a POST request at /query/count/entity/total.
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.Future;
import org.asynchttpclient.Response;
import org.json.JSONObject;

public class Example {

    public static void main(String[] args) throws InterruptedException, ExecutionException, IOException {
        final SlicingDice slicingDice = new SlicingDice("MASTER_OR_READ_API_KEY");
        final Future<Response> result = slicingDice.countEntityTotal();
        System.out.println(result.get().getResponseBody());

        slicingDice.close();
    }
}
  • Future<Response> countEntity(JSONObject query) - Count the number of entities satisfying the given query. This method corresponds to a POST request at /query/count/entity.
import org.json.JSONArray;
import org.json.JSONObject;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.Future;
import org.asynchttpclient.Response;

public class Example {

    public static void main(String[] args) throws InterruptedException, ExecutionException, IOException {
        final SlicingDice slicingDice = new SlicingDice("MASTER_OR_READ_API_KEY");
        final JSONArray countEntityQuery = new JSONArray()
                        .put(new JSONObject()
                                .put("query-name", "corolla-or-fit")
                                .put("query", new JSONArray()
                                        .put(new JSONObject()
                                                .put("car-model", new JSONObject()
                                                        .put("equals", "toyota corolla")))
                                        .put("or")
                                        .put(new JSONObject()
                                                .put("car-model", new JSONObject()
                                                        .put("equals", "honda fit"))))
                                .put("bypass-cache", false))
                        .put(new JSONObject()
                                .put("query-name", "ford-ka")
                                .put("query", new JSONArray()
                                        .put(new JSONObject()
                                                .put("car-model", new JSONObject()
                                                        .put("equals", "ford ka"))))
                                .put("bypass-cache", false));
        final Future<Response> result = slicingDice.countEntity(countEntityQuery);
        System.out.println(result.get().getResponseBody());

        slicingDice.close();
    }
}
  • Future<Response> countEvent(JSONObject query) - Count the number of occurrences for events satisfying the given query. This method corresponds to a POST request at /query/count/event.
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.Future;
import org.asynchttpclient.Response;
import org.json.JSONArray;
import org.json.JSONObject;

public class Example {

    public static void main(String[] args) throws InterruptedException, ExecutionException, IOException {
        final SlicingDice slicingDice = new SlicingDice("MASTER_OR_READ_API_KEY");
        final JSONArray countEventQuery = new JSONArray()
                        .put(new JSONObject()
                                .put("query-name", "test-drives-in-ny")
                                .put("query", new JSONArray()
                                        .put(new JSONObject()
                                                .put("test-drives", new JSONObject()
                                                        .put("equals", "NY")
                                                        .put("between", new JSONArray()
                                                                .put("2016-08-16T00:00:00Z")
                                                                .put("2016-08-18T00:00:00Z")))))
                                .put("bypass-cache", false))
                        .put(new JSONObject()
                                .put("query-name", "test-drives-in-ca")
                                .put("query", new JSONArray()
                                        .put(new JSONObject()
                                                .put("test-drives", new JSONObject()
                                                        .put("equals", "CA")
                                                        .put("between", new JSONArray()
                                                                .put("2016-04-04T00:00:00Z")
                                                                .put("2016-04-06T00:00:00Z")))))
                                .put("bypass-cache", false));

        final Future<Response> result = slicingDice.countEvent(countEventQuery);
        final System.out.println(result.get().getResponseBody());

        slicingDice.close();
    }
}
  • Future<Response> topValues(JSONObject query) - Return the top values for entities satisfying the given query. This method corresponds to a POST request at /query/top_values.
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.Future;
import org.asynchttpclient.Response;
import org.json.JSONObject;

public class Example {

    public static void main(String[] args) throws InterruptedException, ExecutionException, IOException {
        final SlicingDice slicingDice = new SlicingDice("MASTER_OR_READ_API_KEY");
        final JSONObject topValuesQuery = new JSONObject()
                .put("car-year", new JSONObject()
                        .put("year", 2))
                .put("car models", new JSONObject()
                        .put("car-model", 3));
        final Future<Response> result = slicingDice.topValues(topValuesQuery);
        System.out.println(result.get().getResponseBody());

        slicingDice.close();
    }
}
  • Future<Response> aggregation(JSONObject query) - Return the aggregation of all columns in the given query. This method corresponds to a POST request at /query/aggregation.
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.Future;
import org.asynchttpclient.Response;
import org.json.JSONArray;
import org.json.JSONObject;

public class Example {

    public static void main(String[] args) throws InterruptedException, ExecutionException, IOException {
        final SlicingDice slicingDice = new SlicingDice("MASTER_OR_READ_API_KEY");
        final JSONObject aggregationQuery = new JSONObject()
                .put("query", new JSONArray()
                        .put(new JSONObject()
                                .put("year", 2))
                        .put(new JSONObject()
                                .put("car-model", 2)
                                .put("equals", new JSONArray()
                                        .put("honda fit")
                                        .put("toyota corolla"))));
        final Future<Response> result = slicingDice.aggregation(aggregationQuery);
        System.out.println(result.get().getResponseBody());

        slicingDice.close();
    }
}
  • Future<Response> getSavedQueries() - Get all saved queries. This method corresponds to a GET request at /query/saved.
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.Future;
import org.asynchttpclient.Response;

public class Example {

    public static void main(String[] args) throws InterruptedException, ExecutionException, IOException {
        final SlicingDice slicingDice = new SlicingDice("MASTER_API_KEY");
        final Future<Response> result = slicingDice.getSavedQueries();
        System.out.println(result.get().getResponseBody());

        slicingDice.close();
    }
}
  • Future<Response> createSavedQuery(JSONObject query) - Create a saved query at SlicingDice. This method corresponds to a POST request at /query/saved.
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.Future;
import org.asynchttpclient.Response;
import org.json.JSONArray;
import org.json.JSONObject;

public class Example {

    public static void main(String[] args) throws InterruptedException, ExecutionException, IOException {
        final SlicingDice slicingDice = new SlicingDice("MASTER_API_KEY");
        final JSONObject savedQuery = new JSONObject()
                .put("name", "my-saved-query")
                .put("type", "count/entity")
                .put("query", new JSONArray()
                        .put(new JSONObject()
                                .put("car-model", new JSONObject()
                                        .put("equals", "honda fit")))
                        .put("or")
                        .put(new JSONObject()
                                .put("car-model", new JSONObject()
                                        .put("equals", "toyota corolla"))))
                .put("cache-period", 100);
        final Future<Response> result = slicingDice.createSavedQuery(savedQuery);
        System.out.println(result.get().getResponseBody());

        slicingDice.close();
    }
}
  • Future<Response> updateSavedQuery(String queryName, JSONObject query) - Update an existing saved query at SlicingDice. This method corresponds to a PUT request at /query/saved/:query_name.
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.Future;
import org.asynchttpclient.Response;
import org.json.JSONArray;
import org.json.JSONObject;

public class Example {

    public static void main(String[] args) throws InterruptedException, ExecutionException, IOException {
       final  SlicingDice slicingDice = new SlicingDice("MASTER_API_KEY");
        final JSONObject newSavedQuery = new JSONObject()
                .put("type", "count/entity")
                .put("query", new JSONArray()
                        .put(new JSONObject()
                                .put("car-model", new JSONObject()
                                        .put("equals", "honda fit")))
                        .put("or")
                        .put(new JSONObject()
                                .put("car-model", new JSONObject()
                                        .put("equals", "toyota corolla"))))
                .put("cache-period", 100);
        final Future<Response> result = slicingDice.updateSavedQuery("my-saved-query", newSavedQuery);
        System.out.println(result.get().getResponseBody());

        slicingDice.close();
    }
}
  • Future<Response> getSavedQuery(String queryName) - Execute a saved query at SlicingDice. This method corresponds to a GET request at /query/saved/:query_name.
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.Future;
import org.asynchttpclient.Response;

public class Example {

    public static void main(String[] args) throws InterruptedException, ExecutionException, IOException {
        final SlicingDice slicingDice = new SlicingDice("MASTER_OR_READ_API_KEY");
        final Future<Response> result = slicingDice.getSavedQuery("my-saved-query");
        System.out.println(result.get().getResponseBody());

        slicingDice.close();
    }
}
  • Future<Response> deleteSavedQuery(String queryName) - Delete a saved query at SlicingDice. This method corresponds to a DELETE request at /query/saved/:query_name.
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.Future;
import org.asynchttpclient.Response;

public class Example {

    public static void main(String[] args) InterruptedException, ExecutionException, throws IOException {
        final SlicingDice slicingDice = new SlicingDice("MASTER_API_KEY");
        final Future<Response> result = slicingDice.deleteSavedQuery("my-saved-query");
        System.out.println(result.get().getResponseBody());

        slicingDice.close();
    }
}
  • Future<Response> result(JSONObject query) - Retrieve stored values for entities satisfying the given query. This method corresponds to a POST request at /data_extraction/result.
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.Future;
import org.asynchttpclient.Response;
import org.json.JSONArray;
import org.json.JSONObject;

public class Example {

    public static void main(String[] args) throws InterruptedException, ExecutionException, IOException {
        final SlicingDice slicingDice = new SlicingDice("MASTER_OR_READ_API_KEY");
        final JSONObject resultQuery = new JSONObject()
                .put("query", new JSONArray()
                        .put(new JSONObject()
                                .put("car-model", new JSONObject()
                                        .put("equals", "ford ka")))
                        .put("or")
                        .put(new JSONObject()
                                .put("car-model", new JSONObject()
                                        .put("equals", "honda fit"))))
                .put("columns", new JSONArray()
                        .put("car-model")
                        .put("year"))
                .put("limit", 2);
        final Future<Response> result = slicingDice.result(resultQuery);
        System.out.println(result.get().getResponseBody());

        slicingDice.close();
    }
}
  • Future<Response> score(JSONObject query) - Retrieve stored values as well as their relevance for entities satisfying the given query. This method corresponds to a POST request at /data_extraction/score.
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.Future;
import org.asynchttpclient.Response;
import org.json.JSONArray;
import org.json.JSONObject;

public class Example {

    public static void main(String[] args) throws InterruptedException, ExecutionException, IOException {
        final SlicingDice slicingDice = new SlicingDice("MASTER_OR_READ_API_KEY");
        final JSONObject scoreQuery = new JSONObject()
                .put("query", new JSONArray()
                        .put(new JSONObject()
                                .put("car-model", new JSONObject()
                                        .put("equals", "toyota corolla")))
                        .put("or")
                        .put(new JSONObject()
                                .put("car-model", new JSONObject()
                                        .put("equals", "honda fit"))))
                .put("columns", new JSONArray()
                        .put("car-model")
                        .put("year"))
                .put("limit", 2);
        final Future<Response> result = slicingDice.score(scoreQuery);
        System.out.println(result.get().getResponseBody());
    }
}
  • Future<Response> sql(String query) - Retrieve inserted values using a SQL syntax. This method corresponds to a POST request at /query/sql.

Query statement

import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.Future;
import org.asynchttpclient.Response;

public class Example {

    public static void main(String[] args) throws InterruptedException, ExecutionException, IOException {
        final SlicingDice slicingDice = new SlicingDice("MASTER_OR_READ_API_KEY");
        final Future<Response> result = slicingDice.sql("SELECT COUNT(*) FROM default WHERE age BETWEEN 0 AND 49");
        System.out.println(result.get().getResponseBody());

        slicingDice.close();
    }
}

Insert statement

import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.Future;
import org.asynchttpclient.Response;

public class Example {

    public static void main(String[] args) throws InterruptedException, ExecutionException, IOException {
        final SlicingDice slicingDice = new SlicingDice("MASTER_OR_READ_API_KEY");
        final Future<Response> result = slicingDice.sql("INSERT INTO default([entity-id], name, age) VALUES(1, 'john', 10)");
        System.out.println(result.get().getResponseBody());

        slicingDice.close();
    }
}

Using callbacks instead of Futures

The programmer can define callbacks instead of using returned Futures, to create a callback you'll need to extend the class HandlerResponse and implement the methods onError and onSuccess. See the example below.

public static class MyHandler extends HandlerResponse {
    @Override
    public void onSuccess(final JSONObject data) throws Exception {
        System.out.println(data.toString());
    }

    @Override
    public void onError(final JSONObject data) throws Exception {
        System.out.println(data.toString());
    }
}

And you can use the handler this way:

slicingDice.sql("SELECT COUNT(*) FROM default WHERE age BETWEEN 0 AND 49", new MyHandler());

Java

Java client/SDK for SlicingDice