Essential Couchbase APIs

Section 1

Connection Management

by: Don Pinto

Connecting to Couchbase Server

private static CouchbaseClient client;
new CouchbaseClient(urls, bucket, password)

Parameters:

String urls	Linked list containing one or more URLs as strings
String username	Username for Couchbase bucket
String password	Password for Couchbase bucket

Disconnecting from Couchbase Server

client.shutdown();
client.shutdown(long TimeValue, TimeUnit);

Parameters:

long TimeValue	Wait value until any outstanding queued work is completed
enum TimeUnit	TimeUnit.SECONDS, TImeUnit.MINUTES

Section 2

Store Operations

Add Operations

The add method adds a value to the database with the specified key, but will fail if the key already exists in the database.

client.add(key, expiry, value [, persistTo] ,[ replicateTo] )
client.add(key, expiry, value, transcoder)

Replace Operations

The replace method will replace an existing key with a new value but will fail if the key does not exist in the database.

client.replace(key, expiry, value [, persistTo] ,[ replicateTo])
client.replace(key, expiry, value, transcoder)

Set Operations (Durability Requirements)

The set method stores a value to the database with a specified key.

client.set(key, expiry, value [, persistTo] ,[ replicateTo])
client.set(key, expiry, value, transcoder)

Parameters:

String key	Key used to reference the value.
int expiry	Expiry time for the key in seconds. Values larger than 302460*60 seconds (30 days) are interpreted as absolute times (from the epoch)
Object value	Value to be stored
enum persistTo	The amount of nodes the item should be persisted to before returning. - MASTER/ONE, TWO, THREE or FOUR nodes
enum replicateTo	The amount of nodes the item should be replicated to before returning ZERO, ONE, TWO or THREE nodes
Transcoder<T> transcoder	Transcoder class to be used to serialize values

Section 3

Retrieve Operations

There are several different flavors of retrieve operations in the Couchbase Server 1.1 Java SDK

client.asyncGet(key)
client.asyncGet(key, transcoder)
client.asyncGetAndLock(key, expiry)
client.asyncGetAndLock(key, expiry, transcoder)
client.asyncGetAndTouch(key, expiry)
client.asyncGetAndTouch(key, expiry, transcoder)
client.asyncGetBulk(keycollection)
client.asyncGetBulk(keyn)
client.asyncGetBulk(transcoder, keyn)
client.asyncGetBulk(keycollection, transcoder)
client.asyncGet(key, transcoder)
client.get(key)
client.getAndTouch(key, expiry)
client.getAndTouch(key, expiry, transcoder)
client.getBulk(keycollection)
client.getBulk(keyn)
client.getBulk(transcoder, keyn)
client.getBulk(keycollection, transcoder)
client.get(key, transcoder)
client.asyncGetLock(key [,getl-expiry])
client.asyncGetLock(key [,getl-expiry], transcoder)
client.getAndLock(key, getl-expiry)
client.getAndLock(key, getl-expiry, transcoder)
client.asyncGets(key)
client.asyncGets(key, transcoder)
client.gets(key)
client.gets(key, transcoder)
client.unlock(key, casunique)

Parameters:

String key	Key used to reference the value. The key cannot contain control characters or whitespace
int expiry	Expiry time for the key in seconds. Values larger than 302460*60 seconds (30 days) are interpreted as absolute times (from the epoch)
Collection<String> keycollection	One or more keys used to reference a value
String… keyn	One or more keys used to reference a value
long casunique	Unique value used to identify a key/value combination
int getl-expiry	Expiry time in seconds for lock: Default 15, Maximum30
Transcoder<T> transcoder	Transcoder class to be used to serialize values

For more information to create design documents using Java or for cluster management operations, take a look at http://www.couchbase.com/develop/java/current

Section 4

Update Operations

The update methods support different methods of updating and changing existing information within Couchbase Server.

