Library Version 12.1.3.0

Using storeIterator()
Prev | Chapter 6. Reading Records | Next

## Using storeIterator()

If you want to retrieve all the records that match only some of the major key components, use `KVStore.storeIterator()`. Using this method, you can iterate over all of the records in the store, or over all of the records that match a partial set of major components.

`KVStore.storeIterator()` 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. Also, the records returned by this method are in unsorted order.

Note that this method does not result in a single atomic 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 unsorted traversal of records in the store. If you do not provide a key, then this method will iterate over all of the records in the store. If you do provide a key, you must provide only a subset of the major key components used by your records. The key that you provide must NOT include any minor key components.

To use this method, at a minimum you must specify:

- A traversal direction.

- The suggested number of keys to fetch during each network round trip. If you provide a value of 0, an internally determined default is used.

This minimum list would iterate over all keys in the store. You can also iterate over all the descendents of a specified parent key. Key ranges may also be supplied.

This method performs single-threaded retrieval of records if `StoreIteratorConfig.setMaxConcurrentRequests` is anything other than 1. You might be able to achieve better performance by using parallel scans, which uses multiple threads to retrieve data from the store. See Parallel Scans for more information.

For example, suppose you are storing user records that use keys like this:

    /Smith/Bob/-/birthdate
    /Smith/Bob/-/phonenumber
    /Smith/Bob/-/image
    /Smith/Bob/-/userID
    /Smith/Patricia/-/birthdate
    /Smith/Patricia/-/phonenumber
    /Smith/Patricia/-/image
    /Smith/Patricia/-/userID
    /Smith/Richard/-/birthdate
    /Smith/Richard/-/phonenumber
    /Smith/Richard/-/image
    /Smith/Richard/-/userID
    /Wong/Bill/-/birthdate
    /Wong/Bill/-/phonenumber
    /Wong/Bill/-/image
    /Wong/Bill/-/userID

Then in the simplest case, you can retrieve all of the records for all users whose surname is 'Smith' 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("Smith");

    // 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.storeIterator(Direction.UNORDERED, 0,
                              myKey, null, null);
    while (i.hasNext()) {
        Value v = i.next().getValue();
        // Do some work with the Value here
    }

Prev | Up | Next
Using multiGetIterator() | Home | Specifying Subranges