Class NoSQLClient
Implements
Namespace: Oracle.NoSQL.SDK
Assembly: Oracle.NoSQL.SDK.dll
Syntax
public class NoSQLClient : ObjectRemarks
To instantiate NoSQLClient, provide configuration in the form of NoSQLConfig object containing connection information, credentials and default values for operation options. Alternatively, you may provide a path to a JSON file containing this information. See NoSQLConfig for more details.
The same interface is available to both users of Oracle NoSQL Database Cloud Service and on-premise Oracle NoSQL Database, however some methods and/or options are specific to each environment. For each such method or option, the documentation specifies which environment it is applicable to.
NoSQLClient has memory and network resources
associated with it. It implements IDisposable
interface and must be disposed when application is done using it via
calling Dispose() or via using statement.
In most cases, an application only needs to create
NoSQLClient instance once and dispose of it in the end.
To minimize network activity as well as resource allocation and
deallocation overheads, repeated creation and disposal of
NoSQLClient instances is not recommended.
NoSQLClient permits concurrent operations, so a single instance is sufficient to access tables in a multi-threaded application. The creation of multiple instances incurs additional resource overheads without providing any performance benefit.
With the exception of Dispose() the operations on NoSQLClient follow a similar pattern. They accept a number of required parameters and and an optional options object providing optional parameters, with different options classes for different operations (e.g. TableDDLOptions, PutOptions, etc.). Note that you may reuse the same options object when performing the same operation multiple times.
If an option or any of its values are not specified or set to
null, corresponding values set in
NoSQLConfig will be used as described in documentation
for each option. For values not specified in
NoSQLConfig appropriate defaults will be used.
All operations are asynchronous and also accept optional CancellationToken parameter to cancel asynchronous operation.
Each operation returns a Task<TResult> of corresponding operation result, with different result classes for different operations (e.g. TableResult, PutResult<TRow> etc.) Result objects returned are not thread safe and should be used by only one thread at a time unless synchronized externally.
Operation failures throw exceptions. NoSQLClient may throw some standard exceptions such as ArgumentException, InvalidOperationException, TimeoutException, etc). All other exceptions are instances of NoSQLException which serves as a base class for NoSQL Database exceptions.
Some exceptions allow an operation to be retried, with the expectation
that it may succeed on retry, because they are caused by conditions
that are temporary in nature. Examples of retryable exceptions are
those which indicate resource consumption violation such as
ReadThrottlingException,
WriteThrottlingException and others. In addition, any
network or IO errors are always retryable as the usually indicate
temporary conditions. Other exceptions such as
ArgumentException, TableNotFoundException,
etc. are not retryable as they indicate a syntactic or semantic errors
that require additional actions to be resolved.
Exceptions that may be retried are those among the subclasses of
NoSQLException and are indicated in the documentation
for corresponding exception classes. For these subclasses the
property IsRetryable is true.
If a retryable exception is thrown, the driver will automatically retry the operation. The retry semantics is determined by retry handler provided as RetryHandler in the initial configuration. If not set, a default instance of NoSQLRetryHandler will be used. See IRetryHandler and NoSQLRetryHandler for details on retry behavior. This means that a result returned by an operation may be a result obtained after one or more retries (in case the initial attempt and previous retries have failed with retryable exceptions).
When operation is retried by the driver, the operation timeout is considered cumulative over all retries (and not just for a single retry). The driver will keep retrying as long as retries are allowed by the retry handler and are within the specified timeout. TimeoutException is thrown once the timeout expires. TimeoutException may also be thrown even on a non-retryable operation (a single request) if the operation times out for other reasons such as network connectivity. If you are getting TimeoutException often and the service is operating properly, you may wish to adjust corresponding timeout values passed in the operation options or specified in NoSQLConfig.
TimeoutException itself is not retryable automatically by the driver, although an application may choose to retry the operation. Note however that in general, TimeoutException only indicates inability for the driver to receive operation result within the specified timeout and thus it does not determine whether the operation itself was already started/completed by the service. Thus for non-idempotent operations, additional actions may need to be taken before retrying in this situation.
Likewise, you may cancel operations on NoSQLClient instance for which you provided CancellationToken argument. In this case the operation may throw OperationCanceledException (or its subclass TaskCanceledException). As with TimeoutException, catching this exception does not provide any guarantees as to whether the operation was performed by the service.
Instances of NoSQLClient are thread-safe and expected to be shared among threads.
For cloud service only: Each of the options classes contains Compartment property which specifies the compartment of given table (or compartment used to perform given operation). A default value to use for all operations may also be set as Compartment. If neither is set, the root compartment of the tenancy is assumed. The compartment is a string that may be either the id (OCID) of the compartment or a compartment name. Both are acceptable. If a name is used it can be either the name of a top-level compartment, or for nested compartments, it should be a compartment path to the nested compartment that does not include the root compartment name (tenant), e.g. compartmentA.compartmentB.compartmentC. Alternatively, instead of using Compartment property, you may prefix the table name with its compartment name (for top-level compartments) or compartment path (for nested compartments), e.g. compartmentA.compartmentB.compartmentC:myTable. Note that the table name cannot be prefixed with compartment id. Prefixing the table with compartment name/path takes precedence over other methods of specifying the compartment.
Examples
This example instantiates NoSQLClient and uses it to create table, put record into that table and then retrieve it.using Oracle.NoSQL.SDK;
public class Example
{
public static async Task Main()
{
// This will ensure client is disposed on exit from Main()
using var client = new NoSQLClient("config.json");
// We can also use ExecuteTableDDLWithCompletionAsync()
var tableResult = await client.ExecuteTableDDLAsync(
"CREATE TABLE foo(id INTEGER, name STRING, PRIMARY KEY(id))",
new TableLimits(100, 100, 50));
await tableResult.WaitForCompletionAsync();
Console.WriteLine("Table name: {0}, table state: {1}",
tableResult.TableName, tableResult.TableState);
var putResult = await client.PutAsync("foo", new MapValue
{
["id"] = 1,
["name"] = "John"
});
Console.WriteLine("Put succeeded: {0}", putResult.Success);
var getResult = await client.GetAsync("foo", new MapValue
{
["id"] = 1
});
Console.WriteLine("Get returned record:");
// Check Row for null before converting to JSON string
Console.WriteLine(getResult.Row?.ToJsonString());
}
}Constructors
| Name | Description |
|---|---|
| NoSQLClient(NoSQLConfig) | Initializes new instance of NoSQLClient using provided configuration object. You may omit |
| NoSQLClient(String) | Initializes new instance of NoSQLClient using provided path to JSON configuration file. |
Properties
| Name | Description |
|---|---|
| ServiceType | Gets the service type used by this NoSQLClient instance. |