client.append(casunique, key, value)
client.append(casunique, key, value, transcoder)
client.asyncCAS(key, casunique, value)
client.asyncCAS(key, casunique, expiry, value, transcoder)
client.asyncCAS(key, casunique, value, transcoder)
client.cas(key, casunique, value [, persistTo] ,[ replicateTo])
client.cas(key, casunique, expiry, value, transcoder)
client.cas(key, casunique, value, transcoder)
client.asyncDecr(key, offset)
client.decr(key, offset)
client.decr(key, offset, default)
client.decr(key, offset, default, expiry)
client.delete(key [, persistTo] ,[ replicateTo])
client.asyncIncr(key, offset)
client.incr(key, offset)
client.incr(key, offset, default)
client.incr(key, offset, default, expiry)
client.prepend(casunique, key, value)
client.prepend(casunique, key, value, transcoder)
client.touch(key, expiry)

Parameters:

long casunique	Unique value used to identify a key/value combination
String key	Key used to reference the value. The key cannot contain control characters or whitespace
int offset	Integer offset value to increment / decrement (default is 1)
int default	Default value to increment/decrement if key does not exist
int expiry	Expiry time for the key in seconds. Values larger than 302460*60 seconds (30 days) are interpreted as absolute times (from the epoch)
Object value	Value to be stored
enum persistTo	The amount of nodes the item should be persisted to before returning. - MASTER/ONE, TWO, THREE or FOUR nodes
enum replicateTo	The amount of nodes the item should be replicated to before returning ZERO, ONE, TWO or THREE nodes
Transcoder<T> transcoder	Transcoder class to be used to serialize values

Section 5

Query Operations

With Couchbase Server 2.0, you can add the power of views and querying those views to your applications.

Create a view object to be used when querying a view:

client.getView(ddocname, viewname)

Parameters:

String ddocname	Design document name
String viewname	View name within a design document

Then create a new query object to be used when querying the view:

Query.new()
Query query = new Query();

Once, the view and query objects are available, the results of the server view can be accessed using

client.query(view, query)

Parameters:

View view	View object associated with a server view
Query query	Query object associated with a server view

Before accessing the view, a list of options can be set with the query object:

query.setKey(String key)to set the key to query in the view

query.setKey(ComplexKey key)to set the key to query in the view

query.setRangeStart(String startKey)to set the starting key

query.setRangeStart(ComplexKey startKey)to set the key to query in the view

query.setKey(String key)to set the starting key

query.setRangeEnd(String endKey)to set the key to query in the view

query.setRangeEnd(ComplexKey endKey)to set the ending key

query.setRange(String startKey, String endKey)to set a range

query.setRange(ComplexKey startKey, ComplexKey endKey)

query.setDescending(boolean descending)to sort in descending order

query.setIncludeDocs(boolean include)to include the JSON doc

query.setReduce(boolean reduce)execute the reduce function

query.setStale(Stale reduce)set to OK will not refresh the view even if it is stale, set to UPDATE_AFTER will update the view after the stale result is returned, FALSE will update the view and return the latest results.

The format of the returned information of the query method is : ViewResponse or any of the other inherited objects such as ViewResponseWithDocs, ViewResponseNoDocs, ViewResponseReduced

The ViewResponse method provides an iterator() method for iterating through the rows as a ViewRow interface. The ViewResponse method also provides a getMap() method where the result is available as a map.

Ruby

Section 6

Connecting to Couchbase

client = Couchbase.connect(url, options = {});
client = Couchbase.connect(options = {});

Hash Parameters:

:hostname	IP address for Couchbase Node (String)
:bucket	Bucket name (String) [optional, default is ‘default’]
:password	SASL password for Bucket (String) [optional]
:nodelist	Array of IP’s for Couchbase Nodes ([String]) like [’12.34.56.78:8091’, ’12.34.56.79’]

client = Couchbase.bucket

Is a shared single instance of the Couchbase connection object in the Couchbase-model gem and can be used once connected, or when settings are specified in /config/couchbase.yml which connects on Rails startup.

