Source

riak / README

                                       Welcome to Riak.
                                       ================




Table of Contents
=================
1 Overview 
2 Quick Start 
    2.1 Building Riak 
    2.2 Starting Riak 
    2.3 Connecting a client to Riak 


1 Overview 
~~~~~~~~~~~
  Riak is a distributed, decentralized data storage system. 
  
  Below, you will find the "quick start" directions for setting up and
  using Riak.  For more information, browse the following files:
  
  * README:  this file
  * TODO:    a list of improvements planned for Riak
  * LICENSE: the license under which Riak is released
  * apps/    the source tree for Riak and all its dependencies
  * doc/
    - basic-setup.txt:  slightly more detail on setting up Riak
    - basic-client.txt: slightly more detail on using Riak
    - architecture.txt: details about the underlying design of Riak
    - index.html:       the root of the edoc output of 'make docs'


2 Quick Start 
~~~~~~~~~~~~~~

  This section assumes that you have copy of the Riak source tree. To get started, you need to:
  1. Build Riak
  2. Start the Riak server
  3. Connect a client and store/fetch data

2.1 Building Riak 
==================

   Assuming you have a working Erlang (R13B03 or later) installation,
   building Riak should be as simple as:

   $ cd $RIAK
   $ make all rel

2.2 Starting Riak 
==================

   Once you have successfully built Riak, you can start the server with the following commands:

   $ cd $RIAK/rel/riak
   $ bin/riak start

   Now, verify that the server started up cleanly and is working:

   $ bin/riak-admin test

2.3 Connecting a client to Riak 
================================

!!! UNDER CONSTRUCTION !!!

Assuming no errors were generated during the server start step, a
simple client interaction will look like:
(remember, $RIAK should be set to the local path to your Riak installation)

$ erl -name riaktest@127.0.0.1 -pa $RIAK/ebin -setcookie riak_demo_cookie

(riaktest@127.0.0.1)1> %% connect to Riak
(riaktest@127.0.0.1)1> {ok, C} = riak:client_connect('riakdemo@127.0.0.1').
{ok,{riak_client,'riakdemo@127.0.0.1',
                 "20090722191020-riaktest@127.0.0.1-riakdemo@127.0.0.1-266664"}}

riaktest@127.0.0.1)2> %% Create a shopping list for bread at /groceries/mine
riaktest@127.0.0.1)2> O0 = riak_object:new("groceries", "mine", ["bread"]).
{r_object,"groceries","mine",
          [{r_content,{dict,0,16,16,8,80,48,
                            {[],[],[],[],[],[],[],[],[],[],[],[],[],[],...},
                            {{[],[],[],[],[],[],[],[],[],[],[],[],...}}},
                      ["bread"]}],
          [],
          {dict,0,16,16,8,80,48,
                {[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],...},
                {{[],[],[],[],[],[],[],[],[],[],[],[],[],...}}},
          undefined}

(riaktest@127.0.0.1)3> %% store the list
(riaktest@127.0.0.1)3> C:put(O0, 1).
ok

(riaktest@127.0.0.1)4> %% retrieve the list
(riaktest@127.0.0.1)4> {ok, O1} = C:get("groceries", "mine", 1).
{ok,{r_object,"groceries","mine",
              [{r_content,{dict,2,16,16,8,80,48,
                                {[],[],[],[],[],[],[],[],[],[],[],[],...},
                                {{[],[],[],[],[],[],
                                  ["X-Riak-Last-Modified",87|...],
                                  [],[],[],...}}},
                          ["bread"]}],
              [{"20090722191020-riaktest@127.0.0.1-riakdemo@127.0.0.1-266664",
                {1,63415509105}}],
              {dict,0,16,16,8,80,48,
                    {[],[],[],[],[],[],[],[],[],[],[],[],[],...},
                    {{[],[],[],[],[],[],[],[],[],[],[],...}}},
              undefined}}

(riaktest@127.0.0.1)5> %% extract the value
(riaktest@127.0.0.1)5> V = riak_object:get_value(O1).
["bread"]

(riaktest@127.0.0.1)6> %% add milk to the list
(riaktest@127.0.0.1)6> O2 = riak_object:update_value(O1, ["milk"|V]).
{r_object,"groceries","mine",
          [{r_content,{dict,2,16,16,8,80,48,
                            {[],[],[],[],[],[],[],[],[],[],[],[],[],[],...},
                            {{[],[],[],[],[],[],
                              ["X-Riak-Last-Modified",87,101,100|...],
                              [],[],[],[],[],...}}},
                      ["bread"]}],
          [{"20090722191020-riaktest@127.0.0.1-riakdemo@127.0.0.1-266664",
            {1,63415509105}}],
          {dict,0,16,16,8,80,48,
                {[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],...},
                {{[],[],[],[],[],[],[],[],[],[],[],[],[],...}}},
          ["milk","bread"]}

(riaktest@127.0.0.1)7> %% store the new list
(riaktest@127.0.0.1)7> C:put(O2, 1).
ok


(riaktest@127.0.0.1)8> %% find out what else is in the groceries bucket
(riaktest@127.0.0.1)8> C:list_keys("groceries").
{ok,["mine"]}

["X-Riak-Last-Modified",87|...]: sec-2.3
["X-Riak-Last-Modified",87,101,100|...]: sec-2.3