Library Version 12.1.3.0

Writing Rows to a Table in the Store
Prev | Chapter 6. Writing and Deleting Records | Next

## Writing Rows to a Table in the Store

Writing a new row to a table in the store, and updating an existing row are usually identical operations (although methods exist that work only if the row is being updated, or only if it is being created — these are described a little later in this section).

Remember that you can only write data to a table after it has been added to the store. See Introducing Oracle NoSQL Database Tables and Indexes for details.

To write a row to a table in the store:

1. Construct a handle for the table to which you want to write. You do this by retrieving a `TableAPI` interface instance using `KVStore.getTableAPI()`. You then use that instance to retrieve the desired table handle using `TableAPI.getTable()`. This returns a `Table` interface instance.

2. Use the `Table` instance retrieved in the previous step to create a `Row` interface instance. You use the `Table.createRow()` method to do this.

3. Write to each field in the `Row` using `Row.put()`.

4. Write the new row to the store using `TableAPI.put()`.

The following is a trivial example of writing a row to the store. It assumes that the `KVStore` handle has already been created.

    package kvstore.basicExample;

    import oracle.kv.KVStore;
    import oracle.kv.table.Row;
    import oracle.kv.table.Table;
    import oracle.kv.table.TableAPI;

    ...

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

    // Get a Row instance
    Row row = myTable.createRow();

    // Now put all of the cells in the row.
    // This does NOT actually write the data to
    // the store.

    row.put("item", "Bolts");
    row.put("description", "Hex head, stainless");
    row.put("count", 5);
    row.put("percentage", 0.2173913);

    // Now write the table to the store.
    // "item" is the row's primary key. If we had not set that value,
    // this operation will throw an IllegalArgumentException.
    tableH.put(row, null, null);

### Writing Rows to a Child Table

To write to a child table, first create the row in the parent table to which the child belongs. You do this by populating the parent row with data. Then you write the child table's row(s). When you do, you must specify the primary key used by the parent table, as well as the primary key used by the child table's rows.

For example, in Defining Child Tables we showed how to create a child table. To write data to that table, do this:

    package kvstore.basicExample;

    import oracle.kv.KVStore;
    import oracle.kv.table.Row;
    import oracle.kv.table.Table;
    import oracle.kv.table.TableAPI;

    ...

    // KVStore handle creation is omitted for brevity

    ...

    TableAPI tableH = kvstore.getTableAPI();

    // First, populate a row in the parent table
    Table myTable = tableH.getTable("myTable");

    // Get a Row instance
    Row row = myTable.createRow();

    // Now put all of the cells in the row.

    row.put("itemCategory", "Bolts");
    row.put("description", "Metric & US sizes");

    // Now write the table row to the store.
    tableH.put(row, null, null);

    // Now populate the corresponding child table
    Table myChildTable = tableH.getTable("myTable.myChildTable");

    // Get a row instance
    Row childRow = myChildTable.createRow();

    // Populate the rows. Because the parent table's "itemCategory"
    // field is a primary key, this must be populated in addition
    // to all of the child table's rows
    childRow.put("itemCategory", "Bolts");
    childRow.put("itemSKU", "1392610");
    childRow.put("itemDescription", "1/4-20 x 1/2 Grade 8 Hex");
    childRow.put("price", new Float(11.99));
    childRow.put("inventoryCount", 1457);

### Other put Operations

Beyond the very simple usage of the `TableAPI.put()` method illustrated above, there are three other put operations that you can use:

- `TableAPI.putIfAbsent()`

  This method will only put the row if the row's primary key value DOES NOT currently exist in the table. That is, this method is successful only if it results in a create operation.

- `TableAPI.putIfPresent()`

  This method will only put the row if the row's primary key value already exists in the table. That is, this method is only successful if it results in an update operation.

- `TableAPI.putIfVersion()`

  This method will put the row only if the value matches the supplied version information. For more information, see Using Row Versions.

Prev | Up | Next
Chapter 6. Writing and Deleting Records | Home | Deleting Rows from the Store