Over a million developers have joined DZone.
Refcard #176

Essential Couchbase APIs

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

Written by

Don Pinto PMM, Couchbase

Provides an overview of connection, storage, retrieval, update, and query operations on Couchbase databases from Java, Ruby, and .NET applications.

Free PDF
DOWNLOAD
Section 1

Connection Management

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  30*24*60*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 30*24*60*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  30*24*60*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 30*24*60*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'

Installing Couchbase .NET client

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.

Creating a new MVC project

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

Publications

  • Featured
  • Latest
  • Popular
DOWNLOAD
The Ultimate Scrum Reference Card
Provides a concise overview of roles, meetings, rules, and artifacts within a Scrum organization. Updated for 2016.
71.8k 195.5k
DOWNLOAD
AMQP Essentials
Practical introduction to AMQP — a binary, multiplexed, symmetric, secure, and lightweight message transport protocol designed for enterprise applications and particularly useful for IoT.
5,107 3,829
DOWNLOAD
Core .NET
Snapshot of the modern .NET Framework from 30,000 feet, plus deep dive into .NET types, portable class libraries, encodings, and asynchronous programming.
40.3k 140.5k
DOWNLOAD
React.js Essentials
Gives you the essentials of React.js, from the architecture to the virtual DOM, from building components to styling them.
7,439 6,199
DOWNLOAD
SQL Syntax for Apache Drill
Acquaints you with the agility and flexibility of Apache Drill and enables you to easily query non-relational datastores, including Hadoop. Discover the benefits of data agility and gain faster insights into BI and analytics through advanced SQL queries on massive datasets.
4,631 9,243
DOWNLOAD
Node.js
Until recently, highly concurrent programs were the sole province of hardcore network programmers, but now any JavaScript-savvy web developer can write the same kinds of highly concurrent programs quickly and easily.
52k 89.1k
DOWNLOAD
Getting Started With Industrial Internet
Introduces basic concepts and technologies of the Industrial Internet, including sensors and actuators, industrial control systems, human-machine interfaces, real-time streaming data, device security, and more.
4,270 4,444
DOWNLOAD
Getting Started With Docker
Teaches you typical Docker workflows, building images, creating Dockerfiles, and includes helpful commands to easily automate infrastructure and contain your distributed application.
13.3k 14.6k
DOWNLOAD
Getting Started With Real User Monitoring
Teaches you how to use new web standards—like W3C’s Beacon API—to see how your site is performing for actual users, letting you better understand how to improve overall user experience.
5,492 7,442
DOWNLOAD
Core Java
Gives you an overview of key aspects of the Java language and references on the core library, commonly used tools, and new Java 8 features.
108.6k 277.1k
DOWNLOAD
JavaFX 8
Gives you what you need to start using the powerful JavaFX 8 UI and graphics tool with code snippets and visual examples of shapes and controls.
8,264 14.7k
DOWNLOAD
Continuous Delivery With Jenkins Workflow
Provides an introduction to the Jenkins Workflow plugin, a tool that extends the popular CD application to manage even the most complex software pipelines and help you continuously deliver more efficiently.
10.5k 19.6k
{{ card.title }}
{{card.downloads | formatCount }} {{card.views | formatCount }}

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

{{ parent.tldr }}

{{ parent.urlSource.name }}