Library Version 12.1.3.0

Chapter 9. Key Ranges and Depth for Multi-Key Operations
Prev |  | Next

## Chapter 9. Key Ranges and Depth for Multi-Key Operations

When performing multi-key operations (for example, `KVStore.multiGet()`, `KVStore.multiDelete()`, `KVStore.storeIterator()`), you can limit the records that are operated upon by specifying key ranges and depth. Key ranges allow you to identify a subset of keys to use out of a matching set. Depth allows you to specify how many children you want the multi-key operation to use.

## Specifying Subranges

When performing multi-key operations in the store, you can specify a range of records to operate upon. You do this using the `KeyRange` class. This class defines a range of `String` values for the key components immediately following a key that is used in a multiple get operation.

For example, suppose you were using the following keys:

    /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

Given this, you could perform operations for all the records related to users Bob Smith and Patricia Smith by constructing a `KeyRange`. When you do this, you must identify the key components that define the upper and lower bounds of the range. You must also identify if the key components that you provide are inclusive or exclusive.

In this case, we will define the start of the key range using the string "Bob" and the end of the key range to be "Patricia". Both ends of the key range will be inclusive.

    package kvstore.basicExample;

    import oracle.kv.KeyRange;

    ...

    KeyRange kr = new KeyRange("Bob", true, "Patricia", true);

You then use the `KeyRange` instance when you perform your multi-key operation. For example, suppose you were retrieving records from your store using `KVStore.storeIterator()`:

    package kvstore.basicExample;

    ...

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

    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);

    KeyRange kr = new KeyRange("Bob", true, "Patricia", true);

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

    try {
        Iterator<KeyValueVersion> i =
            kvstore.storeIterator(Direction.FORWARD, 0,
                                  myKey, kr, null);
        while (i.hasNext()) {
            Value v = i.next().getValue();
            // Do some work with the Value here
        }
    } catch (RequestTimeoutException re) {
        // The operation was not completed within the
        // timeout value
    }

Prev |  | Next
JSON Bindings | Home | Specifying Depth