In the case of our spaceship game example, we create space
environment which contains multiple planets and discussed how we
get to retrieve documents
that represent the planets. In reality if we want to retrieve
more than one document, and do so efficiently, we would use one
of the forms bulk-retrieves. This enables us to send a single
request from our SDK for all the keys we want to retrieve.
Developers that are new to Couchbase Server tend to heavily rely
get to retrieve values, even sets of
values. However, using a form of multiple retrieve may be a
better approach if you are doing multiple retrievals.
One of the major advantages of using a multiple-retrieve is that
you can make a single request to Couchbase Server from an SDK.
The alternate you could choose is to make multiple, sequential
get requests and your application needs
to wait for the SDK to make each of these requests. This
approach has the performance disadvantage of creating a separate
request that Couchbase Server must then individually respond to.
For instance if you want to retrieve 100 keys, you could do this
as a multiple-retrieve and all keys could be retrieved in 1
millisecond. If you chose to do 100
calls, this would take the equivalent of 100 milliseconds. In
short, if you are retrieving multiple keys, performing a
multiple-retrieve will improve application performance compared
to performing a regular
One scenario where this is helpful is anytime you are aggregating information, such as a leader-board. Imagine you want to show the top products purchased at a site, or in this case, the top scoring users for your site. To do this, you can perform a multiple-retrieve:
The method call varies by language; however the principle remains the same; you can pass a list, array, or hash as parameters to the retrieve method, and multiple keys are specified. Couchbase Server retrieves values for each of the keys it can find.
This example demonstrates how to retrieve multiple keys, using different method overloads in Ruby:
keys = ["foo", "bar","baz"] // alternate method signatures for multiple-retrieve conn.get(keys) conn.get(["foo", "bar", "baz"]) conn.get("foo", "bar", "baz")
In this case, we can overload the standard
get method signature to include several
In the case of other languages, such as Java, there is a
separate method, called
will retrieve keys provided in a string collection:
Map<String,Object> keyvalues = client.getBulk(keylist);
There are some cases where you want to perform a multiple-retrieve but you know the operation will take longer than a user will want to wait, or you want to perform the operation in the background while the application performs other tasks. In a spaceship game, for instance, you want to retrieve all the profiles of users who have a high score to display in a leader board. But in the meantime, you want players to be able to continue playing their game.
In this case, you can perform a multiple-retrieve asynchronously. When you do so, multiple-retrieve will return before the SDK sends a request to Couchbase Server. Your game application continues for the player and they can play their game. In the background, Couchbase Server retrieves all the specified keys that exist and sends these documents to the client SDK. Your application can later retrieve the documents if they exist, or perform error-handling if the documents do not exist. The following demonstrates an asynchronous multiple-retrieve in PHP:
$cb->set('int', 99); $cb->set('string', 'a simple string'); $cb->set('array', array(11, 12)); $cb->getDelayed(array('int', 'array'), true); var_dump($cb->fetchAll());
In this case
immediately and we retrieve all the keys later by performing
The multiple-retrieve methods in Couchbase SDKs are based on
getq in the memcached
protocol in a single binary packet. For more information about
the memcached protocol, see
When you do a multiple-retrieve, be aware that the method will return values for the keys that exist. If a key does not exist, Couchbase Server returns a 'key not found' error which the SDK interprets. If a key is missing, SDK do not provide a placeholder in the result set for the missing key. Therefore do not assume that the order of results will be the same as the order of the keys you provide. If your application depends on all keys existing and being retrieved, you should provide application logic that iterates through the results and checks to see the number results matches the number of keys. You might also want to provide logic that sorts the results so they map to your sequence of keys.
If you expected a key to actually exist, but it does not appear in a result set, you should check your application logic to see why it does not exist. Any logic that creates that type of key, or any logic that deletes it may inadvertently cause this result. Another reason why you might get this result is that the item expired and Couchbase Server returns a 'key not found' error. So you will want to check any explicit expiration set for that key.
One option to handle this result is to create the value if it
does not already exist. After you receive this result you can
add to create the key.
The types of errors that can occur during this operation include 1) inability to connect to a node, or 2) some error exists while attempting to format values being retrieved. If you have a connection-level error you may need to reattempt connection, and possibly check the status of the server. If you have an error with the size of your value or formatting, you need to check the value itself, and how it is encoded and see if there are any issues that make the item incompatible with Couchbase Server.