Using links

Note: This document is for the 1.x Java Client series. Linkwalking has been deprecated in Riak 2.0.

What are links in Riak and why would I use them?

Links are metadata that establish one-way relationships between objects in Riak. They can be used to loosely model graph like relationships between objects in Riak.For an introduction see our Overview on the Wiki as well as the entry in our fasttrack

Adding links to your data

Working with Links requires using the IRiakObject interface directly, as they are really metadata attached to the data you're storing.

App.java

import com.basho.riak.client.IRiakClient;
import com.basho.riak.client.IRiakObject;
import com.basho.riak.client.RiakException;
import com.basho.riak.client.RiakFactory;
import com.basho.riak.client.RiakLink;
import com.basho.riak.client.bucket.Bucket;
import com.basho.riak.client.query.WalkResult;
import java.util.Collection;
import java.util.Iterator;

public class App
{
    public static void main( String[] args ) throws RiakException
    {
        IRiakClient client = RiakFactory.httpClient();
		
        Bucket b = client.fetchBucket("test_bucket").execute();
		
        // Create some records in riak
        b.store("user_1234", "{\"name\":\"Brian Roach\"}").execute();
        b.store("user_2345","{\"name\":\"Russell Brown\"}").execute();
        b.store("user_3456","{\"name\":\"Sean Cribbs\"}").execute();

        // Retrieve an object, add links, store back to Riak
        IRiakObject myObject = b.fetch("user_1234").execute(); 
        myObject.addLink(new RiakLink("test_bucket","user_2345","friend"))
                .addLink(new RiakLink("test_bucket","user_3456","friend"));
        b.store(myObject).execute();
      
        // Retrieve the object we just stored, display the links  
        myObject = b.fetch("user_1234").execute();
        for (RiakLink link : myObject.getLinks())
        {
             System.out.println(link.getBucket() + " " + link.getKey() + " " + link.getTag());
        }

        client.shutdown();
    }
}

Link Walking

Link walking is a feature in Riak that allows link traversal to be performed in a single operation with the objects you are interested in returned to you. For complete details see the linkwalking documentation

Note 1: Link walking is a REST only operation as far as Riak’s interfaces are concerned. Link Walking in the protocol buffers Java client is a hack that issues two m/r jobs to the protocol buffers interface (the first constructs the inputs to the second by walking the links, the second returns the data). It is included to provide parity between the interfaces but should perform similarly to the REST link walking interface.

Note 2: Link walking via the Java client currently does not support conflict resolution. If it encounters siblings it will throw an exception. This will be fixed in a future release. At this time the only way to use links with siblings is via the example above.

App.java

import com.basho.riak.client.IRiakClient;
import com.basho.riak.client.IRiakObject;
import com.basho.riak.client.RiakException;
import com.basho.riak.client.RiakFactory;
import com.basho.riak.client.RiakLink;
import com.basho.riak.client.bucket.Bucket;
import com.basho.riak.client.query.WalkResult;
import java.util.Collection;
import java.util.Iterator;

public class App
{
    public static void main( String[] args ) throws RiakException
    {
        IRiakClient client = RiakFactory.httpClient();
		
        Bucket b = client.fetchBucket("test_bucket").execute();
		
        // Create some records in riak
        b.store("user_1234", "{\"name\":\"Brian Roach\"}").execute();
        b.store("user_2345","{\"name\":\"Russell Brown\"}").execute();
        b.store("user_3456","{\"name\":\"Sean Cribbs\"}").execute();

        // Retrieve an object, add links, store back to Riak
        IRiakObject myObject = b.fetch("user_1234").execute(); 
        myObject.addLink(new RiakLink("test_bucket","user_2345","friend"))
                .addLink(new RiakLink("test_bucket","user_3456","friend"));
        b.store(myObject).execute();
      
        // Walk the links
        myObject = b.fetch("user_1234").execute(); 
        WalkResult result = client.walk(myObject)
                            .addStep("test_bucket", "friend", true)
                            .addStep("test_bucket", "friend")
                            .execute();

        Iterator<Collection<IRiakObject>> i = result.iterator();
        int count = 0;
        while (i.hasNext())
        {
             count++;
             Collection<IRiakObject> c = i.next();
             for (IRiakObject o : c)
             {
                 System.out.println(count + " " + o.getValueAsString());
             }
        }
        
        client.shutdown();
    }
}