Reading Data

Learn how to read data from your table.

You can read data from your application by using the different API methods for the language-specific drivers. You can retrieve a record based on a single primary key value, or by using queries.

Note:

First, connect your client driver to Oracle NoSQL Database Cloud Service to get a handle and then complete other steps. This topic omits the steps for connecting your client driver and creating a table.

The GetRequest class provides a simple and powerful way to read data, while queries can be used for more complex read requests. To read data from a table, specify the target table and target key using the GetRequest class and use NoSQLHandle.get() to execute your request. The result of the operation is available in GetResult. The following example considers that the default compartment is specified in NoSQLHandleConfig while obtaining the NoSQL handle. See Obtaining a NoSQL Handle. To explore other options of specifying a compartment for the NoSQL tables, see About Compartments.

To read data from your table:

/* GET the row, first create the row key */
MapValue key = new MapValue().put("id", 1);
GetRequest getRequest = new GetRequest().setKey(key)
                                        .setTableName("users");
GetResult getRes = handle.get(getRequest);

/* on success, GetResult.getValue() returns a non-null value */
if (getRes.getValue() != null) {
  // success
} else {
  // failure
}

Note:

By default, all read operations are eventually consistent. You can change the default Consistency for a NoSQLHandle instance by using the NoSQLHandleConfig.setConsistency(oracle.nosql.driver.Consistency) and GetRequest.setConsistency() methods.

See the Java API Reference Guide for more information about the GET APIs.

Learn how to read data from your table. You can read single rows using the borneo.NoSQLHandle.get() method. This method allows you to retrieve a record based on its primary key value. The borneo.GetRequest class is used for simple get operations. It contains the primary key value for the target row and returns an instance of borneo.GetResult.
from borneo import GetRequest
# GetRequest requires a table name 
request = GetRequest().set_table_name('users')
# set the primary key to use request.set_key({'id': 1})
result = handle.get(request)
# on success the value is not empty
if result.get_value() is not None:
# success

By default all read operations are eventually consistent, using borneo.Consistency.EVENTUAL. This type of read is less costly than those using absolute consistency, borneo.Consistency.ABSOLUTE. This default can be changed in borneo.NoSQLHandle using borneo.NoSQLHandleConfig.set_consistency() before creating the handle. It can be changed for a single request using borneo.GetRequest.set_consistency().

You can read single rows using the Client.Get function. This function allows you to retrieve a record based on its primary key value. The nosqldb.GetRequest is used for simple get operations. It contains the primary key value for the target row and returns an instance of nosqldb.GetResult. If the get operation succeeds, a non-nil GetResult.Version is returned.
key:=&types.MapValue{}
key.Put("id", 1)
req:=&nosqldb.GetRequest{
    TableName: "users",
    Key: key,
}
res, err:=client.Get(req)
By default all read operations are eventually consistent, using types.Eventual. This type of read is less costly than those using absolute consistency, types.Absolute. This default can be changed in nosqldb.RequestConfig using RequestConfig.Consistency before creating the client. It can be changed for a single request using GetRequest.Consistency field.
  1. Change default consistency for all read operations.
    cfg:= nosqldb.Config{
      RequestConfig: nosqldb.RequestConfig{
            Consistency: types.Absolute,
            ...
        },
        ...
    }
    client, err:=nosqldb.NewClient(cfg)
  2. Change consistency for a single read operation.
    req:=&nosqldb.GetRequest{
        TableName: "users",
        Key: key,
        Consistency: types.Absolute,
    }

You can read single rows using the get method. This method allows you to retrieve a record based on its primary key value. You can set consistency of read operation using Consistency enumeration. By default all read operations are eventually consistent, using Consistency.EVENTUAL. This type of read is less costly than those using absolute consistency, Consistency.ABSOLUTE. This default consistency for read operations can be set in the initial configuration used to create NoSQLClient instance using consistency property. You may also change it for a single read operation by setting consistency property in the opt argument of the get method.

get method returns Promise of GetResult which which is plain JavaScript object containing the resulting row and its Version. If the provided primary key does not exist in the table, the value of row property will be null. Note that the property names in the provided primary key key object should be the same as underlying table column names.
const NoSQLClient = require('oracle-nosqldb').NoSQLClient;
const Consistency = require('oracle-nosqldb').Consistency;
const client = new NoSQLClient('config.json'); 
async function getRowsFromUsersTable() { 
   const tableName = 'users'; 
   try {
      let result = await client.get(tableName,  
      { id: 1 });
      console.log('Got row: ' + result.row);
      // Use absolute consistency 
      result = await client.get(tableName, 'users', 
         { id: 1 }, { consistency: Consistency.ABSOLUTE }); 
      console.log('Got row with absolute consistency: ' + result.row);
   } 
   catch(error){
      //handle errors
   }
}

You can read a single row using the GetAsync method. This method allows you to retrieve a row based on its primary key value. This method takes the primary key value as MapValue. The field names should be the same as the table primary key column names. You may also pass options as GetOptions.

You can set consistency of a read operation using Consistency enumeration. By default all read operations are eventually consistent. This type of read is less costly than those using absolute consistency. The default consistency for read operations may be set as Consistency property of NoSQLConfig. You may also change the consistency for a single Get operation by using Consistency property of GetOptions.

GetAsync method returns Task<GetResult<RecordValue>>. GetResult instance contains the returned Row, the row Version and other information. If the row with the provided primary key does not exist in the table, the values of both Row and Version properties will be null.
var client = new NoSQLClient("config.json");
..................................................
var tableName = "users";
try{
    var result = await client.GetAsync(tableName,
        new MapValue
        {
            ["id"] =1
        });
    // Continuing from the Put example, the expected output will be:
    // { "id": 1, "name": "Kim" }
    Console.WriteLine("Got row: {0}", result.row);
    // Use absolute consistency.
    result = await client.GetAsync(tableName,
        new MapValue
        {
            ["id"] =2
        }),
         new GetOptions
         {
            Consistency=Consistency.Absolute
         });
   // The expected output will be:
   // { "id": 2, "name": "Jack" }
   Console.WriteLine("Got row with absolute consistency: {0}",
        result.row);
  // Continuing from the Put example, the expiration time should be
  // 30 days from now.
  Console.WriteLine("Expiration time: {0}", result.ExpirationTime)
}
catch(Exception ex){
  // handle exceptions
}