Download the PHP package kbrw/riak-bundle without Composer

Table Of Content

• Features
• Roadmap
• Dependencies
• Installation
• Configuration
• Basic Usage
  • Accessing a Cluster
  • Defining Bucket content
  • Insert or Update Data into a Bucket
  • Fetch Data from a Bucket
  • Delete Data from a Bucket
  • List keys inside a Bucket
  • Count keys inside a Bucket
  • Search items inside a Bucket using Riak Search
  • Perform MapReduce request on a Cluster
  • Exceptions
• Extended Usage
  • Load and edit Bucket configuration
  • Enable Automatic Indexation
  • Play with Headers
  • Define your own bucket class
• Admin Tasks
  • Common Options
  • List existing buckets
  • Delete all buckets
  • List keys inside a bucket
  • Count keys inside a bucket
  • Delete all keys inside a bucket
  • Delete one key inside a bucket

Features

RiakBundle is designed to ease interaction with Riak database. It allows developers to focus on stored objects instead of on communication APIs. Supported features are :

• support for multi-clustering
• configure clusters : protocol, domain, port, maximum supported connections in parallel, buckets list, ...
• allow developers to plus directly some code into Guzzle to : use proxy, log or count all calls, ...
• insert, delete and fetch objects into a bucket with support for parallel calls (curl_multi)
• fetch, edit and save bucket properties
• list and count keys inside a bucket
• search on a bucket
• perform mapreduce operations through a fluid interface
• console tasks to list and count keys inside a bucket, delete a single key or an entire bucket
• support for custom search parameters (used by custom Riak Search builds)
• support for Bucket inheritance to allow you to define custom services on a bucket

Roadmap

• support for Secondary indexes insert and fetch operations
• support for extended bucket settings (n_val, ...) in YAML configuration
• performance dashboard added to Symfony Debug Toolbar

Dependencies

RiakBundles requires some other bundles / libraries to work :

• Guzzle : to handle HTTP requests thru curl
• JMSSerializer : to handle serialization operations

Installation

Only installation using composer is supported at the moment but source code could be easily tweaked to be used outside it. In order to install RiakBundle in a classic symfony project, just update your composer.json and add or edit this lines :

You may also need to adjust the "minimum-stability" to "dev" in your composer.json to make this work.

Then, you just need to add some bundle into your app/AppKernel.php :

Configuration

For the next sections, let's assume your infrastructure is made of 2 Riak clusters : one used to store your backend objects and one to store all logs. The backend cluster contains two pre-defined buckets. One to store some users in JSON and one to store some cities in XML. On the log cluster, you create a new bucket every day(I know it's strange but why not...) so you can't pre-configured buckets in this cluster. Moreover, you have conducted robustness campaigns and you know that backend cluster is able to support up to 500 parallels connection where your Frontend is never hitted by more than 5 connections in parallels. So you know that you can send 100 backend requests in parallels per frontend requests but no more. If you try to store or fetch or delete more than 100 objects at once, only the first 100 will be processed. Others will have to wait for a slot to opened. RiakBundle will handle this slot mecanism for you.

All configuration can be made on config.yml file under a new namespace. With that in mind, you should define the following configuration :

Example :

Basic Usage

Accessing a cluster

Each cluster becomes a service called "riak.cluster.". In our example, you can access your two clusters using :

Defining bucket content

Riak stores text-based objects so you need to provide a text-based version of your objects. The best practice we recommand is to create an annotated object which represent your model. For example, an User class could be implemented this way :

RiakBundle can automatically take care of serialization / deserialization so that you will always work with User instance and never with its text-based (JSON, XML or YAML) reprensentation. Your model class and the serialization method can be defined into configuration like described above or you can specify it on a bucket instance like this :

Insert or update data into a bucket

Once your bucket is configured, you just have to create an instance of the object you want to store and ask RiakBundle to store it for you. Example :

You can even write multiple users at the same time using parallel calls to Riak :

The same mecanism can be used to update a data :

Fetch data from a bucket

Once you have some data into your bucket, you can start fetching them. As a matter of fact, you can even have no data and start fetching :) The Bucket class provides two ways to fetch data depending on your needs :

