Source

riak / README.org

Full commit
#+OPTIONS: author:nil timestamp:nil

Welcome to Riak.

* 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'


* 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

** Building Riak

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

   $ cd $RIAK
   $ make all rel

** 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

** Connecting a client to Riak

   Now that you have a functional server, let's try storing some data in it. First,
   start up a erlang node using our embedded version of erlang:

   $ erts-<vsn>/bin/erl -name riaktest -setcookie riak
   
   Eshell V5.7.4  (abort with ^G)
   (riaktest@example.com)1>

   Now construct the node name of Riak server and make sure we can talk to it:

   (riaktest@example.com)4> RiakNode = riak_util:str_to_node(riak).

   (riaktest@example.com)2> net_adm:ping(RiakNode).
   pong
   (riaktest@example.com)2>
   
   We are now ready to start the Riak client:

   (riaktest@example.com)2> {ok, C} = riak:client_connect(RiakNode).
   {ok,{riak_client,'riak@example.com',<<4,136,81,151>>}}

   Let's create a shopping list for bread at /groceries/mine:

   (riaktest@example.com)6> O0 = riak_object:new(<<"groceries">>, <<"mine">>, ["bread"]).
   O0 = riak_object:new(<<"groceries">>, <<"mine">>, ["bread"]).
   {r_object,<<"groceries">>,<<"mine">>,
          [{r_content,{dict,0,16,16,8,80,48,
                            {[],[],[],[],[],[],[],[],[],[],[],[],[],[],...},
                            {{[],[],[],[],[],[],[],[],[],[],[],[],...}}},
                      ["bread"]}],
          [],
          {dict,1,16,16,8,80,48,
                {[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],...},
                {{[],[],[],[],[],[],[],[],[],[],[],[],[],...}}},
          undefined}

    (riaktest@example.com)3> C:put(01, 1).
    
    Now, read the list back from the Riak server and extract the value

    (riaktest@example.com)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@example.com-riakdemo@example.com-266664",
                {1,63415509105}}],
              {dict,0,16,16,8,80,48,
                    {[],[],[],[],[],[],[],[],[],[],[],[],[],...},
                    {{[],[],[],[],[],[],[],[],[],[],[],...}}},
              undefined}}

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

     Add milk to our list of groceries and write the new value to Riak:

     (riaktest@example.com)6> %% add milk to the list
     (riaktest@example.com)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@example.com-riakdemo@example.com-266664",
            {1,63415509105}}],
          {dict,0,16,16,8,80,48,
                {[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],...},
                {{[],[],[],[],[],[],[],[],[],[],[],[],[],...}}},
          ["milk","bread"]}

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

     Finally, see what other keys are available in groceries bucket:

     (riaktest@example.com)8> C:list_keys(<<"groceries">>).
     {ok,[<<"mine">>]}