Section 7

Writing and Updating Data

Key

Keys can be any UTF-8 string up to 250 chars long. Metadata for keys is 125 bytes + length of key and always kept in RAM.

Value

If Value is a Hash, it is converted to JSON for Documents and decoded back to a Hash on Retrieve. Value can also be Strings, Binary Strings, Integers (for Atomic Counters, must be positive Integer), and Decimal. If Value is a JSON String you will get back a JSON String (like any other string) that is not parsed by JSON decoder into a Hash.

Add Operations

The add method adds a value to the database with the specified key, but will fail (Couchbase::Error::KeyExists) if the key already exists in the database.

client.add(key, value, options = {})
client.add[key, options = {}] = value

Replace Operations

The replace method will replace an existing key with a new value but will fail (Couchbase::Error::NotFound) if the key does not exist in the database

client.replace(key, value, options = {})
client.replace[key, options = {}] = value

Set Operations

The set method stores a value to the database with a specified key, overwriting existing content if it exists (see add/replace above).

client.set(key, value, options = {})
client.set[key, options = {}] = value

options:

:ttl	[Fixnum, Integer] Time to Live in seconds [optional]
:flags	[Fixnum] Flags that you want to store/retrieve [optional]
:cas	[Fixnum] Optimistic locking for update control, must match the document cas in Couchbase to succeed
:format	[:document, :plain, :marshal] Explicit format setting, :plain for strings, :document for Hash(JSON), :marshal to use Marshal.load and Marshal.dump; format is :document by default

Section 8

Writing Data (Continued)

Asynchronous Store Example (Block)

client.run do
  client.add("foo" => "val1", "bar" => "val2") do |ret|
    ret.operation  #=> :add
    ret.success?   #=> true
    ret.keys       #=> "foo", "bar" in separate calls
    ret.cas              
    ret.flags           
  end
end

Section 9

Reading Data

The Get method is a very versatile method, allowing for both optimistic and pessimistic locking, multiple gets, and hash like syntax.

Simple Get Operations

val = client.get(key, options = {})
val = client["key"]

Extended Tuple Get Operations

val, flags, cas = client.get(key, :extended => true)
val, flags, cas = client["key", :extended => true]

Multi-Get Operations

val_array = client.get(keys)
val_hash = client.get(keys, :assemble_hash => true)

options:

:extended	[String, Symbol] Key used to reference the value
:quiet	[true, false] Return nil for missing keys default, or false to Return Couchbase::Error::KeyNotFound for missing key
:ttl	[Fixnum, Integer] Get and Touch, :ttl will also reset the TTL at the same time as the get (seconds)
:lock	Lock the document, true to use default lock timeout, or integer for number of seconds to lock
:format	[:document, :plain, :marshal] Explicit format setting, :plain for strings, :document for Hash(JSON), :marshal to use Marshal.load and Marshal.dump
:assemble_hash	[true, false] For Multi-Get, will return a Hash keyed on the document keys instead of default of array

Section 10

Getting Stats From Couchbase

Obtain stats from all servers for the connection (bucket)

client.stats
client.stats["stats"]

To Fetch Memory Stats

client.stats(:memory)

Parameters:

stat

Individual stat string (i.e. "curr_items")

Section 11

Deleting and Updating Data

For Deleting of Keys/Values

client.delete(key)

Atomic Counter Operations

Atomic Counters are only atomic per cluster, but are useful for many different patterns and numeric data. They are unsigned positive integers. You cannot use atomic operations on floats or objects or arrays.

client.incr(key, delta, options = {})
client.decr(key, delta, options = {})

options:

