Library Version 12.1.3.0

Specifying Field Ranges
Prev | Chapter 7. Reading Table Rows | Next

## Specifying Field Ranges

When performing multi-key operations in the store, you can specify a range of rows to operate upon. You do this using the `FieldRange` class, which is accepted by any of the methods which perform bulk reads. This class is used to restrict the selected rows to those matching a range of field values.

For example, suppose you defined a table like this:

    ## Enter into table creation mode
    table create -name myTable
    ## Now add the fields
    add-field -type STRING -name surname
    add-field -type STRING -name familiarName
    add-field -type STRING -name userID
    add-field -type STRING -name phonenumber
    add-field -type STRING -name address
    add-field -type STRING -name email
    add-field -type STRING -name dateOfBirth
    primary-key -field surname -field familiarName -field userID
    shard-key -field surname -field familiarName
    ## Exit table creation mode
    exit

The `surname` contains a person's family name, such as `Smith`. The `familiarName` contains their common name, such as `Bob`, `Patricia`, `Robert`, and so forth.

Given this, you could perform operations for all the rows related to users named `Bob Smith` and `Patricia Smith` by specifying a field range.

A `FieldRange` class instance is created using `Table.createFieldRange()`. This method takes just one argument — the name of the primary key for which you want to set the range. Once you have the `FieldRange` object, you can set the start and end values for the range. You also indicate whether the range values are inclusive.

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.

In this example, we use `TableIterator`, but we could just as easily use this range on any multi-row read operation, such as `TableAPI.multiGet()` or `TableAPI.multiGetKeys()`. The `FieldRange` object is passed to these methods using a `MultiRowOptions` class instance, which we construct using the `FieldRange.createMultiRowOptions()` convenience method.

    package kvstore.basicExample;

    ...

    import oracle.kv.KVStore;
    import oracle.kv.table.FieldRange;
    import oracle.kv.table.MultiRowOptions;
    import oracle.kv.table.PrimaryKey;
    import oracle.kv.table.Row;
    import oracle.kv.table.Table;
    import oracle.kv.table.TableAPI;
    import oracle.kv.table.TableIterator;

    ...

    // KVStore handle creation is omitted for brevity

    ...

    TableAPI tableH = kvstore.getTableAPI();

    // The name you give to getTable() must be identical
    // to the name that you gave the table when you created
    // the table using the CLI's 'table create' command.
    Table myTable = tableH.getTable("myTable");

    // Construct the PrimaryKey. In this case, we are
    // using a partial primary key.
    PrimaryKey key = myTable.createPrimaryKey();
    key.put("surname", "Smith");

    // Create the field range.
    FieldRange fh = myTable.createFieldRange("familiarName");
    fh.setStart("Bob", true);
    fh.setEnd("Patricia", true);
    MultiRowOptions mro = fh.createMultiRowOptions();

    // Exception handling is omitted, but in production code
    // ConsistencyException, RequestTimeException, and FaultException
    // would have to be handled.
    TableIterator<Row> iter = tableH.tableIterator(key, mro, null);
    try {
        while (iter.hasNext()) {
            Row row = iter.next();
            // Examine your row's fields here
        }
    } finally {
        if (iter != null) {
            iter.close();
        }
    }

Prev | Up | Next
Iterating over Table Rows | Home | Using MultiRowOptions to Retrieve Nested Tables