If you believe your return set will be so large that it cannot fit into memory, use KVStore.multiGetIterator() instead of KVStore.multiGet().

KVStore.multiGetIterator() allows you to perform an ordered traversal of a set of keys, as defined by a key and, optionally, a key range. Use this method if you believe your return set will not fit into memory, or if you believe the return set will be so large that it might strain your network resources.

KVStore.multiGetIterator() does not return the entire set of records all at once. Instead, it batches the fetching of key-value pairs in the iterator, to minimize the number of network round trips, while not monopolizing the available bandwidth.

Note that this method does not result in a transactional operation. Because the retrieval is batched, the return set can change over the course of the entire retrieval operation. As a result, you lose the atomicity of the operation when you use this method.

This method provides for an ordered traversal of records that share the same major path components. The major path components that you provide must represent a complete set of components.

To use this method, you must provide:

Note that there are other possible parameters that you can provide, but this above list represents the minimum information required to use this method.

For example, suppose the following is representative of the keys that you use:

/Hats/-/baseball
/Hats/-/baseball/longbill
/Hats/-/baseball/longbill/blue
/Hats/-/baseball/longbill/red
/Hats/-/baseball/shortbill
/Hats/-/baseball/shortbill/blue
/Hats/-/baseball/shortbill/red
/Hats/-/western
/Hats/-/western/felt
/Hats/-/western/felt/black
/Hats/-/western/felt/gray
/Hats/-/western/leather
/Hats/-/western/leather/black
/Hats/-/western/leather/gray

Then you can retrieve all of the records that use the major key component Hats as follows:

package kvstore.basicExample;

...

import oracle.kv.Direction;
import oracle.kv.Key;
import oracle.kv.Value;
import oracle.kv.KeyValueVersion;

import java.util.ArrayList;
import java.util.Iterator;

...

ArrayList<String> majorComponents = new ArrayList<String>();

...

// Define the major and minor path components for the key
majorComponents.add("Hats");

// Create the retrieval key
Key myKey = Key.createKey(majorComponents);

// Now retrieve the records. Note that we do not show the creation of 
// the kvstore handle here.


Iterator<KeyValueVersion> i = 
    kvstore.multiGetIterator(Direction.FORWARD, 0,
                             myKey, null, null);
while (i.hasNext()) {
    Value v = i.next().getValue(); 
    // Do some work with the Value here
}