delta	[Fixnum] Amount to incr/decr, default is 1, can be up to 64 bits
:create	[true, false] If set to true, if key doesn’t exist, initializes to zero but doesn’t increment, can be combined with :initial
:initial	[Fixnum, Unsigned Integer] Sets initial value if key doesn’t exist, doesn’t increment the initial value!
:extended	[true, false] Returns [value, cas] tuple instead of just value
:ttl	[Fixnum, Integer] Sets TTL, doesn’t alter existing TTL, will only be applied to a new item created via :create and/or :initial

Touch Operations

Reset the TTL expiration on one or more keys explicitly with the touch command, can also be done with a get command.

client.touch(key, ttl)
client.touch({"key1"=> ttl1, "key2" => ttl2})

Durability Requirements

Observe the state of the keys on all the nodes or using :replicated and :persisted it allows to set up the waiting rule

client.observe(*keys, options = {})
client.observe_and_wait(*keys, options = {})

Non-JSON Operations

For non-json values, prepend and append can concatenate to existing values accordingly. Defaults to:plain format for encoder/decoder.

client.prepend(key, value)
client.append(key, value)

Couchbase Website:http://www.couchbase.com

Couchbase Blog: http://blog.couchbase.com

Developer SDKs: http://www.couchbase.com/develop

Download: http://www.couchbase.com/download

Autodocs: http://www.couchbase.com/autodocs

Section 12

Querying Data

With Couchbase Server 2.0, you can create Indexes through Map/Reduce functions. http://www.couchbase.com/docs/couchbase-manual-2.0/couchbase-views.html

Create Design Doc Object

Refer to the design_doc by name, the Views are an array of view names, as well as functions defined by name

ddoc = client.design_docs['design_doc_name']
ddoc.views   #=> ['view_name', 'view_name_2', …]

Use dot notation for accessing the view by your defined view name and pass in options for query parameters:

ddoc.view_name(params = {}).each do |doc|
  # do stuff with docs
end

options:

