Current section
Files
Jump to
Current section
Files
doc/Riak.html
<!DOCTYPE html><html lang="en"> <head> <meta charset="utf-8"> <meta http-equiv="x-ua-compatible" content="ie=edge"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="generator" content="ExDoc v0.16.2"> <title>Riak – Riak Elixir Client v1.1.5</title> <link rel="stylesheet" href="dist/app-268c9dc719.css" /> <link rel="canonical" href="https://hexdocs.pm/riak/Riak.html" /> <script src="dist/sidebar_items-57e67b9199.js"></script> </head> <body data-type="modules"> <script>try { if(localStorage.getItem('night-mode')) document.body.className += ' night-mode'; } catch (e) { }</script> <div class="main"><button class="sidebar-toggle"> <span class="icon-menu" aria-hidden="true"></span> <span class="sr-only">Toggle Sidebar</span></button><section class="sidebar"> <a href="api-reference.html" class="sidebar-projectLink"> <div class="sidebar-projectDetails"> <h1 class="sidebar-projectName"> Riak Elixir Client </h1> <h2 class="sidebar-projectVersion"> v1.1.5 </h2> </div> </a> <div class="sidebar-search"> <span class="icon-search" aria-hidden="true"></span> <input type="text" class="sidebar-searchInput" placeholder="search" aria-label="Search" autocomplete="off" /> </div> <ul class="sidebar-listNav"> <li><a id="extras-list" href="#full-list">Pages</a></li> <li><a id="modules-list" href="#full-list">Modules</a></li> </ul> <div class="gradient"></div> <ul id="full-list" class="sidebar-fullList"></ul></section><section class="content"> <div class="content-outer"> <div id="content" class="content-inner"> <h1> <small class="visible-xs">Riak Elixir Client v1.1.5</small> Riak <a href="https://github.com/drewkerrigan/riak-elixir-client/blob/master/lib/riak.ex#L1" title="View Source" class="view-source" rel="help"> <span class="icon-code" aria-hidden="true"></span> <span class="sr-only">View Source</span> </a> </h1> <section id="moduledoc"> <h1>Riak Elixir Client</h1><p><a href="https://travis-ci.org/drewkerrigan/riak-elixir-client"><img src="https://travis-ci.org/drewkerrigan/riak-elixir-client.svg?branch=master" alt="Build Status"/></a></p><p>A Riak client written in Elixir. Now includes connection pooling with <a href="http://github.com/seth/pooler">pooler</a> and a variety of other improvements from <a href="https://github.com/edgurgel/riex">riex</a>.</p><h2 id="module-setup" class="section-heading"> <a href="#module-setup" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a> Setup</h2><h3 id="module-prerequisites" class="section-heading"> <a href="#module-prerequisites" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a> Prerequisites</h3><ul><li>Riak 2.0+</li><li>Elixir 1.0+</li></ul><h4>In an Elixir application</h4><p>Add the following to mix.exs</p><pre><code class="elixir">...def application do [ applications: [ :riak ]]end...defp deps do [ {:riak, "~> 1.0"} ]end...</code></pre><h2 id="module-usage" class="section-heading"> <a href="#module-usage" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a> Usage</h2><h3 id="module-establishing-a-riak-connection" class="section-heading"> <a href="#module-establishing-a-riak-connection" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a> Establishing a Riak connection</h3><pre><code class="elixir">{:ok, pid} = Riak.Connection.start_link('127.0.0.1', 8087) # Default values</code></pre><h3 id="module-connection-pooling" class="section-heading"> <a href="#module-connection-pooling" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a> Connection Pooling</h3><p>Most functions in this module can be called by passing the pid of the established connection or using a pool of connections (provided by pooler). Define pools by using the group <code class="inline">riak</code>. Following is an example <code class="inline">config/config.exs</code>:</p><pre><code class="elixir">[pooler: [pools: [ [ name: :riaklocal1, group: :riak, max_count: 10, init_count: 5, start_mfa: {Riak.Connection, :start_link, []} ], [ name: :riaklocal2, group: :riak, max_count: 15, init_count: 2, start_mfa: {Riak.Connection, :start_link, ['127.0.0.1', 9090]} ] ]]]</code></pre><p>For an example using this functionality with a local Riak instance, check <a href="https://github.com/drewkerrigan/riak-elixir-client/blob/master/config/config.exs"><code class="inline">config/config.exs</code></a>. More information about Elixir configuration can be found on [http://elixir-lang.org(http://elixir-lang.org)]: <a href="http://elixir-lang.org/getting_started/mix_otp/10.html#toc_6">Application environment and configuration</a>.</p><p>Once a pool configuration is properly defined in a project, calls to Riak can omit the pid. For example:</p><p>This call uses a pid from the pool of connections provided by pooler:</p><pre><code class="elixir">Riak.delete("user", key)</code></pre><p>This call requires a pid obtained by first calling <code class="inline">Riak.Connection.start_link</code>:</p><pre><code class="elixir">Riak.delete(pid, "user", key)</code></pre><h3 id="module-save-a-value" class="section-heading"> <a href="#module-save-a-value" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a> Save a value</h3><pre><code class="elixir">o = Riak.Object.create(bucket: "user", key: "my_key", data: "Han Solo")Riak.put(pid, o)</code></pre><h3 id="module-find-an-object" class="section-heading"> <a href="#module-find-an-object" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a> Find an object</h3><pre><code class="elixir">o = Riak.find(pid, "user", "my_key")</code></pre><h3 id="module-update-an-object" class="section-heading"> <a href="#module-update-an-object" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a> Update an object</h3><pre><code class="elixir">o = %{o | data: "Something Else"}Riak.put(pid, o)</code></pre><h3 id="module-delete-an-object" class="section-heading"> <a href="#module-delete-an-object" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a> Delete an object</h3><p>Using key</p><pre><code class="elixir">Riak.delete(pid, "user", key)</code></pre><p>Using object</p><pre><code class="elixir">Riak.delete(pid, o)</code></pre><h3 id="module-datatypes" class="section-heading"> <a href="#module-datatypes" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a> Datatypes</h3><p>Riak Datatypes (a.k.a. CRDTs) are avaiable in <a href="http://basho.com/introducing-riak-2-0/">Riak versions 2.0</a> and greater. The types included are: maps, sets, counters, registers and flags.</p><h4>Setup</h4><p>Datatypes require the use of bucket-types. Maps, sets, and counters can be used as top-level bucket-type datatypes; Registers and flags may only be used within maps.</p><p>The following examples assume the presence of 3 datatype enabled bucket-types. You can create these bucket-types by running the following commands on a single Riak node in your cluster:</p><p>Bucket-Type: <code class="inline">counters</code></p><pre><code class="elixir">riak-admin bucket-type create counters '{"props":{"datatype":"counter"}}'riak-admin bucket-type activate counters</code></pre><p>Bucket-Type: <code class="inline">sets</code></p><pre><code class="elixir">riak-admin bucket-type create sets '{"props":{"datatype":"set"}}'riak-admin bucket-type activate sets</code></pre><p>Bucket-Type: <code class="inline">maps</code></p><pre><code class="elixir">riak-admin bucket-type create maps '{"props":{"datatype":"map"}}'riak-admin bucket-type activate maps</code></pre><h4>Counters</h4><p>Create a counter (<code class="inline">alias Riak.CRDT.Counter</code>):</p><pre><code class="elixir">Counter.new |> Counter.increment |> Counter.increment(2) |> Riak.update("counters", "my_counter_bucket", "my_key")</code></pre><p>Fetch a counter:</p><pre><code class="elixir">counter = Riak.find("counters", "my_counter_bucket", "my_key") |> Counter.value</code></pre><p><code class="inline">counter</code> will be 3.</p><p><strong><em>NOTE</em></strong>: “Counter drift” is a possibility that needs to be accounted for with any distributed system such as Riak. The problem can manifest itself during failure states in either your applicaiton or Riak itself. If an increment operation fails from the client’s point of view, there is not sufficient information available to know whether or not that call made it to zero or all of the replicas for that counter object. As such, if the client attempts to retry the increment after recieving something like a error code 500 from Riak, that counter object is at risk of drifting positive. Similarly if the client decides not to retry, that counter object is at risk of drifting negative.</p><p>For these reasons, counters are only suggested for use-cases that can handle some (albeit small) amount of counter drift. Good examples of appropriate use-cases are: Facebook likes, Twitter retweet counts, Youtube view counts, etc. Some examples of poor use-cases for Riak counters are: bank account balances, anything related to money. It is possible to implement these types of solutions using Riak, but more client side logic is necessary. For an example of a client-side ledger with tunable retry options, check <a href="https://github.com/drewkerrigan/riak-ruby-ledger">github.com/drewkerrigan/riak-ruby-ledger</a>. Another approach could be the client-side implementation of a HAT (Highly Available Transaction) algorithm.</p><h4>Sets</h4><p>Create a set (<code class="inline">alias Riak.CRDT.Set</code>):</p><pre><code class="elixir">Set.new |> Set.put("foo") |> Set.put("bar") |> Riak.update("sets", "my_set_bucket", "my_key")</code></pre><p>And fetch the set:</p><pre><code class="elixir">set = Riak.find("sets", "my_set_bucket", "my_key") |> Set.value</code></pre><p>Where <code class="inline">set</code> is an <code class="inline">orddict</code>.</p><h4>Maps</h4><p>Maps handle binary keys with any other datatype (map, set, flag, register and counter).</p><p>Create a map (<code class="inline">alias Riak.CRDT.Map</code>):</p><pre><code class="elixir">register = Register.new("some string")flag = Flag.new |> Flag.enableMap.new |> Map.put("k1", register) |> Map.put("k2", flag) |> Riak.update("maps", "my_map_bucket", "map_key")</code></pre><p>And fetch the map:</p><pre><code class="elixir">map = Riak.find("maps", "my_map_bucket", key) |> Map.value</code></pre><p>Where <code class="inline">map</code> is an <code class="inline">orddict</code>.</p><h2 id="module-examples" class="section-heading"> <a href="#module-examples" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a> Examples</h2><p>Check the <code class="inline">examples/</code> directory for a few example elixir applications using the riak client.</p><p>For more functionality, check <code class="inline">test/</code> directory.</p><h2 id="module-tests" class="section-heading"> <a href="#module-tests" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a> Tests</h2><pre><code class="elixir">MIX_ENV=test mix do deps.get, test</code></pre><h2 id="module-license" class="section-heading"> <a href="#module-license" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a> License</h2><pre><code class="elixir">Copyright 2015 Drew Kerrigan.Copyright 2014 Eduardo Gurgel.Licensed under the Apache License, Version 2.0 (the "License");you may not use this file except in compliance with the License.You may obtain a copy of the License athttp://www.apache.org/licenses/LICENSE-2.0Unless required by applicable law or agreed to in writing, softwaredistributed under the License is distributed on an "AS IS" BASIS,WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.See the License for the specific language governing permissions andlimitations under the License.</code></pre> </section> <section id="summary" class="details-list"> <h1 class="section-heading"> <a class="hover-link" href="#summary"> <span class="icon-link" aria-hidden="true"></span> <span class="sr-only">Link to this section</span> </a> Summary </h1> <div class="summary-functions summary"> <h2> <a href="#functions">Functions</a> </h2> <div class="summary-row"> <div class="summary-signature"> <a href="#delete/1">delete(obj)</a> </div> </div><div class="summary-row"> <div class="summary-signature"> <a href="#delete/2">delete(pid, obj)</a> </div> <div class="summary-synopsis"><p>Delete the key/value</p></div> </div><div class="summary-row"> <div class="summary-signature"> <a href="#delete/3">delete(pid, bucket, key)</a> </div> </div><div class="summary-row"> <div class="summary-signature"> <a href="#delete/4">delete(pid, type, bucket, key)</a> </div> </div><div class="summary-row"> <div class="summary-signature"> <a href="#find/2">find(bucket, key)</a> </div> </div><div class="summary-row"> <div class="summary-signature"> <a href="#find/3">find(pid, bucket, key)</a> </div> <div class="summary-synopsis"><p>Get bucket-type/bucket/key from the server</p></div> </div><div class="summary-row"> <div class="summary-signature"> <a href="#find/4">find(pid, type, bucket, key)</a> </div> <div class="summary-synopsis"><p>Fetches the representation of a convergent datatype from Riak</p></div> </div><div class="summary-row"> <div class="summary-signature"> <a href="#ping/0">ping()</a> </div> </div><div class="summary-row"> <div class="summary-signature"> <a href="#ping/1">ping(pid)</a> </div> <div class="summary-synopsis"><p>Ping the server</p></div> </div><div class="summary-row"> <div class="summary-signature"> <a href="#put/1">put(obj)</a> </div> </div><div class="summary-row"> <div class="summary-signature"> <a href="#put/2">put(pid, obj)</a> </div> <div class="summary-synopsis"><p>Put the metadata/value in the object under bucket-type/bucket/key</p></div> </div><div class="summary-row"> <div class="summary-signature"> <a href="#resolve/3">resolve(bucket, key, index)</a> </div> </div><div class="summary-row"> <div class="summary-signature"> <a href="#resolve/4">resolve(pid, bucket, key, index)</a> </div> <div class="summary-synopsis"><p>Picks the sibling to “win” over the other siblings via a list index</p></div> </div><div class="summary-row"> <div class="summary-signature"> <a href="#update/4">update(datatype, type, bucket, key)</a> </div> </div><div class="summary-row"> <div class="summary-signature"> <a href="#update/5">update(pid, datatype, type, bucket, key)</a> </div> <div class="summary-synopsis"><p>Updates the convergent datatype in Riak with localmodifications stored in the container type</p></div> </div> </div> </section> <section id="functions" class="details-list"> <h1 class="section-heading"> <a class="hover-link" href="#functions"> <span class="icon-link" aria-hidden="true"></span> <span class="sr-only">Link to this section</span> </a> Functions </h1> <div class="detail" id="delete/1"> <div class="detail-header"> <a href="#delete/1" class="detail-link" title="Link to this function"> <span class="icon-link" aria-hidden="true"></span> <span class="sr-only">Link to this function</span> </a> <span class="signature">delete(obj)</span> <a href="https://github.com/drewkerrigan/riak-elixir-client/blob/master/lib/riak.ex#L343" class="view-source" rel="help" title="View Source"> <span class="icon-code" aria-hidden="true"></span> <span class="sr-only">View Source</span> </a> </div> <section class="docstring"> </section></div><div class="detail" id="delete/2"> <div class="detail-header"> <a href="#delete/2" class="detail-link" title="Link to this function"> <span class="icon-link" aria-hidden="true"></span> <span class="sr-only">Link to this function</span> </a> <span class="signature">delete(pid, obj)</span> <a href="https://github.com/drewkerrigan/riak-elixir-client/blob/master/lib/riak.ex#L344" class="view-source" rel="help" title="View Source"> <span class="icon-code" aria-hidden="true"></span> <span class="sr-only">View Source</span> </a> </div> <section class="docstring"> <p>Delete the key/value.</p> </section></div><div class="detail" id="delete/3"> <div class="detail-header"> <a href="#delete/3" class="detail-link" title="Link to this function"> <span class="icon-link" aria-hidden="true"></span> <span class="sr-only">Link to this function</span> </a> <span class="signature">delete(pid, bucket, key)</span> <a href="https://github.com/drewkerrigan/riak-elixir-client/blob/master/lib/riak.ex#L345" class="view-source" rel="help" title="View Source"> <span class="icon-code" aria-hidden="true"></span> <span class="sr-only">View Source</span> </a> </div> <section class="docstring"> </section></div><div class="detail" id="delete/4"> <div class="detail-header"> <a href="#delete/4" class="detail-link" title="Link to this function"> <span class="icon-link" aria-hidden="true"></span> <span class="sr-only">Link to this function</span> </a> <span class="signature">delete(pid, type, bucket, key)</span> <a href="https://github.com/drewkerrigan/riak-elixir-client/blob/master/lib/riak.ex#L345" class="view-source" rel="help" title="View Source"> <span class="icon-code" aria-hidden="true"></span> <span class="sr-only">View Source</span> </a> </div> <section class="docstring"> </section></div><div class="detail" id="find/2"> <div class="detail-header"> <a href="#find/2" class="detail-link" title="Link to this function"> <span class="icon-link" aria-hidden="true"></span> <span class="sr-only">Link to this function</span> </a> <span class="signature">find(bucket, key)</span> <a href="https://github.com/drewkerrigan/riak-elixir-client/blob/master/lib/riak.ex#L286" class="view-source" rel="help" title="View Source"> <span class="icon-code" aria-hidden="true"></span> <span class="sr-only">View Source</span> </a> </div> <section class="docstring"> </section></div><div class="detail" id="find/3"> <div class="detail-header"> <a href="#find/3" class="detail-link" title="Link to this function"> <span class="icon-link" aria-hidden="true"></span> <span class="sr-only">Link to this function</span> </a> <span class="signature">find(pid, bucket, key)</span> <a href="https://github.com/drewkerrigan/riak-elixir-client/blob/master/lib/riak.ex#L306" class="view-source" rel="help" title="View Source"> <span class="icon-code" aria-hidden="true"></span> <span class="sr-only">View Source</span> </a> </div> <section class="docstring"> <p>Get bucket-type/bucket/key from the server.</p> </section></div><div class="detail" id="find/4"> <div class="detail-header"> <a href="#find/4" class="detail-link" title="Link to this function"> <span class="icon-link" aria-hidden="true"></span> <span class="sr-only">Link to this function</span> </a> <span class="signature">find(pid, type, bucket, key)</span> <a href="https://github.com/drewkerrigan/riak-elixir-client/blob/master/lib/riak.ex#L306" class="view-source" rel="help" title="View Source"> <span class="icon-code" aria-hidden="true"></span> <span class="sr-only">View Source</span> </a> </div> <section class="docstring"> <p>Fetches the representation of a convergent datatype from Riak.</p><p>TODO: In the current implementation, it’s very easy to confuse workingwith regular k/v objects and datatypes. Clarify so that these aren’tconflated by assuming that any object with a type is a datatype.</p> </section></div><div class="detail" id="ping/0"> <div class="detail-header"> <a href="#ping/0" class="detail-link" title="Link to this function"> <span class="icon-link" aria-hidden="true"></span> <span class="sr-only">Link to this function</span> </a> <span class="signature">ping()</span> <a href="https://github.com/drewkerrigan/riak-elixir-client/blob/master/lib/riak.ex#L245" class="view-source" rel="help" title="View Source"> <span class="icon-code" aria-hidden="true"></span> <span class="sr-only">View Source</span> </a> </div> <section class="docstring"> </section></div><div class="detail" id="ping/1"> <div class="detail-header"> <a href="#ping/1" class="detail-link" title="Link to this function"> <span class="icon-link" aria-hidden="true"></span> <span class="sr-only">Link to this function</span> </a> <span class="signature">ping(pid)</span> <a href="https://github.com/drewkerrigan/riak-elixir-client/blob/master/lib/riak.ex#L245" class="view-source" rel="help" title="View Source"> <span class="icon-code" aria-hidden="true"></span> <span class="sr-only">View Source</span> </a> </div> <section class="docstring"> <p>Ping the server.</p> </section></div><div class="detail" id="put/1"> <div class="detail-header"> <a href="#put/1" class="detail-link" title="Link to this function"> <span class="icon-link" aria-hidden="true"></span> <span class="sr-only">Link to this function</span> </a> <span class="signature">put(obj)</span> <a href="https://github.com/drewkerrigan/riak-elixir-client/blob/master/lib/riak.ex#L250" class="view-source" rel="help" title="View Source"> <span class="icon-code" aria-hidden="true"></span> <span class="sr-only">View Source</span> </a> </div> <section class="docstring"> </section></div><div class="detail" id="put/2"> <div class="detail-header"> <a href="#put/2" class="detail-link" title="Link to this function"> <span class="icon-link" aria-hidden="true"></span> <span class="sr-only">Link to this function</span> </a> <span class="signature">put(pid, obj)</span> <a href="https://github.com/drewkerrigan/riak-elixir-client/blob/master/lib/riak.ex#L250" class="view-source" rel="help" title="View Source"> <span class="icon-code" aria-hidden="true"></span> <span class="sr-only">View Source</span> </a> </div> <section class="docstring"> <p>Put the metadata/value in the object under bucket-type/bucket/key.</p> </section></div><div class="detail" id="resolve/3"> <div class="detail-header"> <a href="#resolve/3" class="detail-link" title="Link to this function"> <span class="icon-link" aria-hidden="true"></span> <span class="sr-only">Link to this function</span> </a> <span class="signature">resolve(bucket, key, index)</span> <a href="https://github.com/drewkerrigan/riak-elixir-client/blob/master/lib/riak.ex#L331" class="view-source" rel="help" title="View Source"> <span class="icon-code" aria-hidden="true"></span> <span class="sr-only">View Source</span> </a> </div> <section class="docstring"> </section></div><div class="detail" id="resolve/4"> <div class="detail-header"> <a href="#resolve/4" class="detail-link" title="Link to this function"> <span class="icon-link" aria-hidden="true"></span> <span class="sr-only">Link to this function</span> </a> <span class="signature">resolve(pid, bucket, key, index)</span> <a href="https://github.com/drewkerrigan/riak-elixir-client/blob/master/lib/riak.ex#L331" class="view-source" rel="help" title="View Source"> <span class="icon-code" aria-hidden="true"></span> <span class="sr-only">View Source</span> </a> </div> <section class="docstring"> <p>Picks the sibling to “win” over the other siblings via a list index.</p> </section></div><div class="detail" id="update/4"> <div class="detail-header"> <a href="#update/4" class="detail-link" title="Link to this function"> <span class="icon-link" aria-hidden="true"></span> <span class="sr-only">Link to this function</span> </a> <span class="signature">update(datatype, type, bucket, key)</span> <a href="https://github.com/drewkerrigan/riak-elixir-client/blob/master/lib/riak.ex#L264" class="view-source" rel="help" title="View Source"> <span class="icon-code" aria-hidden="true"></span> <span class="sr-only">View Source</span> </a> </div> <section class="docstring"> </section></div><div class="detail" id="update/5"> <div class="detail-header"> <a href="#update/5" class="detail-link" title="Link to this function"> <span class="icon-link" aria-hidden="true"></span> <span class="sr-only">Link to this function</span> </a> <span class="signature">update(pid, datatype, type, bucket, key)</span> <a href="https://github.com/drewkerrigan/riak-elixir-client/blob/master/lib/riak.ex#L264" class="view-source" rel="help" title="View Source"> <span class="icon-code" aria-hidden="true"></span> <span class="sr-only">View Source</span> </a> </div> <section class="docstring"> <p>Updates the convergent datatype in Riak with localmodifications stored in the container type.</p> </section></div> </section> <footer class="footer"> <p> <span class="line"> Built using <a href="https://github.com/elixir-lang/ex_doc" title="ExDoc" rel="help" target="_blank">ExDoc</a> (v0.16.2), </span> <span class="line"> designed by <a href="https://twitter.com/dignifiedquire" target="_blank" title="@dignifiedquire">Friedel Ziegelmayer</a>. </span> </p> <button class="night-mode-toggle"><span class="sr-only">Switch theme</span></button> </footer> </div> </div></section></div> <script src="dist/app-4988ddd06b.js"></script> </body></html>