table

Class TableAPIExample

java.lang.Object

table.TableAPIExample

public class TableAPIExample
extends Object

This file includes a number of examples that demonstrate some of the features of tables and secondary indexes in Oracle NoSQL Database.

See the package documentation for instructions on how to build and run these examples. They require a running store that has had some required tables and indexes created. The usage for this program is as follows:

 java table.TableAPIExample [-store <instance name>] \
                            [-host  <host name>]     \
                            [-port  <port number>]   \
                            [-example <all | example_to_run>]
 

By default all examples are run. Multiple examples can be run using the -example flag multiple times.

All examples use the default store, host, and port of kvstore, localhost, and 5000. These are the defaults for KVLite as well.

Description of Examples

1. Creates a very simple table and does simple put and get of a row.
2. Uses simple and composite indexese on the table simpleUsers to demonstrate index scans.
3. This example uses a table that has a composite primary key and a defined shard key. This demonstrates the ability to ensure that rows with the same shard key are stored in the same shard and are therefore accessible in an atomic manner. Such rows can also be accessed using the various "multi*" API operations.
4. This example uses a parent/child table relationship to demonstrate how to put and get to/from a child table. It also uses an index on the child table to retrieve child rows via the index.
5. This example uses a table with complex fields (Record, Array, Map) to demonstrate input and output of rows in tables with such fields.
6. This example uses an index on the array from the complex field example table to demonstrate use of an array index.
7. Demonstrates use of table version, row table version, and the Version of a row to handle changes related to table schema evolution. This example requires running the evolve_table.kvs script to see changes.
8. This example uses tables that were created in R2 compatibility mode where tables are intended to overlay existing R2 data. This is possible for R2 key-only applications as well as R2 applications with Avro schemas that are compatible with tables (most will be, but not all).
9. This is a simple example of a key-only table.

Constructor Summary

Constructors

Constructor and Description
TableAPIExample(String[] argv) Parses command line args and opens the KVStore.

Method Summary

Methods

Modifier and Type	Method and Description
static void	main(String[] args) Runs the TableAPIExample command line program.
(package private) void	runExample1() Example 1: Hello World! This example shows a simple use of tables, it uses a simple table holding an id field as a primary key and 2 fields -- name and surname -- as Strings.
(package private) void	runExample2() Example 2: Secondary Index This example uses 2 indexes on the table "simpleUsers." One is a simple, single-field index on "firstName" and the other is a composite index on "lastName, firstName".
(package private) void	runExample3() Example 3: Shard keys This example uses a table that has a composite primary key and a defined shard key.
(package private) void	runExample4() Example 4: Parent and Child tables This example demonstrates use of parent and child tables.
(package private) void	runExample5() Example 5: Complex fields This example demonstrates how to create, populate and read complex fields (Array, Map, Record) in a table.
(package private) void	runExample6() Example 6: Secondary index on array This example demonstrates use of a secondary index on an array.
(package private) void	runExample7() Example 7: Evolve Table This example requires use of the evolve_table.kvs script to help demonstrate how to handle schema evolution of a table.
(package private) void	runExample8() Example 8: R2 compatibility example This example uses a table created using an avro schema and a table with r2 compatibility enabled.
(package private) void	runExample9() Example 9: Primary key table This example shows how all the fields in a table can be assigned as part of the primary key as a key-only table.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TableAPIExample

TableAPIExample(String[] argv)

Parses command line args and opens the KVStore.

Method Detail

main

public static void main(String[] args)

Runs the TableAPIExample command line program.

runExample1

void runExample1()

Example 1: Hello World! This example shows a simple use of tables, it uses a simple table holding an id field as a primary key and 2 fields -- name and surname -- as Strings. It does basic put and get.

runExample2

void runExample2()

Example 2: Secondary Index This example uses 2 indexes on the table "simpleUsers." One is a simple, single-field index on "firstName" and the other is a composite index on "lastName, firstName".

runExample3

void runExample3()

Example 3: Shard keys This example uses a table that has a composite primary key and a defined shard key. This demonstrates the ability to ensure that rows with the same shard key are stored in the same shard and are therefore accessible in an atomic manner. Such rows can also be accessed using the various "multi*" API operations.

runExample4

void runExample4()

Example 4: Parent and Child tables This example demonstrates use of parent and child tables. The parent table is the shardUsers table used above and the child table is a table of addresses for a given user, allowing definition of multiple addresses for a user.

runExample5

void runExample5()

Example 5: Complex fields This example demonstrates how to create, populate and read complex fields (Array, Map, Record) in a table.

runExample6

void runExample6()

Example 6: Secondary index on array This example demonstrates use of a secondary index on an array. An important thing to note about indexes on arrays is that a independent index entry is generated for each value in the array. This can lead to an explosion of entries as well as potential for duplication in results (e.g. if the same array value repeats in the same row). This example uses the same table as the complex field example. There is an index on the "likes" array.

runExample7

void runExample7()

Example 7: Evolve Table This example requires use of the evolve_table.kvs script to help demonstrate how to handle schema evolution of a table. It shows how to evolve a table using CLI commands and how to protect code from accessing older version tables using the getTableVersion and the Version returned by row operations. NOTE: This example needs to run the script evolve_table to show the differences between an evolved table and a new table. kv-> load -file <store directory>/example/tables/evolve_table.kvs The evolution does this: 1. removes the "phoneNumber" field 2. adds a String "comment" field To see a change, run this example, then run evolve_table.kvs and run the example again. When this is done you will see the default value set for the new "comment" field and the fact that the removed "phoneNumber" field does not appear. In a real application a combination of the table version, the row's table version (the table version used to write the row) and the row's Version object can be used to protect the application from unexpected changes.

runExample8

void runExample8()

Example 8: R2 compatibility example This example uses a table created using an avro schema and a table with r2 compatibility enabled. These features are intended for migration of the key/value API to the table API. Such migration is required in order to add indexes on R2 data. TODO: add actual R2 data to this example to show compatibility.

runExample9

void runExample9()

Example 9: Primary key table This example shows how all the fields in a table can be assigned as part of the primary key as a key-only table.