Download Riak 2.0 RC1

Replication Properties

Here, we are going to talk about how Riak distributes your data around the cluster and lets you tune your levels of consistency and availability. This has immense value and implications for your applications and is one of the features that we feel truly differentiates Riak from other technologies.

At the bottom of this page, there is a final screencast that briefly touches on how to adjust your replication levels to match your application and business needs. Before you watch, however, have a quick read of the content below.

A Primer on N, R, and W

Riak exposes replication controls to the developers in such a way that they can tune, down to the bucket level, how many copies of data they want to store, how many copes they wish to read from at a time, and how many copies must write to be considered a success. We do this using N, R, and W values.

Riak's guiding design principle is Dr. Eric Brewer's CAP Theorem. The CAP theorem defines distributed systems in terms of three desired properties: consistency, availability, and partition (i.e. failure) tolerance. The theorem states that you can only rely on having two of the three properties at any time.

Riak chooses to focus on the A and P of CAP. This choice puts Riak in the eventually consistent camp. It should be stated, however, that the window for “eventually consistent” is usually in the neighborhood of milliseconds, which can be good enough for many applications.

N Value and Replication

All data stored in Riak will be replicated to a number of nodes in the cluster according to the N value (n_val) property set on the bucket. By default, Riak chooses an n_val of 3 for you. This means that data stored in the bucket will be replicated to three different nodes, thus storing three copies. For this to be effective, you need at least three physical nodes in your cluster. The merits of this system can be demonstrated, however, using your local environment.

To change the n_val for a bucket (to something different than the default of 3), issue a PUT request to the bucket with the new n_val. If you still have your three-node Riak cluster running, try this:

curl -v -XPUT \
  -H "Content-Type: application/json" \
  -d '{"props":{"n_val":2}}' \

This will change the n_val of the bucket another_bucket to two, meaning that each piece of data in that bucket will be replicated to two partitions in the cluster.

A Word on Setting the N Value
n_val must be greater than 0 and less than or equal to the number of actual nodes in your cluster to get all the benefits of replication. We advise against modifying the n_val of a bucket after its initial creation as this may result in failed reads because the new value may not be replicated to all the appropriate partitions.

R Value and Read Failure Tolerance

With the last command, we changed the bucket's n_val to 2.

Riak allows the client to supply an R value on each direct fetch. The R value represents the number of Riak nodes that must return results for a read before the read is considered successful. This allows Riak to provide read availability even when nodes are down or laggy.

For example, in this HTTP request, the r value is set to 1:


This means that Riak will return a copy of that data if at least 1 copy is present in your cluster.

W Value and Write Fault Tolerance

Riak also allows the client to supply a W value on each update. The W value represents the number of Riak nodes that must report success before an update is considered complete. This allows Riak to provide write availability even when nodes are down or laggy.

In this PUT operation, you can see the w value set to 3.

curl -v -XPUT \
  -H "Content-type: text/plain" \
  --data-binary @story.txt \

Symbolic Consistency Names

Riak 0.12 introduced “symbolic” consistency options for R and W that can be easier to use and understand. They are:

Not submitting an R or W value is the same as sending default.

N, R and W in Action

Here is a brief screencast that shows just how the N, R, and W values function in our running three-node Riak cluster:

Tuning CAP Controls in Riak from Basho Technologies on Vimeo.