Docussandra marries MongoDB's simple data storage model with the horizontal scaling of Cassandra. It enables developers to store arbitrary payloads as BSON, as they would with MongoDB, in a Cassandra cluster. It supports indexing, filtering, sorting, querying and pagination (via familiar limit and offset semantics). Simple json document storage with effortless scaling exposed as a service - that's Docussandra!
Let's begin by starting a server and beginning to store data.
A running Cassandra instance and maven (for building Java packages).
Before we can start the Docussandra API server that talks to Cassandra we have to create the keyspace where data will be stored. We do this by loading the schema found in the rest/src/main/resources/docussandra.cql directory. On the command line this looks like:
cqlsh -f rest/src/main/resources/docussandra.cql
Next we need to build and run the API server. First, if using a command line, navigate to the api project folder in the root project. Once there, type:
mvn exec:java -Dexec.mainClass="com.strategicgains.docussandra.Main"
If successful, the Docussandra will now be listening to requests on 127.0.0.1:8081.
Once the server has been started we can begin to interact with it. The first step is a create a database in which to store data. This can be done by making a POST request to:
The {databaseName} variable mentioned above can be whatever the user would like as long as it has not been previously used. Names must be globally unique and in lower case. Otherwise an error will result.
To create a logical grouping of similar data we'll create a table. We can do this by making another POST request to:
Naming restrictions on the table name are similar to the database: unique to the database and in lower case.
Storing information to Docussandra is simple. To add a JSON document to a table that you've created, POST the document to the table.
Suppose that we're interested in storing information about the appearances of various superhero characters in comics. First, we need to create the database with Docussandra:
With our comic database created, we now need to create a table for JSON documents that describe our superhero (and villian) appearances.
What does that appearance JSON document look like? Perhaps we want to store something like:
{
"name":"Wolverine",
"date":"1974-11-01",
"comic":"Incredible Hulk, The",
"title":"And Now... the Wolverine!",
"number":"181"
}
That JSON document contains a number of important pieces of information: the name of the character, the date of this appearance, the name of the comic, the title and number of the issue. Good stuff, to be sure. But in our use case we are most concerned with returning information primarily by the character name, followed by the date of the appearance. To do that, we need to create an index. We do this by posting to the reserved word indexes at our endpoint, followed by the name we're giving that index.
POST http://localhost:8081/comics/appearances/indexes/namedate
In the body of the POST, we include the fields within each JSON document that we want Docussandra to index the information by:
{ "fields":["name","date"] }
With the index created, we can now add our data.
with a body of:
{ "name":"Wolverine", "date":"1974-11-01", "comic":"Incredible Hulk, The", "title":"And Now... the Wolverine!", "number":"181" }
Note: While and endpoint of "http://localhost:8081/comics/appearances" was used to create the table, data is written to be written to "http://localhost:8081/comics/appearances**/**", with a trailing slash.
We can retrieve all our appearances by making a GET request to our table: