citrusleaf the noSQL database for the enterprise

apis & clients

Clients Overview

Citrusleaf provides a smart client that provides simple interfaces for reading and writing data to the Citrusleaf cluster. The client tracks the state of the cluster itself, and directs transaction requests to the optimal nodes. This means that the application is entirely protected from any change in cluster configuration - nodes can be added and subtracted without failing transactions, and the clients do not have to be restarted when a nodes goes up or down.

The Citrusleaf data model is in many ways similar to the familiar RDBMS model, although the names are different to reflect the the fact that Citrusleaf is not a RDBMS. In the Citrusleaf documentation, we refer to a 'namespace', which closesly parallels 'database'. Similarly 'set' is analogous to 'table', and 'bin' to 'column'.

For an application developer, there are several key differences to keep in mind:

  • The system is schema-less. There is no need to define sets or bins up front - if you need to add a new set or a bin, use the standard 'set' APIs and it will be created for you.
  • The system is fundamentally a key-value store. Records are indexed by a key which must be supplied to retrieve the data in the record.
  • Values in bins are strongly typed, however, the bins themselves are not. That means that different records may have different types for values in the same bin. As an example, consider a set with bin 'name'. Some records may have fill this bin with a string (the standard case), some may fill the bin with an integer (an error case) and others may not have a value in that bin at all. How this feature is used is entirely up to the application developer.
  • Each record contains an additional bit of data, the generation count, which reflects how many times the data has been modified. This number is handed back to the application on a read, and may be used to make sure that data that is being written has not been modified since the last read. (This is the same paradigm used by memcache.) See the Set If Not Modified call, below.

API Overview

All the Clients support standard get and set operations, athough some clients have some additional parameters and functionality. In broad strokes, the following is a list of the fundamental calls found in the APIs

  • Client Create
    Creates/initializes the Citrusleaf Client. In object oriented languages, this is implemented as a constructor.
  • Client Release
    Releases resources associated with the client.
  • Add Host
    Tells the client the host name/address of one of the cluster nodes. The client will communicate with this node to find the locations of the other nodes in the cluster.
  • Set Value(s)
    Sets a bin value (or values) for a particular record in the specified namespace and set, as referenced by the specified key. If the record, set or bin does not exist, the system will create them.
  • Set Value(s) If Unmodified
    Sets a bin value (or values), per the Set Value API, above, but does so only if the value has not been modified since it was read. (This call uses a passed in generation count to determine if the value has been modified.)
  • Set Value(s) If Unique
    Sets a bin value (or values), per the Set Value API, above, but does so only if the record does not already exist.
  • Add to Value(s)
    Add a passed in parameter to the specified values. Integers will add; strings and blobs will concatenate.
  • Get Value(s)
    Get a bin value (or values) for a particular record in the specified namespace and set, as referenced by the specified key.
  • Delete Record
    Delete a particular record, as identified by the namespace, set, and key.
  • Batch Get
    Get value(s) from multiple records at once.
  • Scan Namespace
    Used for backing up a namespace - returns the entire contents of the namespace.

All get and set operations take two additional parameters - the transaction timeout time, and the retry policy. By default, the retry policy is to retry failed operations until the specified timeout. Set operations take an optional time-to-live parameter, which specifies how long the record is to be protected from automatic eviction by the system. The time-to-live can be set to infinite, in which case the data will never be automatically evicted.

Citrusleaf supports basic types: integers, strings, and blobs. In addition to simple byte array blobs, the system also supports automatic serialization for language-native blobs

Optimistic locking, or Read / Modify / Write

Citrusleaf supports a method of safely modifying complex database contents safely and scalably. This technique has recently been popularized by memcache, which they call CAS (Compare And Swap), but is known generally in databases as Optomistic locking.. In this API pattern, a database read returns a value that represents the current state of that record - which Citrusleaf calls a generation. When the record is to be written - with the goal of failing if another writer has updated the record in the intrim - the generation is included in the write. If another client has modified the record since this client's read, the write will fail.

Many of the Citrusleaf clients support this feature. The read functions always return the generation, and write calls may optionally include the generation to trigger this behavior.

Available clients

Citrusleaf provides clients in several different languages. The APIs are documented (and source code to the clients provided) in these pages. Choose your favorite below

C API

C# API

C API Using LibEvent

Java API

PHP API

Python API

Ruby API