:include_docs	[true, false] Perform get with key on rows returned with key (non-reduce)
:descending	[true, false], reverse order of returned rows
:key	[String, Fixnum, Hash, Array] Return only rows with index key that match :key, simple and compound keys can be used (JSON encoded)
:keys	[Array] Return only rows that match array of keys (see :key), both simple and compound keys (JSON encoded)
:startkey	[String, Fixnum, Hash, Array] Range query from :start_key to :end_key (JSON encoded)
:endkey	[String, Fixnum, Hash, Array] Range query from :start_key to :end_key (JSON encoded)
:startkey_docid	[String] Document id to start with (to allow pagination for duplicate startkeys
:endkey_docid	[String] Last document id to include in the output (to allow pagination for duplicate startkeys)
:inclusive_end	[true, false] If true, specificed end key is included in result
:limit	[Fixnum] Limit the results returned
:skip	[Fixnum] Skip a number of results before returning (can be used with :limit to page through results)
:reduce	[true, false] Perform the reduce function defined in the view. If there is no reduce defined default is false and setting to true will return error.
:group	[true, false] Groups results using the view defined reduce function
:group_level	[Fixnum] Sets the grouping level for compound keys
:stale	[:false, :update_after, :ok] Consistency setting, :false initiates Design Document to update indexes before returning results, :update_after updates indexes after returning results, :ok doesn’t trigger indexers and returns existing indexed results
:body	[Hash] Takes same parameters as options but does it as a POST if the query has many parameters or is complex
:on_error	[:continue, :stop] Behavior setting if an error occurs during view query

.NET

Section 13

Connecting to Couchbase

var config = new CouchbaseClientConfiguration();
config.Urls.Add(new Uri("http://

   :8091/pools/"));
config.Bucket = "

    ";
var client = new CouchbaseClient(config);

Section 14

Writing Data

Based on the storemode, Store and ExecuteStore may be an Add, Replace or Set operation. Execute API's return the operation result.

Store Operations

object.Store(storemode, key, value)
object.Store(storemode, key, value, validfor)
object.Store(storemode, key, value, expiresat)

ExecuteStore Operations

object.ExecuteStore(storemode, key, value)
object.ExecuteStore(storemode, key, value, expiresat)
object.ExecuteStore(storemode, key, value, validfor)
object.ExecuteStore(storemode, key, value, ReplicateTo)
object.ExecuteStore(storemode, key, value, PersistTo)
object.ExecuteStore(storemode, key, value, PersistTo, ReplicateTo)

Parameters:

String key	Key used to reference the value.
Object value	Value to be stored
StoreMode storemode	Storage mode for a given key/value pair – can be Add, Replace or Set.
Timespan validfor	Expiry timespan (in seconds) for key
DateTime expiresat	Explicit expiry time for key
Enum PersistsTo	Persist to one or more replicas. Master plus one, two, three replicas
Enum ReplicateTo	Replicate to zero or more replicas

Section 15

Reading Data

Get Operations

Get a value from Couchbase Sever

object.Get(key, expiry)
object.ExecuteGet(key, expiry)
object.ExecuteGet(key)
object.ExecuteGet(keyarray)
object.Get(key)
object.Get(keyarray)
object.GetWithCas(key)

Parameters:

String key	Key used to reference the value. The key cannot contain control characters or whitespace
object expiry	Expiry time for the key in seconds. Values larger than 302460*60 seconds (30 days) are interpreted as absolute times (from the epoch)
List <string> keyarray	Array of keys used to reference one or more values

Section 16

Updating Data

Support updating existing information on the server

object.Append(key, value)
object.Append(key, casvalue, value)
object.ExecuteAppend(key, value)
object.ExecuteAppend(key, casvalue, value)
object.Cas(storemode, key, value)
object.Cas(storemode, key, value, casunique)
object.Cas(storemode, key, value, validfor, casunique)
object.ExecuteCas(storemode, key, value)
object.ExecuteCas(storemode, key, value, casunique)
object.ExecuteCas(storemode, key, value, expiresat, casunique)
object.ExecuteCas(storemode, key, value, validfor, casunique)
object.Decrement(key, defaultvalue, offset)
object.Decrement(key, defaultvalue, offset, casunique)
object.Decrement(key, defaultvalue, offset, expiresat, casunique)
object.Decrement(key, defaultvalue, offset, validfor, casunique)
object.Decrement(key, defaultvalue, offset, expiresat)
object.Decrement(key, defaultvalue, offset, validfor)
object.Decrement(key, defaultvalue, offset)
object.Decrement(key, defaultvalue, offset, casunique)
object.Decrement(key, defaultvalue, offset, validfor, casunique)
object.Decrement(key, defaultvalue, offset, expiresat)
object.Decrement(key, defaultvalue, offset, validfor)
object.ExecuteDecrement(key, defaultvalue, offset)
object.ExecuteDecrement(key, defaultvalue, offset, casunique)
object.ExecuteDecrement(key, defaultvalue, offset, expiresat, casunique)
object.ExecuteDecrement(key, defaultvalue, offset, validfor, casunique)
object.ExecuteDecrement(key, defaultvalue, offset, expiresat)
object.ExecuteDecrement(key, defaultvalue, offset, validfor)
object.ExecuteRemove(key)
object.Remove(key)
object.ExecuteIncrement(key, defaultvalue, offset)
object.ExecuteIncrement(key, defaultvalue, offset, casunique)
object.ExecuteIncrement(key, defaultvalue, offset, expiresat, casunique)
object.ExecuteIncrement(key, defaultvalue, offset, validfor, casunique)
object.ExecuteIncrement(key, defaultvalue, offset, expiresat)
object.ExecuteIncrement(key, defaultvalue, offset, validfor)
object.Increment(key, defaultvalue, offset)
object.Increment(key, defaultvalue, offset, casunique)
object.Increment(key, defaultvalue, offset, expiresat, casunique)
object.Increment(key, defaultvalue, offset, validfor, casunique)
object.Increment(key, defaultvalue, offset, expiresat)
object.Increment(key, defaultvalue, offset, validfor)
object.ExecutePrepend(key, value)
object.ExecutePrepend(key, casunique, value)
object.Prepend(key, value)
object.Prepend(key, casunique, value)
object.Touch(key, expiry)

Parameters:

String key	Key used to reference the value.
Object value	Value to be stored
StoreMode storemode	Storage mode for a given key/value pair
Timespan validfor	Expiry timespan (in seconds) for key
DateTime expiresat	Explicit expiry time for key
Object defaultvalue	Value to be stored if the key does not exists
offset	Integer offset value to increment or decrement (default 1)
casunique	Unique value used to verify a key/value combination

Section 17

Querying Data

With Couchbase Server 2.0, you can add the power of views and querying those views using your applications.

Create a view object to be used when querying a view:

GetView(designName, viewName)

Parameters:

String designName	Design document name
String viewName	View name within a design document

There is also a generic version of GetView, which has a third boolean parameter that tells the client to lookup the original document by its ID.

GetView

   (designName, viewName, bLookup)

You can iterate over the returned collection as follows :

var beersByNameAndABV = client.GetView

   ("beers", "by_name_and_abv");
foreach(var beer in beersByNameAndABV) { … }

If you iterate over a strongly typed view each item is of the type you specified. If you use the non-generic version, each item you enumerate over will be of type IViewRow. IViewRow provides methods for accessing details of the row that are not present when using strongly typed views.

To get the original document from Couchbase:

row.GetItem()

To get a Dictionary representation of the view:

row.Info

To get the original document's ID:

row.ItemId

To get the key emitted by the map function:

row.ViewKey

To limit the number of documents returned by the query to 10:

GetView(designName, viewName).Limit(10)

To limit the number of documents returned by the query to 10:

GetView(designName, viewName).Limit(10)

To group the results when using _count for example:

GetView(designName, viewName).Group(true)

To disallow stale results in the view:

GetView(designName, viewName).Stale(StaleMode.False)

To limit the number of results to and order the results in descending order:

GetView(designName, viewName).Limit(5).Descending(true)

Section 18

Getting Started With Couchbase C# Libraries

Using the NuGet package manager you can get the Couchbase .Net client using 'Install-Package CouchbaseNetClient'

To create a new MVC project using Couchbase Server , select File -> New Project and then select Web -> ASP.Net MVC4 application under the Visual C# project templates. Give your project a name and click "OK" to create the solution.

Next, you'll need to add a reference to the Couchbase .Net Client Library in your project.

Enjoy building your application using C#.Net and Couchbase Server

Useful Links

Couchbase Website : http://www.couchbase.com
Couchbase Blog : http://blog.couchbase.com
Developer SDKs : http://www.couchbase.com/develop
Download: http://www.couchbase.com/download

Open Source NoSQL Data Access from Java, Ruby, and .NET

Connection Management

Connecting to Couchbase Server

Disconnecting from Couchbase Server

Store Operations

Add Operations

Replace Operations

Set Operations (Durability Requirements)

Retrieve Operations

Update Operations

Query Operations

Connecting to Couchbase

Writing and Updating Data

Key

Value

Add Operations

Replace Operations

Set Operations

Writing Data (Continued)

Asynchronous Store Example (Block)

Reading Data

Simple Get Operations

Extended Tuple Get Operations

Multi-Get Operations

Getting Stats From Couchbase

To Fetch Memory Stats

Deleting and Updating Data

For Deleting of Keys/Values

Atomic Counter Operations

Touch Operations

Durability Requirements

Non-JSON Operations

Querying Data

Create Design Doc Object

Connecting to Couchbase

Writing Data

Store Operations

ExecuteStore Operations

Reading Data

Get Operations

Updating Data

Querying Data

Getting Started With Couchbase C# Libraries

Useful Links

Like This Refcard? Read More From DZone

{{ parent.title || parent.header.title}}

{{ parent.linkDescription }}