• get one single data with the function
• get a list of data with the function Internally, this two methods are doing the same thing but "uniq" will provide you a \Kbrw\RiakBundle\Model\KV\Datas one. \Kbrw\RiakBundle\Model\KV\Data class lets you access the actual object (User, City, ...) but also the Response headers like VClock, Last-Modified, ...

Example :

Delete data from a bucket

You just have to supply a list of keys that have to been deleted. Example :

List keys inside a bucket

Riak does not provide an easy way like SQL databases to list all keys inside a bucket. To do so, it has to run over all keys in the cluster. So, this operation can be really long on a big cluster even if you query against a very small bucket. Moreover, even if RiakBundle uses the "keys=stream" parameter to stream keys from Riak instead of asking Riak to return them all in one response, please keep in mind that PHP might not work well with a multi-million values array. To display all keys inside a bucket :

Count keys inside a bucket

Sometimes, there are too many keys inside a bucket to get them but you might want to count them. To count all keys inside a bucket :

List buckets inside a cluster

If you need to list all buckets inside a cluster, you can use the following example :

Search items inside a bucket using Riak Search

Riak supports a Solr-like (and -light) search engine. RiakBundle lets you searching for items on every buckets with search feature activated. Search can be executed with a simple Solr-Like string query or with a fully qualified \Kbrw\RiakBundle\Model\Search\Query instance. Examples :

Perform MapReduce request on a cluster

Riak allows developers to execute mapreduce operations an entire cluster. RiakBundle offers the same possibility through a fluent interface. Mapreduce operations are made of two main parts :

• select keys the map phase will be executed against. Developers can choose to execute the mapreduce operation against a full bucket, a predefined subset of keys or a filterable set of keys. The three possibilities will be described below.
• define map and reduce phases using javascript functions, erlang module, ... Some possibilities will be defined below but you can dive into the source code or the API to find more.

Generic example :

Basic example :

Key filter example :

Key filter example :

Exceptions

If riak is unavailable or down, RiakBundle will throw a RiakUnavailableException

Advanced Usage

Load and Edit Bucket configuration

Riak allows developers to customize some bucket configuration like nval, the number of replicas to be store in the cluster for each and every data. Please have a look at Riak documentation for closer details.

Using RiakBundle, you can easily update bucket configuration. The \Kbrw\RiakBundle\Model\Bucket\Bucket class is not only the place used to execute operations on a bucket, it also contains bucket properties that you can manage. Example :

Enable automatic indexation

Riak supports automatic indexation of JSON / XML / Erlang datas from Riak KV to Riak Search. This feature needs to be activated on a per-bucket level. RiakBundle lets you easily do that :

Example :

Play with headers

Riak does not only associate an object to a key but also some headers. Some are pre-defined (Last-Modified, X-Riak-Vclock, ...) but you can also put your own custom headers. As explained above, the method takes an associated array of objects. Thoses objects can either be your own simple representation of the data you want to store in Riak or a \Kbrw\RiakBundle\Model\KV\Data instance (the same one returned by the fetch and uniq methods). On this object, you can define your own custom headers by using the headerBag property which is a \Symfony\Component\HttpFoundation\HeaderBag. Example :

The same mecanism can be used to handle Riak merge issues with the X-Riak-Vclock header.

Define your own Bucket class

Sometimes, you might want to define you own Bucket class so that you can override some existing methods, add new ones, ... This can easily be done by hacking the configuration like that :

With this configuration, the "points_of_interests" bucket will be initialized as a and not a regular Bucket. You can now implement this class (that you extends ) to atch your requirements. In the same spirit, each time a Bucket is added to a Cluster, an event named "riak.bucket.add" is thrown to the EventDispatcher. This contains the newly created bucket that you can manipulate the way you want. For closer details, you can have a look at this example.

Admin Tasks

Common Options

All tasks working on a cluster (so... all tasks) support the following option :

• or : the cluster name. If not provided, it will be asked on the command line

All tasks working on a bucket support the following option :

• or : the bucket name. If not provided, it will be asked on the command line

All tasks which list or count items support the following option :

• or : if provided, a raw output format will be used. Mainly used for bash scripting.

All tasks which delete items support the following option :

• or : if provided, all yes/no questions will be skipped. mainly used for bash scripting.

List existing buckets

Delete all buckets

List keys inside a bucket

Count keys inside a bucket

Delete all keys inside a bucket

Delete one key inside a bucket