nosqldb

package
Version: v1.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 17, 2022 License: UPL-1.0 Imports: 35 Imported by: 0

Documentation

Overview

Package nosqldb provides the public APIs for Go applications to use the Oracle NoSQL Database.

This package also provides configuration and common operational structs and interfaces, such as request and result types used for NoSQL database operations.

More detailed information can be viewed at: https://github.com/oracle/nosql-go-sdk/blob/master/README.md

Index

Examples

Constants

View Source
const (
	// LimiterRefreshNanos is used to update table limits once every 10 minutes
	LimiterRefreshNanos int64 = 600 * 1000 * 1000 * 1000
	// SessionCookieField is used to check for persistent session cookies
	SessionCookieField string = "session="
)

Variables

View Source
var (
	// Decimal32 represents the IEEE 754R Decimal32 format, that is 7 digits,
	// and a rounding mode of big.ToNearestEven.
	Decimal32 = FPArithSpec{
		Precision:    7,
		RoundingMode: big.ToNearestEven,
	}

	// Decimal64 represents the IEEE 754R Decimal64 format, that is 16 digits,
	// and a rounding mode of big.ToNearestEven.
	Decimal64 = FPArithSpec{
		Precision:    16,
		RoundingMode: big.ToNearestEven,
	}

	// Decimal128 represents the IEEE 754R Decimal128 format, that is 34 digits,
	// and a rounding mode of big.ToNearestEven.
	Decimal128 = FPArithSpec{
		Precision:    34,
		RoundingMode: big.ToNearestEven,
	}

	// Unlimited represents a setting of 0 precision and a rounding mode of
	// big.ToNearestAway.
	// This is used for unlimited precision arithmetic.
	Unlimited = FPArithSpec{
		Precision:    0,
		RoundingMode: big.ToNearestAway,
	}
)

Functions

This section is empty.

Types

type AuthorizationProvider

type AuthorizationProvider interface {
	// AuthorizationScheme returns a string that represents the supported
	// authorization scheme for this provider.
	//
	// The available authorization schemes are:
	//
	//   Bearer    : supported for the on-premise Oracle NoSQL server and the Oracle NoSQL cloud simulator
	//   Signature : supported for the Oracle NoSQL cloud service that uses OCI IAM for request authorization
	//
	AuthorizationScheme() string

	// AuthorizationString returns an authorization string for the specified request.
	// The returned string will be sent to the server in the request for authorization.
	// Authorization information can be request-dependent.
	AuthorizationString(req auth.Request) (string, error)

	// Some authorization providers need the entire http request to sign it
	// note this method may add or change header fields (but should never modify the
	// http data payload)
	SignHTTPRequest(httpReq *http.Request) error

	// Close releases resources allocated by the provider.
	Close() error
}

AuthorizationProvider is an interface used to provide authorization information for client to access authorized resources on the server.

A Client should call the AuthorizationString() method to obtain an authorization string when it is required for the request, or call the SignHTTPRequest() method depending on the authorization scheme.

The default implementations for this interface:

iam.SignatureProvider        cloud IAM
kvstore.AccessTokenProvider  on-premise

Applications do not need to provide an implementation for this interface unless there is a special requirement.

Implementations of this interface must be safe for concurrent use by multiple goroutines.

type Capacity

type Capacity struct {
	// ReadKB represents the number of kilo bytes consumed for reads.
	ReadKB int `json:"readKB"`

	// WriteKB represents the number of kilo bytes consumed for writes.
	WriteKB int `json:"writeKB"`

	// ReadUnits represents the number of read units consumed for reads.
	//
	// A read unit represents 1 eventually consistent read per second for data
	// up to 1 KB in size. A read that is absolutely consistent is double that,
	// consuming 2 read units for a read of up to 1 KB in size.
	ReadUnits int `json:"readUnits"`
}

Capacity represents the read/write throughput consumed by an operation.

func (Capacity) ConsumedCapacity

func (r Capacity) ConsumedCapacity() (Capacity, error)

ConsumedCapacity returns the read/write throughput consumed by an operation.

func (Capacity) String

func (r Capacity) String() string

String returns a JSON string representation of the Capacity.

type Client

type Client struct {
	// Config specifies the configuration parameters associated with the Client.
	// Most configuration parameters have default values that should suffice for use.
	Config

	// HTTPClient represents an HTTP client associated with a Client instance.
	// It is used to send Client requests to server and receive responses.
	HTTPClient *httputil.HTTPClient
	// contains filtered or unexported fields
}

Client represents an Oracle NoSQL database client used to access the Oracle NoSQL database cloud service or on-premise Oracle NoSQL database servers.

func NewClient

func NewClient(cfg Config) (*Client, error)

NewClient creates a Client instance with the specified Config. If any errors occurred during the creation, it returns a non-nil error and a nil Client that should not be used. Applications should check the returned error before using the returned Client instance.

Applications should call the Close() method on the Client when it terminates.

Example (Cloud)
package main

import (
	"fmt"

	"github.com/oracle/nosql-go-sdk/nosqldb"
)

func main() {
	// Specify configurations for the client that connects to the NoSQL cloud service.
	//
	// This assumes the required user credentials are specified in the
	// default OCI configuration file ~/.oci/config.
	//
	// [DEFAULT]
	// tenancy=<your-tenancy-id>
	// user=<your-user-id>
	// fingerprint=<fingerprint-of-your-public-key>
	// key_file=<path-to-your-private-key-file>
	// pass_phrase=<optional-passphrase>
	//
	cfg := nosqldb.Config{
		Region: "us-phoenix-1",
	}

	client, err := nosqldb.NewClient(cfg)
	if err != nil {
		fmt.Printf("failed to create a NoSQL client: %v\n", err)
		return
	}
	defer client.Close()
	// Perform database operations using client APIs.
	// ...
}
Output:

Example (CloudSim)
package main

import (
	"fmt"

	"github.com/oracle/nosql-go-sdk/nosqldb"
)

func main() {
	// Specify configurations for the client that connects to the NoSQL cloud simulator.
	cfg := nosqldb.Config{
		Mode:     "cloudsim",
		Endpoint: "http://localhost:8080",
	}

	client, err := nosqldb.NewClient(cfg)
	if err != nil {
		fmt.Printf("failed to create a NoSQL client: %v\n", err)
		return
	}
	defer client.Close()
	// Perform database operations using client APIs.
	// ...
}
Output:

Example (OnPremise)
package main

import (
	"fmt"

	"github.com/oracle/nosql-go-sdk/nosqldb"
	"github.com/oracle/nosql-go-sdk/nosqldb/httputil"
)

func main() {
	// Specify configurations for the client that connects to on-premise NoSQL servers.
	cfg := nosqldb.Config{
		Endpoint: "https://localhost:8080",
		Mode:     "onprem",
		Username: "testUser",
		Password: []byte("F;0s2M0;-Tdr"),
		// Specify InsecureSkipVerify to skip verification for server certificate.
		// This is used for testing, not recommended for production use.
		HTTPConfig: httputil.HTTPConfig{
			InsecureSkipVerify: true,
		},
	}

	client, err := nosqldb.NewClient(cfg)
	if err != nil {
		fmt.Printf("failed to create a NoSQL client: %v\n", err)
		return
	}
	defer client.Close()
	// Perform database operations using client APIs.
	// ...
}
Output:

func (*Client) Close

func (c *Client) Close() error

Close releases any resources used by Client.

func (*Client) Delete

func (c *Client) Delete(req *DeleteRequest) (*DeleteResult, error)

Delete deletes a row from a table.

The row is identified using a primary key specified in DeleteRequest.Key.

By default a delete operation is unconditional and will succeed if the specified row exists. Delete operations can be made conditional based on whether the version of an existing row matches that specified in DeleteRequest.MatchVersion.

It is also possible, on failure, to return information about the existing row. The row, including it's version can be optionally returned if a delete operation fails because of a version mismatch. The existing row information will only be returned if DeleteRequest.ReturnRow is true and the operation fails because DeleteRequest.MatchVersion is used and the operation fails because the row exists and its version does not match.

Use of DeleteRequest.ReturnRow may result in additional consumed read capacity. If the operation is successful there will be no information returned about the previous row.

Example
package main

import (
	"fmt"
	"time"

	"github.com/oracle/nosql-go-sdk/nosqldb"
	"github.com/oracle/nosql-go-sdk/nosqldb/types"
)

func main() {
	cfg := nosqldb.Config{
		Mode:     "cloudsim",
		Endpoint: "http://localhost:8080",
	}

	client, err := nosqldb.NewClient(cfg)
	if err != nil {
		fmt.Printf("failed to create a NoSQL client: %v\n", err)
		return
	}
	defer client.Close()

	// Sample table:
	//
	// CREATE TABLE employees (employee_id INTEGER, first_name STRING, last_name STRING,
	// email STRING, phone_number STRING, hire_date TIMESTAMP(0), salary DOUBLE,
	// department_id INTEGER, PRIMARY KEY(shard(department_id), employee_id))
	empID := 100
	deptID := 90
	pk := &types.MapValue{}
	pk.Put("employee_id", empID).Put("department_id", deptID)

	req := &nosqldb.DeleteRequest{
		TableName: "employees",
		Key:       pk,
		Timeout:   5 * time.Second,
	}

	res, err := client.Delete(req)
	if err != nil {
		fmt.Printf("Delete() failed: %v\n", err)
		return
	}

	if res.Success {
		fmt.Printf("delete row(employee_id=%d, department_id=%d) succeeded.\n", empID, deptID)
	} else {
		fmt.Printf("delete row(employee_id=%d, department_id=%d) failed.\n", empID, deptID)
	}
}
Output:

Example (DeleteIfVersion)
package main

import (
	"fmt"
	"time"

	"github.com/oracle/nosql-go-sdk/nosqldb"
	"github.com/oracle/nosql-go-sdk/nosqldb/types"
)

func main() {
	cfg := nosqldb.Config{
		Mode:     "cloudsim",
		Endpoint: "http://localhost:8080",
	}

	client, err := nosqldb.NewClient(cfg)
	if err != nil {
		fmt.Printf("failed to create a NoSQL client: %v\n", err)
		return
	}
	defer client.Close()

	// Sample table:
	//
	// CREATE TABLE employees (employee_id INTEGER, first_name STRING, last_name STRING,
	// email STRING, phone_number STRING, hire_date TIMESTAMP(0), salary DOUBLE,
	// department_id INTEGER, PRIMARY KEY(shard(department_id), employee_id))
	empID := 100
	deptID := 90
	pk := &types.MapValue{}
	pk.Put("employee_id", empID).Put("department_id", deptID)

	getReq := &nosqldb.GetRequest{
		TableName: "employees",
		Key:       pk,
		Timeout:   5 * time.Second,
	}

	getRes, err := client.Get(getReq)
	if err != nil {
		fmt.Printf("Get() failed: %v\n", err)
		return
	}

	currVersion := getRes.Version

	req := &nosqldb.DeleteRequest{
		TableName:    "employees",
		Key:          pk,
		Timeout:      5 * time.Second,
		MatchVersion: currVersion,
	}

	res, err := client.Delete(req)
	if err != nil {
		fmt.Printf("Delete() failed: %v\n", err)
		return
	}

	if res.Success {
		fmt.Printf("delete row(option=DeleteIfVersion, employee_id=%d, department_id=%d) succeeded.\n", empID, deptID)
	} else {
		fmt.Printf("delete row(option=DeleteIfVersion, employee_id=%d, department_id=%d) failed.\n", empID, deptID)
	}
}
Output:

func (*Client) DoSystemRequest

func (c *Client) DoSystemRequest(req *SystemRequest) (*SystemResult, error)

DoSystemRequest performs a system operation such as administrative operations that do not affect a specific table. For table-specific operations use DoTableRequest() or DoTableRequestAndWait().

Examples of statements in the SystemRequest passed to this method include:

CREATE NAMESPACE mynamespace
CREATE USER some_user IDENTIFIED BY password
CREATE ROLE some_role
GRANT ROLE some_role TO USER some_user

These operations are implicitly asynchronous. DoSystemRequest does not wait for completion of the operation, it returns a SystemResult that contains an operation id representing the operation being performed. The caller must poll using SystemResult.WaitForCompletion() method to determine when it has completed.

This method is used for on-premise only.

Example
package main

import (
	"fmt"
	"time"

	"github.com/oracle/nosql-go-sdk/nosqldb"
	"github.com/oracle/nosql-go-sdk/nosqldb/httputil"
)

func main() {
	cfg := nosqldb.Config{
		Endpoint: "https://localhost:8080",
		Mode:     "onprem",
		Username: "testUser",
		Password: []byte("F;0s2M0;-Tdr"),
		// Specify InsecureSkipVerify to skip verification for server certificate.
		// This is used for testing, not recommended for production use.
		HTTPConfig: httputil.HTTPConfig{
			InsecureSkipVerify: true,
		},
	}

	client, err := nosqldb.NewClient(cfg)
	if err != nil {
		fmt.Printf("failed to create a NoSQL client: %v\n", err)
		return
	}
	defer client.Close()

	req := &nosqldb.SystemRequest{
		Statement: "CREATE NAMESPACE ns01",
		Timeout:   3 * time.Second,
	}

	res, err := client.DoSystemRequest(req)
	if err != nil {
		fmt.Printf("DoSystemRequest(): failed to create namespace \"ns01\": %v\n", err)
		return
	}

	_, err = res.WaitForCompletion(client, 10*time.Second, 2*time.Second)
	if err != nil {
		fmt.Printf("failed to create namespace \"ns01\": %v\n", err)
		return
	}

	fmt.Printf("namespace \"ns01\" has been created\n")
}
Output:

func (*Client) DoSystemRequestAndWait

func (c *Client) DoSystemRequestAndWait(statement string, timeout, pollInterval time.Duration) (*SystemResult, error)

DoSystemRequestAndWait is a convenience method used to perform a system operation such as administrative operations that do not affect a specific table, and waits for completion of the operation. For table-specific operations use DoTableRequest() or DoTableRequestAndWait().

Examples of statements passed to this method include:

CREATE NAMESPACE mynamespace
CREATE USER some_user IDENTIFIED BY password
CREATE ROLE some_role
GRANT ROLE some_role TO USER some_user

These are potentially long-running operations that take time to complete. This method allows specifying a timeout that represents a time duration to wait for completion of the operation, and a pollInterval that represents a time duration to wait between two consecutive polling attempts. If the operation does not complete when the specified timeout elapses, a RequestTimeout error is returned.

This method is used for on-premise only.

Example
package main

import (
	"fmt"
	"time"

	"github.com/oracle/nosql-go-sdk/nosqldb"
	"github.com/oracle/nosql-go-sdk/nosqldb/httputil"
)

func main() {
	cfg := nosqldb.Config{
		Endpoint: "https://localhost:8080",
		Mode:     "onprem",
		Username: "testUser",
		Password: []byte("F;0s2M0;-Tdr"),
		// Specify InsecureSkipVerify to skip verification for server certificate.
		// This is used for testing, not recommended for production use.
		HTTPConfig: httputil.HTTPConfig{
			InsecureSkipVerify: true,
		},
	}

	client, err := nosqldb.NewClient(cfg)
	if err != nil {
		fmt.Printf("failed to create a NoSQL client: %v\n", err)
		return
	}
	defer client.Close()

	stmt := "CREATE USER user01 IDENTIFIED BY \"F;0s2M0;-Tdr\""
	_, err = client.DoSystemRequestAndWait(stmt, 10*time.Second, 2*time.Second)
	if err != nil {
		fmt.Printf("DoSystemRequest(): failed to create user \"user01\": %v\n", err)
		return
	}

	fmt.Printf("user \"user01\" has been created\n")
}
Output:

func (*Client) DoTableRequest

func (c *Client) DoTableRequest(req *TableRequest) (*TableResult, error)

DoTableRequest performs an operation that manages table schema or changes table limits.

This method can be used to perform the following operations:

create tables
drop tables
modify tables: add or remove columns
create indexes
drop indexes
change table limits of an existing table

These operations are implicitly asynchronous. DoTableRequest does not wait for completion of the operation, it returns a TableResult that contains an operation id representing the operation being performed. The caller should use the TableResult.WaitForCompletion() method to determine when it has completed.

Example
package main

import (
	"fmt"
	"time"

	"github.com/oracle/nosql-go-sdk/nosqldb"
)

func main() {
	cfg := nosqldb.Config{
		Mode:     "cloudsim",
		Endpoint: "http://localhost:8080",
	}

	client, err := nosqldb.NewClient(cfg)
	if err != nil {
		fmt.Printf("failed to create a NoSQL client: %v\n", err)
		return
	}
	defer client.Close()

	stmt := "CREATE TABLE employees (employee_id INTEGER, first_name STRING, last_name STRING," +
		"email STRING, phone_number STRING, hire_date TIMESTAMP(0), salary DOUBLE," +
		"department_id INTEGER, PRIMARY KEY(shard(department_id), employee_id))"

	req := &nosqldb.TableRequest{
		Statement: stmt,
		TableLimits: &nosqldb.TableLimits{
			ReadUnits:  200,
			WriteUnits: 200,
			StorageGB:  2,
		},
		Timeout: 5 * time.Second,
	}

	res, err := client.DoTableRequest(req)
	if err != nil {
		fmt.Printf("DoTableRequest() failed: %v\n", err)
		return
	}

	res, err = res.WaitForCompletion(client, 10*time.Second, 2*time.Second)
	if err != nil {
		fmt.Printf("failed to create table \"employees\": %v\n", err)
		return
	}

	fmt.Printf("table \"employees\" has been created. Table state: %s\n", res.State)
}
Output:

func (*Client) DoTableRequestAndWait

func (c *Client) DoTableRequestAndWait(req *TableRequest, timeout, pollInterval time.Duration) (*TableResult, error)

DoTableRequestAndWait performs an operation that manages table schema or changes table limits and waits for completion of the operation.

This method can be used to perform the following operations:

create tables
drop tables
modify tables: add or remove columns
create indexes
drop indexes
change table limits of an existing table

These are potentially long-running operations that take time to complete. This method allows specifying a timeout that represents a time duration to wait for completion of the operation, and a pollInterval that represents a time duration to wait between two consecutive polling attempts. If the operation does not complete when the specified timeout elapses, a RequestTimeout error is returned.

Example (ChangeTableLimits)
package main

import (
	"fmt"
	"time"

	"github.com/oracle/nosql-go-sdk/nosqldb"
)

func main() {
	cfg := nosqldb.Config{
		Mode:     "cloudsim",
		Endpoint: "http://localhost:8080",
	}

	client, err := nosqldb.NewClient(cfg)
	if err != nil {
		fmt.Printf("failed to create a NoSQL client: %v\n", err)
		return
	}
	defer client.Close()

	req := &nosqldb.TableRequest{
		TableName: "employees",
		TableLimits: &nosqldb.TableLimits{
			ReadUnits:  400,
			WriteUnits: 400,
			StorageGB:  2,
		},
		Timeout: 3 * time.Second,
	}

	_, err = client.DoTableRequestAndWait(req, 10*time.Second, 2*time.Second)
	if err != nil {
		fmt.Printf("DoTableRequestAndWait(): failed to change table limits for table \"employees\": %v\n", err)
		return
	}

	fmt.Println("table limits for \"employees\" has been changed.")
}
Output:

Example (CreateTable)
package main

import (
	"fmt"
	"time"

	"github.com/oracle/nosql-go-sdk/nosqldb"
)

func main() {
	cfg := nosqldb.Config{
		Mode:     "cloudsim",
		Endpoint: "http://localhost:8080",
	}

	client, err := nosqldb.NewClient(cfg)
	if err != nil {
		fmt.Printf("failed to create a NoSQL client: %v\n", err)
		return
	}
	defer client.Close()

	stmt := "CREATE TABLE employees (employee_id INTEGER, first_name STRING, last_name STRING," +
		"email STRING, phone_number STRING, hire_date TIMESTAMP(0), salary DOUBLE," +
		"department_id INTEGER, PRIMARY KEY(shard(department_id), employee_id))"

	req := &nosqldb.TableRequest{
		Statement: stmt,
		TableLimits: &nosqldb.TableLimits{
			ReadUnits:  200,
			WriteUnits: 200,
			StorageGB:  2,
		},
		Timeout: 3 * time.Second,
	}

	res, err := client.DoTableRequestAndWait(req, 10*time.Second, 2*time.Second)
	if err != nil {
		fmt.Printf("DoTableRequestAndWait(): failed to create table \"employees\": %v\n", err)
		return
	}

	fmt.Printf("table \"employees\" has been created. Table state: %s\n", res.State)
}
Output:

Example (DropTable)
package main

import (
	"fmt"
	"time"

	"github.com/oracle/nosql-go-sdk/nosqldb"
)

func main() {
	cfg := nosqldb.Config{
		Mode:     "cloudsim",
		Endpoint: "http://localhost:8080",
	}

	client, err := nosqldb.NewClient(cfg)
	if err != nil {
		fmt.Printf("failed to create a NoSQL client: %v\n", err)
		return
	}
	defer client.Close()

	stmt := "DROP TABLE IF EXISTS employees"

	req := &nosqldb.TableRequest{
		Statement: stmt,
		Timeout:   3 * time.Second,
	}

	_, err = client.DoTableRequestAndWait(req, 10*time.Second, 2*time.Second)
	if err != nil {
		fmt.Printf("DoTableRequestAndWait(): failed to drop table \"employees\": %v\n", err)
		return
	}

	fmt.Println("table \"employees\" has been dropped.")
}
Output:

func (*Client) EnableRateLimiting added in v1.2.2

func (c *Client) EnableRateLimiting(enable bool, usePercent float64)

EnableRateLimiting is for testing purposes only. Applications should set RateLimitingEnabled to true in the client Config to enable rate limiting.

func (*Client) Get

func (c *Client) Get(req *GetRequest) (*GetResult, error)

Get retrieves the row associated with a primary key.

The table name and primary key for the get operation must be specified in the GetRequest, otherwise an IllegalArgument error is returned.

On success the returned GetResult is non-nil, the value of the row is available in GetResult.Value. If there are no matching rows GetResult.Value will be nil.

The default Consistency used for the operation is types.Eventual unless an explicit value has been set using GetRequest.Consistency or RequestConfig.Consistency.

Use of types.Absolute consistency may affect latency of the operation and may result in additional cost for the operation.

Example
package main

import (
	"fmt"
	"time"

	"github.com/oracle/nosql-go-sdk/nosqldb"
	"github.com/oracle/nosql-go-sdk/nosqldb/types"
)

func main() {
	cfg := nosqldb.Config{
		Mode:     "cloudsim",
		Endpoint: "http://localhost:8080",
	}

	client, err := nosqldb.NewClient(cfg)
	if err != nil {
		fmt.Printf("failed to create a NoSQL client: %v\n", err)
		return
	}
	defer client.Close()

	// Sample table:
	//
	// CREATE TABLE employees (employee_id INTEGER, first_name STRING, last_name STRING,
	// email STRING, phone_number STRING, hire_date TIMESTAMP(0), salary DOUBLE,
	// department_id INTEGER, PRIMARY KEY(shard(department_id), employee_id))
	empID := 100
	deptID := 90
	pk := &types.MapValue{}
	pk.Put("employee_id", empID).Put("department_id", deptID)

	req := &nosqldb.GetRequest{
		TableName: "employees",
		Key:       pk,
		Timeout:   3 * time.Second,
	}

	res, err := client.Get(req)
	if err != nil {
		fmt.Printf("Get() failed: %v\n", err)
		return
	}

	if res.RowExists() {
		fmt.Printf("got the row: %s\n", res.ValueAsJSON())
	} else {
		fmt.Printf("the requested row(employee_id=%d, department_id=%d) does not exist.\n", empID, deptID)
	}
}
Output:

func (*Client) GetIndexes

func (c *Client) GetIndexes(req *GetIndexesRequest) (*GetIndexesResult, error)

GetIndexes retrieves information about an index, or all indexes on a table. If no index name is specified in the GetIndexesRequest, then information on all indexes is returned.

The table name must be specified in the GetIndexesRequest, otherwise an IllegalArgument error is returned.

On success the returned GetIndexesResult is non-nil and contains desired index information.

Example
package main

import (
	"fmt"
	"time"

	"github.com/oracle/nosql-go-sdk/nosqldb"
)

func main() {
	cfg := nosqldb.Config{
		Mode:     "cloudsim",
		Endpoint: "http://localhost:8080",
	}

	client, err := nosqldb.NewClient(cfg)
	if err != nil {
		fmt.Printf("failed to create a NoSQL client: %v\n", err)
		return
	}
	defer client.Close()

	req := &nosqldb.GetIndexesRequest{
		TableName: "employees",
		Timeout:   3 * time.Second,
	}

	res, err := client.GetIndexes(req)
	if err != nil {
		fmt.Printf("GetIndexes(): failed to get indexes on table \"employees\": %v\n", err)
		return
	}

	fmt.Printf("number of indexes on table \"employees\": %d\n", len(res.Indexes))
	for i, idx := range res.Indexes {
		fmt.Printf("%d: index name: %s\n", i+1, idx.IndexName)
	}
}
Output:

func (*Client) GetSerialVersion added in v1.3.0

func (c *Client) GetSerialVersion() int16

GetSerialVersion is used for tests.

func (*Client) GetSystemStatus

func (c *Client) GetSystemStatus(req *SystemStatusRequest) (*SystemResult, error)

GetSystemStatus checks the status of an operation previously performed using DoSystemRequest().

Example
package main

import (
	"fmt"
	"time"

	"github.com/oracle/nosql-go-sdk/nosqldb"
	"github.com/oracle/nosql-go-sdk/nosqldb/httputil"
)

func main() {
	cfg := nosqldb.Config{
		Endpoint: "https://localhost:8080",
		Mode:     "onprem",
		Username: "testUser",
		Password: []byte("F;0s2M0;-Tdr"),
		// Specify InsecureSkipVerify to skip verification for server certificate.
		// This is used for testing, not recommended for production use.
		HTTPConfig: httputil.HTTPConfig{
			InsecureSkipVerify: true,
		},
	}

	client, err := nosqldb.NewClient(cfg)
	if err != nil {
		fmt.Printf("failed to create a NoSQL client: %v\n", err)
		return
	}
	defer client.Close()

	sysReq := &nosqldb.SystemRequest{
		Statement: "CREATE ROLE role01",
		Timeout:   3 * time.Second,
	}

	sysRes, err := client.DoSystemRequest(sysReq)
	if err != nil {
		fmt.Printf("DoSystemRequest(): failed to create role \"role01\": %v\n", err)
		return
	}

	req := &nosqldb.SystemStatusRequest{
		OperationID: sysRes.OperationID,
		Timeout:     3 * time.Second,
	}

	sysRes, err = client.GetSystemStatus(req)
	if err != nil {
		fmt.Printf("GetSystemStatus() failed: %v\n", err)
		return
	}

	fmt.Printf("current state of system request for the \"CREATE ROLE role01\" operation: %s\n", sysRes.State)
}
Output:

func (*Client) GetTable

func (c *Client) GetTable(req *GetTableRequest) (*TableResult, error)

GetTable retrieves static information about the specified table including its state, provisioned throughput, capacity and schema. Dynamic information such as usage is obtained using GetTableUsage.

The table name must be specified in the GetTableRequest, otherwise an IllegalArgument error is returned.

Throughput, capacity and usage information is only available in the returned TableResult when using the Cloud Service and will be nil or not defined for on-premise.

Example
package main

import (
	"fmt"
	"time"

	"github.com/oracle/nosql-go-sdk/nosqldb"
)

func main() {
	cfg := nosqldb.Config{
		Mode:     "cloudsim",
		Endpoint: "http://localhost:8080",
	}

	client, err := nosqldb.NewClient(cfg)
	if err != nil {
		fmt.Printf("failed to create a NoSQL client: %v\n", err)
		return
	}
	defer client.Close()

	req := &nosqldb.GetTableRequest{
		TableName: "employees",
		Timeout:   3 * time.Second,
	}

	res, err := client.GetTable(req)
	if err != nil {
		fmt.Printf("GetTable() failed: %v\n", err)
		return
	}

	fmt.Printf("got table info for \"employees\": state=%s, limits=%v\n", res.State, res.Limits)
}
Output:

func (*Client) GetTableUsage

func (c *Client) GetTableUsage(req *TableUsageRequest) (*TableUsageResult, error)

GetTableUsage gets dynamic information about the specified table such as the current throughput usage. Usage information is collected in time slices and returned in individual usage records. It is possible to specify a time-based range of usage records using StartTime and EndTime of TableUsageRequest.

This method is used for cloud service only.

func (*Client) ListNamespaces

func (c *Client) ListNamespaces() ([]string, error)

ListNamespaces returns the namespaces in a store as a slice of string.

This method is used for on-premise only.

Example
package main

import (
	"fmt"

	"github.com/oracle/nosql-go-sdk/nosqldb"
	"github.com/oracle/nosql-go-sdk/nosqldb/httputil"
)

func main() {
	cfg := nosqldb.Config{
		Endpoint: "https://localhost:8080",
		Mode:     "onprem",
		Username: "testUser",
		Password: []byte("F;0s2M0;-Tdr"),
		// Specify InsecureSkipVerify to skip verification for server certificate.
		// This is used for testing, not recommended for production use.
		HTTPConfig: httputil.HTTPConfig{
			InsecureSkipVerify: true,
		},
	}

	client, err := nosqldb.NewClient(cfg)
	if err != nil {
		fmt.Printf("failed to create a NoSQL client: %v\n", err)
		return
	}
	defer client.Close()

	namespaces, err := client.ListNamespaces()
	if err != nil {
		fmt.Printf("ListNamespaces() failed: %v\n", err)
		return
	}

	fmt.Printf("number of namespaces available: %d\n", len(namespaces))
	for i, ns := range namespaces {
		fmt.Printf("%d: namespace name: %s\n", i+1, ns)
	}
}
Output:

func (*Client) ListRoles

func (c *Client) ListRoles() ([]string, error)

ListRoles returns the roles in a store as a slice of string

This method is used for on-premise only.

Example
package main

import (
	"fmt"

	"github.com/oracle/nosql-go-sdk/nosqldb"
	"github.com/oracle/nosql-go-sdk/nosqldb/httputil"
)

func main() {
	cfg := nosqldb.Config{
		Endpoint: "https://localhost:8080",
		Mode:     "onprem",
		Username: "testUser",
		Password: []byte("F;0s2M0;-Tdr"),
		// Specify InsecureSkipVerify to skip verification for server certificate.
		// This is used for testing, not recommended for production use.
		HTTPConfig: httputil.HTTPConfig{
			InsecureSkipVerify: true,
		},
	}

	client, err := nosqldb.NewClient(cfg)
	if err != nil {
		fmt.Printf("failed to create a NoSQL client: %v\n", err)
		return
	}
	defer client.Close()

	roles, err := client.ListRoles()
	if err != nil {
		fmt.Printf("ListRoles() failed: %v\n", err)
		return
	}

	fmt.Printf("number of roles available: %d\n", len(roles))
	for i, ns := range roles {
		fmt.Printf("%d: role name: %s\n", i+1, ns)
	}
}
Output:

func (*Client) ListTables

func (c *Client) ListTables(req *ListTablesRequest) (*ListTablesResult, error)

ListTables lists all available table names. If further information about a specific table is desired the GetTable method may be used. If a given identity has access to a large number of tables the list may be paged by specifying the StartIndex and Limit field of the request.

Example
package main

import (
	"fmt"
	"time"

	"github.com/oracle/nosql-go-sdk/nosqldb"
)

func main() {
	cfg := nosqldb.Config{
		Mode:     "cloudsim",
		Endpoint: "http://localhost:8080",
	}

	client, err := nosqldb.NewClient(cfg)
	if err != nil {
		fmt.Printf("failed to create a NoSQL client: %v\n", err)
		return
	}
	defer client.Close()

	req := &nosqldb.ListTablesRequest{
		Timeout: 3 * time.Second,
	}

	res, err := client.ListTables(req)
	if err != nil {
		fmt.Printf("ListTables() failed: %v\n", err)
		return
	}

	fmt.Printf("number of tables available: %d\n", len(res.Tables))
	for i, table := range res.Tables {
		fmt.Printf("%d: table name: %s\n", i+1, table)
	}
}
Output:

func (*Client) ListUsers

func (c *Client) ListUsers() ([]UserInfo, error)

ListUsers returns the users in a store as a slice of UserInfo.

This method is used for on-premise only.

Example
package main

import (
	"fmt"

	"github.com/oracle/nosql-go-sdk/nosqldb"
	"github.com/oracle/nosql-go-sdk/nosqldb/httputil"
)

func main() {
	cfg := nosqldb.Config{
		Endpoint: "https://localhost:8080",
		Mode:     "onprem",
		Username: "testUser",
		Password: []byte("F;0s2M0;-Tdr"),
		// Specify InsecureSkipVerify to skip verification for server certificate.
		// This is used for testing, not recommended for production use.
		HTTPConfig: httputil.HTTPConfig{
			InsecureSkipVerify: true,
		},
	}

	client, err := nosqldb.NewClient(cfg)
	if err != nil {
		fmt.Printf("failed to create a NoSQL client: %v\n", err)
		return
	}
	defer client.Close()

	users, err := client.ListUsers()
	if err != nil {
		fmt.Printf("ListUsers() failed: %v\n", err)
		return
	}

	fmt.Printf("number of users available: %d\n", len(users))
	for i, u := range users {
		fmt.Printf("%d: username: %s\n", i+1, u.Name)
	}
}
Output:

func (*Client) MultiDelete

func (c *Client) MultiDelete(req *MultiDeleteRequest) (*MultiDeleteResult, error)

MultiDelete deletes multiple rows from a table in an atomic operation.

The key used may be partial but must contain all of the fields that are in the shard key.

A range may be specified to delete a range of keys.

Example
package main

import (
	"fmt"
	"time"

	"github.com/oracle/nosql-go-sdk/nosqldb"
	"github.com/oracle/nosql-go-sdk/nosqldb/types"
)

func main() {
	cfg := nosqldb.Config{
		Mode:     "cloudsim",
		Endpoint: "http://localhost:8080",
	}

	client, err := nosqldb.NewClient(cfg)
	if err != nil {
		fmt.Printf("failed to create a NoSQL client: %v\n", err)
		return
	}
	defer client.Close()

	// Sample table:
	//
	// CREATE TABLE employees (employee_id INTEGER, first_name STRING, last_name STRING,
	// email STRING, phone_number STRING, hire_date TIMESTAMP(0), salary DOUBLE,
	// department_id INTEGER, PRIMARY KEY(shard(department_id), employee_id))
	deptID := 90
	sk := &types.MapValue{}
	sk.Put("department_id", deptID)

	req := &nosqldb.MultiDeleteRequest{
		TableName: "employees",
		Key:       sk,
		Timeout:   5 * time.Second,
	}

	res, err := client.MultiDelete(req)
	if err != nil {
		fmt.Printf("MultiDelete() failed: %v\n", err)
		return
	}

	fmt.Printf("number of rows deleted: %d\n", res.NumDeleted)
}
Output:

func (*Client) Prepare

func (c *Client) Prepare(req *PrepareRequest) (*PrepareResult, error)

Prepare prepares a query for execution and reuse. See the Query() method for general information and restrictions.

It is recommended that prepared queries are used when the same query will run multiple times as execution is much more efficient than starting with a query string every time. The query language and Query() method support query variables to assist with re-use.

func (*Client) Put

func (c *Client) Put(req *PutRequest) (*PutResult, error)

Put puts a row into a table.

This method creates a new row or overwrites an existing row entirely. The value used for the put is specified in PutRequest.Value and must contain a complete primary key and all required fields.

It is not possible to put part of a row. Any fields that are not provided will be defaulted, overwriting any existing value. Fields that are not nullable or defaulted must be provided or an error will be returned.

By default a put operation is unconditional, but put operations can be conditional based on existence, or not, of a previous value as well as conditional on the version of the existing value.

a. Use PutIfAbsent option to do a put only if there is no existing row that matches the primary key.

b. Use PutIfPresent option to do a put only if there is an existing row that matches the primary key.

c. Use PutIfVersion option to do a put only if there is an existing row that matches the primary key and its version matches that provided.

If put operation succeeds, this method retuns a non-nil PutResult.Version representing the current version of the row that is put.

If put operation fails, this method returns a nil PutResult.Version. It is also possible, on failure, to return information about the existing row. The row, including it's version can be optionally returned if a put operation fails because of a version mismatch or if the operation fails because the row already exists. The existing row information will only be returned if PutRequest.ReturnRow is true and one of the following occurs:

a. The PutIfAbsent option is used and the operation fails because the row already exists.

b. The PutIfVersion option is used and the operation fails because the row exists and its version does not match.

Use of PutRequest.ReturnRow may result in additional consumed read capacity. If the operation is successful there will be no information returned about the previous row.

Example
package main

import (
	"fmt"
	"time"

	"github.com/oracle/nosql-go-sdk/nosqldb"
	"github.com/oracle/nosql-go-sdk/nosqldb/types"
)

func main() {
	cfg := nosqldb.Config{
		Mode:     "cloudsim",
		Endpoint: "http://localhost:8080",
	}

	client, err := nosqldb.NewClient(cfg)
	if err != nil {
		fmt.Printf("failed to create a NoSQL client: %v\n", err)
		return
	}
	defer client.Close()

	// Sample table:
	//
	// CREATE TABLE employees (employee_id INTEGER, first_name STRING, last_name STRING,
	// email STRING, phone_number STRING, hire_date TIMESTAMP(0), salary DOUBLE,
	// department_id INTEGER, PRIMARY KEY(shard(department_id), employee_id))
	empID := 170
	deptID := 80
	value := &types.MapValue{}
	value.Put("employee_id", empID).Put("department_id", deptID)
	value.Put("first_name", "Tayler").Put("last_name", "Fox")
	value.Put("email", "TFOX@example.com").Put("phone_number", "011.44.1343.729268")
	value.Put("hire_date", "2006-01-24").Put("salary", 17000)

	req := &nosqldb.PutRequest{
		TableName: "employees",
		Value:     value,
		Timeout:   5 * time.Second,
	}

	res, err := client.Put(req)
	if err != nil {
		fmt.Printf("Put() failed: %v\n", err)
		return
	}

	if res.Success() {
		fmt.Printf("put row(employee_id=%d, department_id=%d) succeeded.\n", empID, deptID)
	} else {
		fmt.Printf("put row(employee_id=%d, department_id=%d) failed.\n", empID, deptID)
	}
}
Output:

Example (PutIfAbsent)
package main

import (
	"fmt"
	"time"

	"github.com/oracle/nosql-go-sdk/nosqldb"
	"github.com/oracle/nosql-go-sdk/nosqldb/types"
)

func main() {
	cfg := nosqldb.Config{
		Mode:     "cloudsim",
		Endpoint: "http://localhost:8080",
	}

	client, err := nosqldb.NewClient(cfg)
	if err != nil {
		fmt.Printf("failed to create a NoSQL client: %v\n", err)
		return
	}
	defer client.Close()

	// Sample table:
	//
	// CREATE TABLE employees (employee_id INTEGER, first_name STRING, last_name STRING,
	// email STRING, phone_number STRING, hire_date TIMESTAMP(0), salary DOUBLE,
	// department_id INTEGER, PRIMARY KEY(shard(department_id), employee_id))
	empID := 171
	deptID := 80
	value := &types.MapValue{}
	value.Put("employee_id", empID).Put("department_id", deptID)
	value.Put("first_name", "William").Put("last_name", "Smith")
	value.Put("email", "WSMITH@example.com").Put("phone_number", "011.44.1343.629268")
	value.Put("hire_date", "2007-02-23").Put("salary", 14000)

	req := &nosqldb.PutRequest{
		TableName: "employees",
		Value:     value,
		Timeout:   5 * time.Second,
		PutOption: types.PutIfAbsent,
		ReturnRow: true,
	}

	res, err := client.Put(req)
	if err != nil {
		fmt.Printf("Put() failed: %v\n", err)
		return
	}

	if res.Success() {
		fmt.Printf("put row(option=PutIfAbsent, employee_id=%d, department_id=%d) succeeded.\n", empID, deptID)
	} else {
		fmt.Printf("put row(option=PutIfAbsent, employee_id=%d, department_id=%d) failed.\n", empID, deptID)
	}
}
Output:

Example (PutIfPresent)
package main

import (
	"fmt"
	"time"

	"github.com/oracle/nosql-go-sdk/nosqldb"
	"github.com/oracle/nosql-go-sdk/nosqldb/types"
)

func main() {
	cfg := nosqldb.Config{
		Mode:     "cloudsim",
		Endpoint: "http://localhost:8080",
	}

	client, err := nosqldb.NewClient(cfg)
	if err != nil {
		fmt.Printf("failed to create a NoSQL client: %v\n", err)
		return
	}
	defer client.Close()

	// Sample table:
	//
	// CREATE TABLE employees (employee_id INTEGER, first_name STRING, last_name STRING,
	// email STRING, phone_number STRING, hire_date TIMESTAMP(0), salary DOUBLE,
	// department_id INTEGER, PRIMARY KEY(shard(department_id), employee_id))
	empID := 170
	deptID := 80
	value := &types.MapValue{}
	value.Put("employee_id", empID).Put("department_id", deptID)
	value.Put("first_name", "Tayler").Put("last_name", "Fox")
	value.Put("email", "TFOX@example.com").Put("phone_number", "011.44.1343.729268")
	value.Put("hire_date", "2006-01-24").Put("salary", 19000)

	req := &nosqldb.PutRequest{
		TableName: "employees",
		Value:     value,
		Timeout:   5 * time.Second,
		PutOption: types.PutIfPresent,
	}

	res, err := client.Put(req)
	if err != nil {
		fmt.Printf("Put() failed: %v\n", err)
		return
	}

	if res.Success() {
		fmt.Printf("put row(option=PutIfPresent, employee_id=%d, department_id=%d) succeeded.\n", empID, deptID)
	} else {
		fmt.Printf("put row(option=PutIfPresent, employee_id=%d, department_id=%d) failed.\n", empID, deptID)
	}
}
Output:

Example (PutIfVersion)
package main

import (
	"fmt"
	"time"

	"github.com/oracle/nosql-go-sdk/nosqldb"
	"github.com/oracle/nosql-go-sdk/nosqldb/types"
)

func main() {
	cfg := nosqldb.Config{
		Mode:     "cloudsim",
		Endpoint: "http://localhost:8080",
	}

	client, err := nosqldb.NewClient(cfg)
	if err != nil {
		fmt.Printf("failed to create a NoSQL client: %v\n", err)
		return
	}
	defer client.Close()

	// Sample table:
	//
	// CREATE TABLE employees (employee_id INTEGER, first_name STRING, last_name STRING,
	// email STRING, phone_number STRING, hire_date TIMESTAMP(0), salary DOUBLE,
	// department_id INTEGER, PRIMARY KEY(shard(department_id), employee_id))
	empID := 172
	deptID := 80
	pk := &types.MapValue{}
	pk.Put("employee_id", empID).Put("department_id", deptID)

	getReq := &nosqldb.GetRequest{
		TableName: "employees",
		Key:       pk,
		Timeout:   5 * time.Second,
	}

	getRes, err := client.Get(getReq)
	if err != nil {
		fmt.Printf("Get() failed: %v\n", err)
		return
	}

	currVersion := getRes.Version

	value := &types.MapValue{}
	value.Put("employee_id", empID).Put("department_id", deptID)
	value.Put("first_name", "Elizabeth").Put("last_name", "Bates")
	value.Put("email", "EBATES@example.com").Put("phone_number", "011.44.1343.529268")
	value.Put("hire_date", "2007-03-24").Put("salary", 15300)

	req := &nosqldb.PutRequest{
		TableName:    "employees",
		Value:        value,
		Timeout:      5 * time.Second,
		PutOption:    types.PutIfVersion,
		ReturnRow:    true,
		MatchVersion: currVersion,
	}

	res, err := client.Put(req)
	if err != nil {
		fmt.Printf("Put() failed: %v\n", err)
		return
	}

	if res.Success() {
		fmt.Printf("put row(option=PutIfVersion, employee_id=%d, department_id=%d) succeeded.\n", empID, deptID)
	} else {
		fmt.Printf("put row(option=PutIfVersion, employee_id=%d, department_id=%d) failed.\n", empID, deptID)
	}
}
Output:

func (*Client) Query

func (c *Client) Query(req *QueryRequest) (*QueryResult, error)

Query is used to query a table based on the query statement specified in the QueryRequest.

Queries that include a full shard key will execute much more efficiently than more distributed queries that must go to multiple shards.

Table-style and system-style queries such as "CREATE TABLE ..." or "CREATE USER ..." are not supported by this method. Those operations must be performed using DoTableRequest or DoSystemRequest as appropriate.

When execute on the cloud service, the amount of data read by a single query request is limited by a system default and can be further limited using QueryRequest.MaxReadKB. This limits the amount of data read and not the amount of data returned, which means that a query can return zero results but still have more data to read. For this reason queries should always operate in a loop, acquiring more results, until QueryRequest.IsDone() returns true, indicating that the query is done.

Example
package main

import (
	"fmt"

	"github.com/oracle/nosql-go-sdk/nosqldb"
	"github.com/oracle/nosql-go-sdk/nosqldb/types"
)

func main() {
	cfg := nosqldb.Config{
		Mode:     "cloudsim",
		Endpoint: "http://localhost:8080",
	}

	client, err := nosqldb.NewClient(cfg)
	if err != nil {
		fmt.Printf("failed to create a NoSQL client: %v\n", err)
		return
	}
	defer client.Close()

	// Sample table:
	//
	// CREATE TABLE employees (employee_id INTEGER, first_name STRING, last_name STRING,
	// email STRING, phone_number STRING, hire_date TIMESTAMP(0), salary DOUBLE,
	// department_id INTEGER, PRIMARY KEY(shard(department_id), employee_id))
	stmt := "declare $dept_id integer; " +
		"SELECT employee_id, first_name, last_name FROM employees WHERE department_id = $dept_id"
	prepReq := &nosqldb.PrepareRequest{
		Statement: stmt,
	}

	prepRes, err := client.Prepare(prepReq)
	if err != nil {
		fmt.Printf("Prepare(%s) failed: %v\n", stmt, err)
		return
	}

	queryReq := &nosqldb.QueryRequest{
		PreparedStatement: &prepRes.PreparedStatement,
	}
	queryReq.PreparedStatement.SetVariable("$dept_id", 90)

	var results []*types.MapValue
	for {
		queryRes, err := client.Query(queryReq)
		if err != nil {
			fmt.Printf("Query(%s) failed: %v\n", stmt, err)
			return
		}

		res, err := queryRes.GetResults()
		if err != nil {
			fmt.Printf("GetResults() failed: %v\n", err)
			return
		}

		results = append(results, res...)

		if queryReq.IsDone() {
			break
		}
	}

	fmt.Printf("got %d results\n", len(results))
	for _, r := range results {
		empID, _ := r.GetInt("employee_id")
		firstName, _ := r.GetString("firstName")
		lastName, _ := r.GetString("lastName")
		fmt.Printf("%d: %s %s\n", empID, firstName, lastName)
	}
}
Output:

func (*Client) ResetRateLimiters added in v1.2.2

func (c *Client) ResetRateLimiters(tableName string)

ResetRateLimiters is for testing puposes only.

func (*Client) VerifyConnection added in v1.3.0

func (c *Client) VerifyConnection() error

VerifyConnection attempts to verify that the connection is useable. It may check auth credentials, and may negotiate the protocol level to use with the server. This is typically only used in tests.

func (*Client) WriteMultiple

func (c *Client) WriteMultiple(req *WriteMultipleRequest) (*WriteMultipleResult, error)

WriteMultiple executes a sequence of operations associated with a table that share the same shard key portion of their primary keys, all the specified operations are executed within the scope of a single transaction.

When execute on the cloud service, there are some size-based limitations on this operation:

  1. The max number of individual operations (put, delete) in a single WriteMultiple request is 50.
  2. The total request size is limited to 25MB.
Example
package main

import (
	"fmt"
	"time"

	"github.com/oracle/nosql-go-sdk/nosqldb"
	"github.com/oracle/nosql-go-sdk/nosqldb/types"
)

func main() {
	cfg := nosqldb.Config{
		Mode:     "cloudsim",
		Endpoint: "http://localhost:8080",
	}

	client, err := nosqldb.NewClient(cfg)
	if err != nil {
		fmt.Printf("failed to create a NoSQL client: %v\n", err)
		return
	}
	defer client.Close()

	// Sample table:
	//
	// CREATE TABLE employees (employee_id INTEGER, first_name STRING, last_name STRING,
	// email STRING, phone_number STRING, hire_date TIMESTAMP(0), salary DOUBLE,
	// department_id INTEGER, PRIMARY KEY(shard(department_id), employee_id))
	type emp struct {
		empID       int
		firstName   string
		lastName    string
		email       string
		phoneNumber string
		hireDate    time.Time
		salary      float64
		deptID      int
	}

	formerEmployees := []*emp{
		{empID: 101, deptID: 80},
		{empID: 107, deptID: 80},
		{empID: 109, deptID: 80},
	}

	newEmployees := []*emp{
		{
			empID:       211,
			deptID:      80,
			firstName:   "Tayler",
			lastName:    "Fox",
			email:       "TFOX@example.com",
			phoneNumber: "011.44.1343.729268",
			hireDate:    time.Date(2019, time.October, 1, 10, 0, 0, 0, time.UTC),
			salary:      17000,
		},
		{
			empID:       212,
			deptID:      80,
			firstName:   "William",
			lastName:    "Smith",
			email:       "WSMITH@example.com",
			phoneNumber: "011.44.1343.629268",
			hireDate:    time.Date(2019, time.October, 3, 10, 0, 0, 0, time.UTC),
			salary:      17000,
		},
	}

	wmReq := &nosqldb.WriteMultipleRequest{
		TableName: "employees",
		Timeout:   10 * time.Second,
	}

	for _, e := range formerEmployees {
		pk := &types.MapValue{}
		pk.Put("employee_id", e.empID).Put("department_id", e.deptID)
		delReq := &nosqldb.DeleteRequest{
			TableName: "employees",
			Key:       pk,
		}

		wmReq.AddDeleteRequest(delReq, true)
	}

	for _, e := range newEmployees {
		value := &types.MapValue{}
		value.Put("employee_id", e.empID).Put("department_id", e.deptID)
		value.Put("first_name", e.firstName).Put("last_name", e.lastName)
		value.Put("email", e.email).Put("phone_number", e.phoneNumber)
		value.Put("hire_date", e.hireDate).Put("salary", e.salary)
		putReq := &nosqldb.PutRequest{
			TableName: "employees",
			Value:     value,
			PutOption: types.PutIfAbsent,
			ReturnRow: true,
		}

		wmReq.AddPutRequest(putReq, true)
	}

	wmRes, err := client.WriteMultiple(wmReq)
	if err != nil {
		fmt.Printf("WriteMultiple() failed: %v\n", err)
		return
	}

	if wmRes.IsSuccess() {
		fmt.Printf("WriteMultiple() succeeded\n")
	} else {
		fmt.Printf("WriteMultiple() failed\n")
	}
}
Output:

type Config

type Config struct {
	// Endpoint specifies the Oracle NoSQL server endpoint that clients connect to.
	// It is required when connect to the Oracle NoSQL cloud simulator or
	// the on-premise Oracle NoSQL server.
	// It must include the target address, and may include protocol and port.
	// The syntax is:
	//
	//   [http[s]://]host[:port]
	//
	// For example, these are valid endpoints:
	//
	//   localhost:8080
	//   http://localhost:8080
	//   https://localhost:8090
	//
	// If port is omitted, the endpoint defaults to 443.
	// If protocol is omitted, the endpoint uses https if the port is 443, and
	// http in all other cases.
	Endpoint string `json:"endpoint"`

	// Region specifies the region for the Oracle NoSQL cloud service that clients connect to.
	// Region takes precedence over the "region" property that may be specified
	// in the OCI configuration file which is ~/.oci/config by default.
	//
	// This is used for cloud service only.
	Region common.Region `json:"region"`

	// Mode specifies the configuration mode for client, which is one of:
	//
	//   "cloud": for connecting to a NoSQL cloud service
	//   "cloudsim": for connecting to a local cloud simulator
	//   "onprem": for connecting to an on-premise NoSQL server
	//
	// If not set, the "cloud" mode is used by default.
	Mode string `json:"mode"`

	// Username specifies the user that used to authenticate with the server.
	// This is only used for on-premise NoSQL server that configured with security.
	Username string `json:"username,omitempty"`

	// Password specifies the password for user that used to authenticate with the server.
	// This is only used for on-premise NoSQL server that configured with security.
	Password []byte `json:"password,omitempty"`

	// Configurations for requests.
	RequestConfig `json:"requestConfig,omitempty"`

	// Configurations for HTTP client.
	httputil.HTTPConfig `json:"httpConfig,omitempty"`

	// Configurations for logging.
	LoggingConfig `json:"loggingConfig,omitempty"`

	// Authorization provider.
	// If not specified, use the default authorization provider depending on the
	// configuration mode:
	//
	//   use iam.SignatureProvider for NoSQL cloud service that uses OCI IAM.
	//   use kvstore.AccessTokenProvider for the secure NoSQL servers on-premise.
	//
	AuthorizationProvider

	// RetryHandler specifies a handler used to handle operation retries.
	RetryHandler

	// By default, internal rate limiting is disabled. Set RateLimitingEnabled to
	// true before creating a client to enable internal rate limiting.
	RateLimitingEnabled bool `json:"rateLimitingEnabled,omitempty"`

	// RateLimiterPercentage is a default percentage of table limits to use with
	// rate limiting. This may be useful for cases where a client should only use
	// a portion of full table limits. This only applies if internal rate limiting is
	// enabled.
	// The default for this value is 100.0 (full table limits).
	RateLimiterPercentage float64
	// contains filtered or unexported fields
}

Config represents a group of configuration parameters for a Client.

When creating a Client, the Config instance is copied so modifications on the instance have no effect on the existing Client which is immutable.

Most of the configuration parameters are optional and have default values if not specified.

func (*Config) IsCloud

func (c *Config) IsCloud() bool

IsCloud returns whether the configuration is used for cloud service.

func (*Config) IsCloudSim

func (c *Config) IsCloudSim() bool

IsCloudSim returns whether the configuration is used for cloud simulator.

type DefaultRetryHandler

type DefaultRetryHandler struct {
	// contains filtered or unexported fields
}

DefaultRetryHandler represents the default implementation of RetryHandler interface.

func NewDefaultRetryHandler

func NewDefaultRetryHandler(maxNumRetries uint, retryInterval time.Duration) (*DefaultRetryHandler, error)

NewDefaultRetryHandler creates a DefaultRetryHandler with the specified maximum number of retries and retry interval. The retry interval must be greater than or equal to 1 millisecond.

func (DefaultRetryHandler) Delay

func (r DefaultRetryHandler) Delay(req Request, numRetries uint, err error)

Delay causes the current goroutine to pause for a peroid of time. It is called when a retryable error is reported. It is determined that the request will be retried based on the return value of ShouldRetry().

If a non-zero retryInterval is configured for the retry handler, this method uses retryInterval. Otherwise, it uses an exponential backoff algorithm to compute the time of delay.

If the reported retryable error is SecurityInfoUnavailable, it pauses for securityErrorRetryInterval period of time when the number of retries is less than or equal to 10. Otherwise, it uses the exponential backoff algorithm to compute the time of delay.

func (DefaultRetryHandler) MaxNumRetries

func (r DefaultRetryHandler) MaxNumRetries() uint

MaxNumRetries returns the maximum number of retries that this handler will allow before the error is reported to the application.

func (DefaultRetryHandler) ShouldRetry

func (r DefaultRetryHandler) ShouldRetry(req Request, numRetries uint, err error) bool

ShouldRetry reports whether the request should continue to retry upon receiving the specified error and having attempted the specified number of retries.

The default behavior is to NOT retry OperationThrottlingError because the retry time is likely much longer than normal because they are DDL operations. In addition, NOT retry any requests that should not be retried, including TableRequest, ListTablesRequest, GetTableRequest, TableUsageRequest and GetIndexesRequest.

Always retry SecurityInfoUnavailable error until exceed the request timeout. It's not restrained by the maximum retries configured for this handler, the driver with retry handler with 0 retry setting would still retry the request upon receiving this error.

type DelayInfo added in v1.2.2

type DelayInfo struct {
	// RateLimitTime represents the time delayed due to internal rate limiting.
	RateLimitTime time.Duration
	// RetryTime represents the time delayed due to internal request retries.
	RetryTime time.Duration
}

DelayInfo contains information about the amount of time a request was delayed.

func (DelayInfo) Delayed added in v1.2.2

func (d DelayInfo) Delayed() DelayInfo

Delayed returns the time delay information for a completed request.

type DeleteRequest

type DeleteRequest struct {
	// TableName specifies the name of table from which to delete the row.
	// It is required and must be non-empty.
	TableName string `json:"tableName"`

	// Key specifies the primary key used for the delete operation.
	// It is required and must be non-nil.
	Key *types.MapValue `json:"key"`

	// ReturnRow specifies whether information about the existing row should be
	// returned on failure because of a version mismatch.
	// If a match version has not been specified via MatchVersion, this
	// parameter is ignored and there will be no return information.
	//
	// It is optional and defaults to false.
	//
	// Using this option may incur additional cost.
	ReturnRow bool `json:"returnRow"`

	// MatchVersion specifies the version to use for a conditional delete
	// operation. The version is usually obtained from GetResult.Version or
	// other method that returns a version.
	//
	// It is optional.
	// If set, the delete operation will succeed only if the row exists and its
	// version matches the one specified.
	//
	// Using this option will incur additional cost.
	MatchVersion types.Version `json:"matchVersion,omitempty"`

	// Timeout specifies the timeout value for the request.
	// It is optional.
	// If set, it must be greater than or equal to 1 millisecond, otherwise an
	// IllegalArgument error will be returned.
	// If not set, the default timeout value configured for Client is used,
	// which is determined by Client.DefaultRequestTimeout().
	Timeout time.Duration `json:"timeout"`

	// Durability is currently only used in On-Prem installations.
	// Added in SDK Version 1.3.0
	Durability types.Durability `json:"durability"`

	common.InternalRequestData
	// contains filtered or unexported fields
}

DeleteRequest represents a request for deleting a row from a table.

This request can be used to perform unconditional and conditional deletes:

1. Delete any existing row. This is the default.

2. Delete only if the row exists and its version matches a specific version.

For the latter case, a MatchVersion for the request must be specified. Using this option in conjunction with specifying the ReturnRow allows information about the existing row to be returned if the operation fails because of a version mismatch. On success no information is returned. Specifying the ReturnRow may incur additional cost and affect operation latency.

This request is used as the input to a Client.Delete() operation, which returns a DeleteResult. If the operation succeeds, DeleteResult.Success returns true. Additional information such as previous row information, may be available in DeleteResult.

type DeleteResult

type DeleteResult struct {
	Capacity
	DelayInfo

	// WriteResult is used to get the information about the existing row such as
	// ExistingValue and ExistingVersion on operation failure.
	WriteResult

	// Success represents if the delete operation succeeded or not.
	Success bool `json:"success"`
}

DeleteResult represents the result of a Client.Delete() operation.

If the delete succeeded DeleteResult.Success returns true. Information about the existing row on failure may be available using DeleteResult.ExistingValue and DeleteResult.ExistingVersion, depending on the use of DeleteRequest.ReturnRow.

func (DeleteResult) String

func (r DeleteResult) String() string

String returns a JSON string representation of the DeleteResult.

type FPArithSpec

type FPArithSpec struct {
	// Precision specifies the desired decimal precision (in number of digits)
	// for arithematic operation result of floating-point value.
	Precision uint

	// RoundingMode determines how an arithematic operation result of
	// floating-point value is rounded to the desired precision.
	RoundingMode big.RoundingMode
}

FPArithSpec specifies the desired representation in terms of decimal precision (number of digits) and rounding rules for the floating-point values as arithematic operation results.

type GetIndexesRequest

type GetIndexesRequest struct {
	// TableName specifies the name of table to which the indexes belong.
	// It is required and must be non-empty.
	TableName string `json:"tableName"`

	// IndexName specifies the name of index.
	//
	// It is optional.
	// If set, the request is intended for retrieving information of the
	// specific index.
	// If not set, the request is intended for retrieving information of
	// all indexes on the table.
	IndexName string `json:"indexName,omitempty"`

	// Timeout specifies the timeout value for the request.
	// It is optional.
	// If set, it must be greater than or equal to 1 millisecond, otherwise an
	// IllegalArgument error will be returned.
	// If not set, the default timeout value configured for Client is used,
	// which is determined by Client.DefaultRequestTimeout().
	Timeout time.Duration `json:"timeout"`

	common.InternalRequestData
}

GetIndexesRequest represents a request for retrieving indexes information.

It is used as the input to a Client.GetIndexes() operation which returns the information of a specific index or all indexes of the specified table, as returned in GetIndexesResult.

type GetIndexesResult

type GetIndexesResult struct {
	DelayInfo

	// Indexes represents a slice of IndexInfo that contains index information
	// returned by the operation.
	Indexes []IndexInfo `json:"indexes"`
	// contains filtered or unexported fields
}

GetIndexesResult represents the result of a Client.GetIndexes() operation.

On a successful operation the index information is returned in a slice of IndexInfo.

func (GetIndexesResult) ConsumedCapacity

func (r GetIndexesResult) ConsumedCapacity() (Capacity, error)

func (GetIndexesResult) String

func (r GetIndexesResult) String() string

String returns a JSON string representation of the GetIndexesResult.

type GetRequest

type GetRequest struct {

	// TableName specifies the name of table from which to get the row.
	// It is required and must be non-empty.
	TableName string `json:"tableName"`

	// Key specifies the primary key used for the get operation.
	// It is required and must be non-nil.
	Key *types.MapValue `json:"key"`

	// Timeout specifies the timeout value for the request.
	// It is optional.
	// If set, it must be greater than or equal to 1 millisecond, otherwise an
	// IllegalArgument error will be returned.
	// If not set, the default timeout value configured for Client is used,
	// which is determined by Client.DefaultRequestTimeout().
	Timeout time.Duration `json:"timeout"`

	// Consistency specifies desired consistency policy for the request.
	// It is optional.
	// If set, it must be either types.Absolute or types.Eventual, otherwise
	// an IllegalArgument error will be returned.
	// If not set, the default consistency value configured for Client is used,
	// which is determined by Client.DefaultConsistency().
	Consistency types.Consistency `json:"consistency"`

	common.InternalRequestData
}

GetRequest represents a request for retrieving a row from a table.

It is used as the input to a Client.Get() operation which returns a single row based on the specified key.

type GetResult

type GetResult struct {
	Capacity

	// Value represents the value of the returned row, or nil if the row does not exist.
	Value *types.MapValue `json:"value"`

	// Version represents the version of the row if the operation was
	// successful, or nil if the row does not exist.
	Version types.Version `json:"version"`

	// ExpirationTime represents the expiration time of the row.
	// A zero value of time.Time indicates that the row does not expire.
	// This value is valid only if the operation successfully returned a row,
	// which means the returned Value is non-nil.
	ExpirationTime time.Time `json:"expirationTime"`

	// ModificationTime represents the modification time of an existing row.
	// Its value is in milliseconds since January 1 1970.
	// Added in SDK Version 1.3.0
	ModificationTime int64 `json:"modificationTime"`

	DelayInfo
}

GetResult represents the result of a Client.Get() operation.

On a successful operation the value of the row is available in GetResult.Value and the other state available in this struct is valid.

On failure that value is nil and other state, other than consumed capacity, is undefined.

func (GetResult) RowExists

func (r GetResult) RowExists() bool

RowExists checks if the desired row exists. It returns true if the get operation successfully finds the row with specified key, returns false otherwise.

func (GetResult) String

func (r GetResult) String() string

String returns a JSON string representation of the GetResult.

func (GetResult) ValueAsJSON

func (r GetResult) ValueAsJSON() string

ValueAsJSON returns a JSON string representation of the GetResult.Value.

type GetTableRequest

type GetTableRequest struct {
	// TableName specifies the name of table.
	// It is required and must be non-empty.
	TableName string `json:"tableName"`

	// OperationID specifies the operation id to use for the request.
	// The operation id can be obtained via TableResult.OperationID.
	//
	// It is optional.
	// If set to a non-empty string, it represents an asynchronous table
	// operation that may be in progress. It is used to examine the result of
	// the operation and if the operation has failed, an error will be returned
	// in response to a Client.GetTable() operation. If the operation is in
	// progress or has completed successfully, the state of the table is
	// returned.
	OperationID string `json:"operationID,omitempty"`

	// Timeout specifies the timeout value for the request.
	// It is optional.
	// If set, it must be greater than or equal to 1 millisecond, otherwise an
	// IllegalArgument error will be returned.
	// If not set, the default timeout value configured for Client is used,
	// which is determined by Client.DefaultRequestTimeout().
	Timeout time.Duration `json:"timeout"`

	common.InternalRequestData
}

GetTableRequest represents a request for retrieving table information from server.

It is used as the input of a Client.GetTable() operation which returns static information associated with a table, as returned in TableResult. This information only changes in response to a change in table schema or a change in provisioned throughput or capacity for the table.

type IndexInfo

type IndexInfo struct {
	// IndexName represents the name of index.
	IndexName string `json:"indexName"`

	// FieldNames represents a slice of string that contains names of fields
	// constitute the index.
	FieldNames []string `json:"fieldNames"`
}

IndexInfo represents the information about a single index including its name and field names.

func (IndexInfo) String

func (r IndexInfo) String() string

String returns a JSON string representation of the IndexInfo.

type ListTablesRequest

type ListTablesRequest struct {
	// StartIndex specifies the index to use to start returning table names.
	// This is related to the ListTablesResult.LastIndexReturned from a previous
	// request and can be used to page table names.
	//
	// It is optional.
	// If not set, the list starts at index 0.
	StartIndex uint `json:"startIndex,omitempty"`

	// Limit specifies the maximum number of tables to return in the operation.
	//
	// It is optional.
	// If not set, there is no limit.
	Limit uint `json:"limit,omitempty"`

	// Namespace specifies the namespace to use for the list.
	//
	// It is optional and used for on-premise only.
	// If set, only tables in the namespace provided are returned.
	// If not set, all tables accessible to the user will be returned.
	Namespace string `json:"namespace,omitempty"`

	// Timeout specifies the timeout value for the request.
	// It is optional.
	// If set, it must be greater than or equal to 1 millisecond, otherwise an
	// IllegalArgument error will be returned.
	// If not set, the default timeout value configured for Client is used,
	// which is determined by Client.DefaultRequestTimeout().
	Timeout time.Duration `json:"timeout"`

	common.InternalRequestData
}

ListTablesRequest represents a request to list all available tables.

It is used as the input to a Client.ListTables() operation, which lists all available tables associated with the identity. If the list is large, it can be paged by using the StartIndex and Limit parameters. The list is returned in an array in ListTablesResult. Table names are returned sorted in alphabetical order in order to facilitate paging.

type ListTablesResult

type ListTablesResult struct {
	DelayInfo

	// Tables represents a slice of string that contains table names returned
	// by the operation, in alphabetical order.
	Tables []string `json:"tables"`

	// LastIndexReturnedthe represents index of the last table name returned.
	// This can be provided to ListTablesRequest.StartIndex to be used as a
	// starting point for listing tables.
	LastIndexReturned uint `json:"lastIndexReturned"`
	// contains filtered or unexported fields
}

ListTablesResult represents the result of a Client.ListTables() operation.

On a successful operation the table names are available as well as the index of the last returned table. Table names are returned in a slice of string, sorted in alphabetical order.

func (ListTablesResult) ConsumedCapacity

func (r ListTablesResult) ConsumedCapacity() (Capacity, error)

func (ListTablesResult) String

func (r ListTablesResult) String() string

String returns a JSON string representation of the ListTablesResult.

type LoggingConfig

type LoggingConfig struct {

	// Configurations for the logger.
	// If this is not set, use logger.DefaultLogger unless DisableLogging is set.
	*logger.Logger

	// DisableLogging represents whether logging is disabled.
	DisableLogging bool `json:"disableLogging,omitempty"`
}

LoggingConfig represents logging configurations.

type MultiDeleteRequest

type MultiDeleteRequest struct {
	// TableName specifies the name of table for the request.
	// It is required and must be non-empty.
	TableName string `json:"tableName"`

	// Key specifies the partial key used for the request.
	// It is required and must be non-nil.
	Key *types.MapValue `json:"key"`

	// ContinuationKey specifies the continuation key to use to continue the operation.
	ContinuationKey []byte `json:"continuationKey,omitempty"`

	// FieldRange specifies the FieldRange to be used for the operation.
	// It is optional, but required to delete a specific range of rows.
	FieldRange *types.FieldRange `json:"fieldRange,omitempty"`

	// MaxWriteKB specifies the limit on the total KB write during this operation.
	//
	// It is optional and has no effect for on-premise.
	//
	// When use for cloud service, if this value is not set, or set to 0, there
	// is no application-defined limit. This value can only reduce the system
	// defined limit. An attempt to increase the limit beyond the system defined
	// limit will cause an IllegalArgument error.
	MaxWriteKB uint `json:"maxWriteKB,omitempty"`

	// Timeout specifies the timeout value for the request.
	// It is optional.
	// If set, it must be greater than or equal to 1 millisecond, otherwise an
	// IllegalArgument error will be returned.
	// If not set, the default timeout value configured for Client is used,
	// which is determined by Client.DefaultRequestTimeout().
	Timeout time.Duration `json:"timeout"`

	// Durability is currently only used in On-Prem installations.
	// Added in SDK Version 1.3.0
	Durability types.Durability `json:"durability"`

	common.InternalRequestData
}

MultiDeleteRequest represents the input to a Client.MultiDelete operation which can be used to delete a range of values that match the primary key and range provided.

A range is specified using a partial key plus a range based on the portion of the key that is not provided. For example if a table's primary key is <id, timestamp> and the its shard key is the "id", it is possible to delete a range of timestamp values for a specific id by providing an id but no timestamp in the value used for Key and providing a range of timestamp values in the FieldRange.

Because this operation can exceed the maximum amount of data modified in a single operation, a continuation key can be used to continue the operation. The continuation key is obtained from MultiDeleteResult.ContinuationKey and set in a new request using MultiDeleteRequest.ContinuationKey. Operations with a continuation key still require the primary key.

type MultiDeleteResult

type MultiDeleteResult struct {
	Capacity
	DelayInfo

	// ContinuationKey represents the continuation key where the next
	// MultiDelete request resumes from.
	ContinuationKey []byte `json:"continuationKey"`

	// NumDeleted represents the number of rows deleted from the table.
	NumDeleted int `json:"numDeleted"`
}

MultiDeleteResult represents the result of a Client.MultiDelete() operation.

On a successful operation the number of rows deleted is available in MultiDeleteResult.NumDeleted.

There is a limit on the amount of data consumed by a single call. If there are still more rows to delete, the continuation key can be obtained using MultiDeleteResult.ContinuationKey.

func (MultiDeleteResult) String

func (r MultiDeleteResult) String() string

String returns a JSON string representation of the MultiDeleteResult.

type OperationResult

type OperationResult struct {
	// WriteResult is used to get the information about the existing row such as
	// ExistingValue and ExistingVersion on operation failure.
	WriteResult

	// Success represents whether the operation succeeded.
	// A put or delete operation may fail if the condition is not matched.
	Success bool `json:"success"`

	// Version represents the version of the new row for put operation, or nil
	// if the put operation did not succeed or the operation is a delete operation.
	Version types.Version `json:"version"`

	// GeneratedValue represents the value generated if the operation
	// created a new value for an identity column or string as uuid
	// column. If a value was generated for the column, it is non-nil,
	// otherwise it is nil.
	//
	// This value is only valid for a put operation on a table with an identity
	// column.
	GeneratedValue types.FieldValue `json:"generatedValue"`
}

OperationResult represents the result associated with the execution of an individual operation in the request.

func (OperationResult) String

func (r OperationResult) String() string

String returns a JSON string representation of the OperationResult.

type PrepareRequest

type PrepareRequest struct {
	// Statement specifies a query statement.
	// It is required and must be non-empty.
	Statement string `json:"statement"`

	// GetQueryPlan specifies whether to include the query execution plan in
	// the PrepareResult returned for this request.
	GetQueryPlan bool `json:"getQueryPlan"`

	// Timeout specifies the timeout value for the request.
	// It is optional.
	// If set, it must be greater than or equal to 1 millisecond, otherwise an
	// IllegalArgument error will be returned.
	// If not set, the default timeout value configured for Client is used,
	// which is determined by Client.DefaultRequestTimeout().
	Timeout time.Duration `json:"timeout"`

	common.InternalRequestData
}

PrepareRequest encapsulates a query prepare call. Query preparation allows queries to be compiled (prepared) and reused, saving time and resources. Use of prepared queries vs. direct execution of query strings is highly recommended.

Prepared queries are implemented as PreparedStatement which supports bind variables in queries which can be used to more easily reuse a query by parameterization.

type PrepareResult

type PrepareResult struct {
	Capacity
	DelayInfo

	// PreparedStatement represents the value of the prepared statement.
	PreparedStatement PreparedStatement `json:"preparedStatement"`
}

PrepareResult represents the result of a Client.Prepare() operation.

The returned PreparedStatement can be re-used for query execution using QueryRequest.PreparedStatement.

func (PrepareResult) String

func (r PrepareResult) String() string

String returns a JSON string representation of the PrepareResult.

type PreparedStatement

type PreparedStatement struct {
	// contains filtered or unexported fields
}

PreparedStatement encapsulates a prepared query statement. It includes state that can be sent to a server and executed without re-parsing the query. It includes bind variables which may be set for each successive use of the query. The prepared query itself is read-only but this object contains a mutable map of bind variables and is not goroutine-safe if variables are used.

A single instance of PreparedStatement is goroutine-safe if bind variables are not used. If bind variables are to be used and the statement shared among goroutines additional instances of PreparedStatement should be created.

func (*PreparedStatement) SetVariable

func (p *PreparedStatement) SetVariable(name string, value interface{}) error

SetVariable sets value for the specified variable used for the query. Existing variables with the same name are silently overwritten. The name and type of the value are validated when the query is executed.

type PutRequest

type PutRequest struct {
	// TableName specifies the name of table which the row to put into.
	// It is required and must be non-empty.
	TableName string `json:"tableName"`

	// Value specifies the value of the row to put.
	// It is required and must be non-nil.
	Value *types.MapValue `json:"value"`

	// PutOption specifies the put option for the operation.
	//
	// It is optional and performs an unconditional put by default.
	// If set, it must be types.PutIfAbsent, types.PutIfPresent or types.PutIfVersion.
	PutOption types.PutOption `json:"putOption"`

	// ReturnRow specifies whether information about the existing row should be
	// returned on failure because of a version mismatch or failure of a
	// PutIfAbsent operation.
	ReturnRow bool `json:"returnRow"`

	// TTL specifies the time to live (TTL) value, causing the time to live on
	// the row to be set to the specified value on put.
	// It is optional.
	TTL *types.TimeToLive `json:"ttl"`

	// UseTableTTL specifies whether to use the table's default TTL for the row.
	// If true, and there is an existing row, causes the operation to update
	// the time to live (TTL) value of the row based on the table's default
	// TTL if set. If the table has no default TTL this setting has no effect.
	// By default updating an existing row has no effect on its TTL.
	UseTableTTL bool `json:"useTableTTL"`

	// MatchVersion specifies the desired version to use for a conditional put
	// operation that uses the PutIfVersion option.
	// The Version is usually obtained from GetResult.Version or other method
	// that returns a Version. When set, the put operation will succeed only if
	// the row exists and its Version matches the one specified.
	// This condition exists to allow an application to ensure that it is
	// updating a row in an atomic read-modify-write cycle.
	//
	// Using this mechanism incurs additional cost.
	MatchVersion types.Version `json:"matchVersion,omitempty"`

	// ExactMatch specifies whether the provided Value must be an exact match
	// for the table schema. An exact match means that there are no required
	// fields missing and that there are no extra, unknown fields.
	// If set to true, and the provided Value does not match the table schema
	// exactly, the operation will fail.
	// The default behavior is to not require an exact match.
	ExactMatch bool `json:"exactMatch"`

	// IdentityCacheSize specifies the number of generated identity values that
	// are requested from the server during a put.
	// This takes precedence over the DDL identity CACHE option that was set
	// during creation of the identity column.
	// If this is set to a value that is less than or equal to 0, the DDL identity
	// CACHE value is used.
	IdentityCacheSize int `json:"identityCacheSize"`

	// Timeout specifies the timeout value for the request.
	// It is optional.
	// If set, it must be greater than or equal to 1 millisecond, otherwise an
	// IllegalArgument error will be returned.
	// If not set, the default timeout value configured for Client is used,
	// which is determined by Client.DefaultRequestTimeout().
	Timeout time.Duration `json:"timeout"`

	// Durability is currently only used in On-Prem installations.
	// Added in SDK Version 1.3.0
	Durability types.Durability `json:"durability"`

	common.InternalRequestData
	// contains filtered or unexported fields
}

PutRequest represents a request used to put a row into a table.

This request can be used to perform unconditional and conditional puts:

1. Overwrite any existing row. This is the default.

2. Succeed only if the row does not exist. Specify types.PutIfAbsent for the PutOption parameter for this case.

3. Succeed only if the row exists. Specify types.PutIfPresent for the PutOption parameter for this case.

4. Succeed only if the row exists and its version matches a specific version. Specify types.PutIfVersion for the PutOption parameter and a desired version for the MatchVersion parameter for this case.

Information about the existing row can be returned on failure of a put operation using types.PutIfAbsent or types.PutIfVersion by using the ReturnRow option. Use of the ReturnRow option incurs additional cost and may affect operation latency.

This request is used as the input to a Client.Put() operation, which returns a PutResult. On a successful operation the returned PutResult.Version is non-nil. Additional information, such as previous row information, may be available in PutResult.

type PutResult

type PutResult struct {
	Capacity
	DelayInfo

	// WriteResult is used to get the information about the existing row such as
	// ExistingValue and ExistingVersion on operation failure.
	WriteResult

	// Version represents the version of the new row if the operation was
	// successful. If the operation failed nil is returned.
	Version types.Version `json:"version"`

	// GeneratedValue represents the value generated if the operation
	// created a new value for an identity column or string as uuid
	// column. If a value was generated for the column, it is non-nil,
	// otherwise it is nil.
	GeneratedValue types.FieldValue `json:"generatedValue"`
}

PutResult represents the result of a Client.Put() operation.

On a successful operation the value returned by PutResult.Version is non-nil.

On failure that value is nil. Information about the existing row on failure may be available using PutResult.ExistingValue and PutResult.ExistingVersion, depending on the use of PutRequest.ReturnRow and whether the put had set the PutIfAbsent or PutIfVersion option.

func (PutResult) String

func (r PutResult) String() string

String returns a JSON string representation of the PutResult.

func (PutResult) Success

func (r PutResult) Success() bool

Success returns whether the put operation succeeded.

type QueryRequest

type QueryRequest struct {
	// Statement specifies a query statement.
	Statement string `json:"statement,omitempty"`

	// PreparedStatement specifies the prepared query statement.
	PreparedStatement *PreparedStatement `json:"preparedStatement,omitempty"`

	// Limit specifies the limit on number of items returned by the operation.
	// This allows an operation to return less than the default amount of data.
	Limit uint `json:"limit,omitempty"`

	// MaxReadKB specifies the limit on the total data read during this operation, in KB.
	//
	// For cloud service, this value can only reduce the system defined limit.
	// An attempt to increase the limit beyond the system defined limit will
	// cause an IllegalArgument error. This limit is independent of read units
	// consumed by the operation.
	//
	// It is recommended that for tables with relatively low provisioned read
	// throughput that this limit be reduced to less than or equal to one half
	// of the provisioned throughput in order to avoid or reduce throttling
	// errors.
	MaxReadKB uint `json:"maxReadKB,omitempty"`

	// MaxWriteKB specifies the limit on the total data written during this operation, in KB.
	//
	// This limit is independent of write units consumed by the operation.
	MaxWriteKB int `json:"maxWriteKB"`

	// MaxMemoryConsumption specifies the maximum number of memory in bytes that
	// may be consumed by the query at the client for operations such as
	// duplicate elimination (which may be required due to the use of an index
	// on an array or map) and sorting. Such operations may consume a lot of
	// memory as they need to cache the full result set or a large subset of
	// it at the client memory.
	//
	// The default value is 1GB.
	MaxMemoryConsumption int64 `json:"maxMemoryConsumption"`

	// FPArithSpec specifies the desired representation in terms of decimal
	// precision (number of digits) and rounding rules for the floating-point
	// values as arithematic operation results.
	//
	// The default is Decimal32, that is in IEEE 745R Decimal32 format.
	FPArithSpec *FPArithSpec

	// Consistency specifies desired consistency policy for the request.
	// It is optional.
	// If set, it must be either types.Absolute or types.Eventual, otherwise
	// an IllegalArgument error will be returned.
	// If not set, the default consistency value configured for Client is used,
	// which is determined by Client.DefaultConsistency().
	Consistency types.Consistency `json:"consistency,omitempty"`

	// Timeout specifies the timeout value for the request.
	// It is optional.
	// If set, it must be greater than or equal to 1 millisecond, otherwise an
	// IllegalArgument error will be returned.
	// If not set, the default timeout value configured for Client is used,
	// which is determined by Client.DefaultRequestTimeout().
	Timeout time.Duration `json:"timeout"`

	// TableName is only used in the cloud service.
	// TableName should be set to the table specified in the query.
	// If this is not set, cloud rate limiting may not work properly for the
	// query request.
	TableName string

	common.InternalRequestData
	// contains filtered or unexported fields
}

QueryRequest encapsulates a query. A query may be either a string query statement or a prepared query, which may include bind variables. A query request cannot have both a string statement and prepared query, but it must have one or the other.

For performance reasons prepared queries are preferred for queries that may be reused. Prepared queries bypass compilation of the query. They also allow for parameterized queries using bind variables.

func (*QueryRequest) Close

func (r *QueryRequest) Close()

Close terminates the query execution and releases any memory consumed by the query at the client. An application should use this method if it wishes to terminate query execution before retrieving all of the query results.

func (*QueryRequest) GetMaxMemoryConsumption

func (r *QueryRequest) GetMaxMemoryConsumption() int64

GetMaxMemoryConsumption returns the maximum number of memory bytes that may be consumed by the query at the client for operations such as duplicate elimination and sorting.

func (*QueryRequest) IsDone

func (r *QueryRequest) IsDone() bool

IsDone reports whether the query execution is done. It returns true if there are no more query results to be generated, otherwise false.

type QueryResult

type QueryResult struct {
	Capacity
	DelayInfo
	// contains filtered or unexported fields
}

QueryResult represents the result of a Client.Query() operation.

It comprises a list of MapValue instances representing the query results. The shape of the values is based on the schema implied by the query. For example a query such as "SELECT * FROM ..." that returns an intact row will return values that conform to the schema of the table. Projections return instances that conform to the schema implied by the statement. UPDATE queries either return values based on a RETURNING clause or, by default, the number of rows affected by the statement.

It is possible for a query to return no results in an empty list. This happens if the query reads the maximum amount of data allowed in a single request without matching a query predicate.

Applications need to check QueryRequest.IsDone() and continue to get more results if the query request is not completed.

func (*QueryResult) ConsumedCapacity

func (r *QueryResult) ConsumedCapacity() (Capacity, error)

ConsumedCapacity returns the consumed capacity by the query request.

This implements the Result interface.

func (*QueryResult) GetResults

func (r *QueryResult) GetResults() (res []*types.MapValue, err error)

GetResults returns query results as a slice of *types.MapValue.

It is possible to return an empty result even though the query is not finished.

func (QueryResult) String

func (r QueryResult) String() string

String returns a JSON string representation of the QueryResult.

type Request

type Request interface {
	common.InternalRequestDataInt
	// contains filtered or unexported methods
}

Request is an interface that defines common functions for operation requests.

type RequestConfig

type RequestConfig struct {
	// RequestTimeout specifies a timeout value for requests.
	// This applies to any requests other than TableRequest.
	// If set, it must be greater than or equal to 1 millisecond.
	RequestTimeout time.Duration `json:"requestTimeout,omitempty"`

	// TableRequestTimeout specifies a timeout value for TableRequest.
	// If set, it must be greater than or equal to 1 millisecond.
	TableRequestTimeout time.Duration `json:"tableRequestTimeout,omitempty"`

	// SecurityInfoTimeout specifies a timeout value for retrieving security
	// information such as access tokens from authorization service.
	// This specifies a period of time waiting for security information to be available.
	// If set, it must be greater than or equal to 1 millisecond.
	SecurityInfoTimeout time.Duration `json:"securityInfoTimeout,omitempty"`

	// Consistency specifies a Consistency value for read requests, which
	// include GetRequest and QueryRequest.
	// If set, it must be either types.Eventual or types.Absolute.
	Consistency types.Consistency `json:"consistency,omitempty"`
}

RequestConfig represents a group of configuration parameters for requests.

func (*RequestConfig) DefaultConsistency

func (r *RequestConfig) DefaultConsistency() types.Consistency

DefaultConsistency returns the default Consistency value. If there is a configured Consistency it is returned. Otherwise a default value (defaultConsistency) of types.Eventual is used.

func (*RequestConfig) DefaultRequestTimeout

func (r *RequestConfig) DefaultRequestTimeout() time.Duration

DefaultRequestTimeout returns the default timeout value for requests. If there is no configured timeout or it is configured as 0, a default value (defaultRequestTimeout) of 5 seconds is used.

func (*RequestConfig) DefaultSecurityInfoTimeout

func (r *RequestConfig) DefaultSecurityInfoTimeout() time.Duration

DefaultSecurityInfoTimeout returns the default timeout value while waiting for security information to be available. If there is no configured timeout or it is configured as 0, a default value (defaultSecurityInfoTimeout) of 10 seconds is used.

func (*RequestConfig) DefaultTableRequestTimeout

func (r *RequestConfig) DefaultTableRequestTimeout() time.Duration

DefaultTableRequestTimeout returns the default timeout value for table requests. If there is no configured timeout or it is configured as 0, a default value (defaultTableRequestTimeout) of 10 seconds is used.

type Result

type Result interface {
	// ConsumedCapacity is a function used to return the read, write throughput
	// consumed by an operation.
	ConsumedCapacity() (Capacity, error)

	Delayed() DelayInfo
}

Result is an interface that represents the operation result for a request.

All operation results should satisfy this interface.

type RetryHandler

type RetryHandler interface {
	// MaxNumRetries returns the maximum number of retries that this handler
	// instance will allow before the error is reported to the application.
	MaxNumRetries() uint

	// ShouldRetry indicates whether the request should continue to retry upon
	// receiving the specified error and having attempted the specified number
	// of retries.
	//
	// This method is used by the request handling system when a retryable error
	// is returned, to determine whether to perform a retry or not based on the
	// specified parameters.
	ShouldRetry(req Request, numRetries uint, err error) bool

	// Delay is called when a retryable error is reported. It is determined
	// that the request will be retried based on the return value of
	// ShouldRetry(). It provides a delay between retries. Most implementations
	// will sleep for some period of time. The method should not return until
	// the desired delay period has passed.
	//
	// Implementations should not busy-wait in a tight loop.
	Delay(req Request, numRetries uint, err error)
}

RetryHandler interface is used by the request handling system when a retryable error is returned. It controls the number of retries as well as frequency of retries using a delaying algorithm.

A default RetryHandler is always configured on a Client instance and can be controlled or overridden using Config.RetryHandler.

It is not recommended that applications rely on a RetryHandler for regulating provisioned throughput. It is best to add rate-limiting to the application based on a table's capacity and access patterns to avoid throttling errors.

Implementations of this interface must be immutable so they can be shared.

type SystemRequest

type SystemRequest struct {
	// Statement specifies the statement used for the operation.
	// It is required.
	Statement string `json:"statement"`

	// Timeout specifies the timeout value for the request.
	// It is optional.
	// If set, it must be greater than or equal to 1 millisecond, otherwise an
	// IllegalArgument error will be returned.
	// If not set, the default timeout value configured for Client is used,
	// which is determined by Client.DefaultTableRequestTimeout().
	Timeout time.Duration `json:"timeout"`

	common.InternalRequestData
}

SystemRequest represents a request used to perform any table-independent administrative operations such as create/drop of namespaces and security-relevant operations such as create/drop users and roles.

Execution of operations specified by this request is implicitly asynchronous. These are potentially long-running operations and completion of the operation needs to be checked.

SystemRequest is used as the input of a Client.DoSystemRequest() operation, which returns a SystemResult that can be used to poll until the operation succeeds or fails by calling the SystemResult.WaitForCompletion() method.

This request is used for on-premise only.

type SystemResult

type SystemResult struct {
	DelayInfo

	// State represents the current state of the operation.
	State types.OperationState `json:"state"`

	// OperationID represents the id for the operation if it was asynchronous.
	// This is an empty string if the request did not generate a new operation.
	// The value can be used in SystemStatusRequest.OperationID to find
	// potential errors resulting from the operation.
	//
	// This is only useful for the result of asynchronous operations.
	OperationID string `json:"operationID"`

	// Statement represents the statement used for the operation.
	Statement string `json:"statement"`

	// ResultString represents the result string for the operation.
	// This may be empty if the operation did not return a result, or may be
	// a JSON string that contains the result for the operation.
	ResultString string `json:"resultString"`
	// contains filtered or unexported fields
}

SystemResult represents a result returned from Client.GetSystemStatus() and Client.DoSystemRequest() operations. It encapsulates the state of the operation requested.

Some operations performed by DoSystemRequest() are asynchronous. When such an operation has been performed it is necessary to call GetSystemStatus() until the status of the operation is known. The method SystemResult.WaitForCompletion() exists to perform this task and should be used whenever possible.

Asynchronous operations (e.g. create namespace) can be distinguished from synchronous System operations in this way:

a. Asynchronous operations may return a non-nil OperationID.
b. Asynchronous operations modify state, while synchronous operations are read-only.
c. Synchronous operations return a state of types.Complete and have a non-nil ResultString.

Client.GetSystemStatus() is synchronous, returning the known state of the operation. It should only be called if the operation was asynchronous and returned a non-null OperationID.

SystemResult is used for on-premise only.

func (SystemResult) ConsumedCapacity

func (r SystemResult) ConsumedCapacity() (Capacity, error)

func (SystemResult) String

func (r SystemResult) String() string

String returns a JSON string representation of the SystemResult.

func (*SystemResult) WaitForCompletion

func (r *SystemResult) WaitForCompletion(client *Client, timeout, pollInterval time.Duration) (*SystemResult, error)

WaitForCompletion waits for the operation to be complete.

This is a blocking, polling style wait that pauses the current goroutine for the specified duration between each polling operation.

This SystemResult is modified with any changes in state.

type SystemStatusRequest

type SystemStatusRequest struct {
	// Statement specifies the statement used for the operation.
	// It is optional.
	Statement string `json:"statement"`

	// OperationID specifies the operation id to use for the request. The
	// operation id can be obtained via SystemResult.OperationID.
	//
	// It is required and represents an asynchronous operation that may be in
	// progress. It is used to examine the result of the operation and if the
	// operation has failed an error will be returned in response to a
	// Client.GetSystemStatus() operation. If the operation is in progress or
	// has completed successfully, the state of the operation is returned.
	OperationID string `json:"operationID,omitempty"`

	// Timeout specifies the timeout value for the request.
	// It is optional.
	// If set, it must be greater than or equal to 1 millisecond, otherwise an
	// IllegalArgument error will be returned.
	// If not set, the default timeout value configured for Client is used,
	// which is determined by Client.DefaultTableRequestTimeout().
	Timeout time.Duration `json:"timeout"`

	common.InternalRequestData
}

SystemStatusRequest represents a request used to check the status of an operation started using a SystemRequest.

It is used as the input to a Client.GetSystemStatus() operation which returns current status of the SystemRequest operation.

This request is used for on-premise only.

type TableLimits

type TableLimits struct {
	// ReadUnits specifies the desired throughput of read operation in terms of
	// read units.
	ReadUnits uint `json:"readUnits"`

	// WriteUnits specifies the desired throughput of write operation in terms
	// of write units.
	WriteUnits uint `json:"writeUnits"`

	// StorageGB specifies the maximum amount of storage to be consumed by the
	// table, in gigabytes.
	StorageGB uint `json:"storageGB"`

	// CapacityMode specifies if the table is provisioned (the default) or
	// on demand.
	CapacityMode types.CapacityMode `json:"limitsMode"`
}

TableLimits is used during table creation to specify the throughput and capacity to be consumed by the table. It is also used in an operation to change the limits of an existing table. Client.DoTableRequest() method and TableRequest are used to perform these operations. The specified throughput and capacity values are enforced by the system and used for billing purposes.

Throughput limits are defined in terms of read units and write units.

A read unit represents 1 eventually consistent read per second for data up to 1 KB in size. A read that is absolutely consistent is double that, consuming 2 read units for a read of up to 1 KB in size. This means that if an application is to use types.Absolute consistency, it may need to specify additional read units when creating a table.

A write unit represents 1 write per second of data up to 1 KB in size.

In addition to throughput table capacity must be specified to indicate the maximum amount of storage, in gigabytes, allowed for the table.

All 3 values must be used whenever using this struct. There are no defaults and no mechanism to indicate "no change".

TableLimits is used for cloud service only.

func OnDemandTableLimits added in v1.3.0

func OnDemandTableLimits(GB uint) *TableLimits

OnDemandTableLimits returns a TableLimits struct set up for on demand (flexible read/write limits) tables. Added in SDK Version 1.3.0

func ProvisionedTableLimits added in v1.3.0

func ProvisionedTableLimits(RUs uint, WUs uint, GB uint) *TableLimits

ProvisionedTableLimits returns a TableLimits struct set up for provisioned (fixed maximum read/write limits) tables. This is the default.

type TableRequest

type TableRequest struct {
	// Statement specifies the statement for table relevant operations.
	// It is required for operations that manage table schema.
	Statement string `json:"statement"`

	// TableName specifies the name of an existing table.
	//
	// It is required for operations that change table limits of an existing table.
	// It should not be specified for other operations.
	TableName string `json:"tableName,omitempty"`

	// TableLimits specifies desired read/write throughput, storage limits, and
	// mode (provisioned or on demand) for the table.
	//
	// It is required for operations that create tables or change table limits.
	// It should not be specified for other operations.
	//
	// TableLimits is used for cloud service only.
	// It will be ignored if used for on-premise.
	TableLimits *TableLimits `json:"tableLimits,omitempty"`

	// Timeout specifies the timeout value for the request.
	// It is optional.
	// If set, it must be greater than or equal to 1 millisecond, otherwise an
	// IllegalArgument error will be returned.
	// If not set, the default timeout value configured for Client is used,
	// which is determined by Client.DefaultTableRequestTimeout().
	Timeout time.Duration `json:"timeout"`

	common.InternalRequestData
}

TableRequest represents a request used to manage table schema and limits.

The following operations are supported by TableRequest:

create tables
drop tables
modify tables: add or remove columns
create indexes
drop indexes
change table limits of an existing table

Operation that is used to create a table must specify a Statement to define the table schema and a TableLimits to define the throughput, storage, and mode (provisioned or on demand) desired for the table.

Operations that are used to drop, modify a table, or create, drop an index must specify a Statement.

These operations that are used to manage table schema do not need to specify the TableName explicitly as the table name is inferred from the specified Statement. An IllegalArgument error will be returnerd if both the Statement and TableName are specified in a TableRequest.

Operation that is used to change limits of an existing table must specify the TableName and a TableLimits to define the throughput and storage desired for the table.

Execution of operations specified by TableRequest is implicitly asynchronous. These are potentially long-running operations. This request is used as the input of a Client.DoTableRequest() operation, which returns a TableResult that can be used to poll until the table reaches the desired state.

type TableResult

type TableResult struct {
	DelayInfo

	// TableName represents the name of target table.
	TableName string `json:"tableName"`

	// State represents current state of the table.
	// A table in Active state or Updating state is usable for normal operation.
	// It is not permitted to perform table modification operations while the
	// table is in Updating state.
	State types.TableState `json:"state"`

	// Limits represents read/write throughput and storage limits for the table.
	Limits TableLimits `json:"limits"`

	// Schema represents table schema and any other metadata available for the table.
	// The returned schema may subject to change in future releases.
	Schema string `json:"schema"`

	// OperationID represents the operation id for an asynchronous operation.
	// This is empty if the request did not generate a new operation. The value
	// can be used in GetTableRequest.OperationId to find potential errors
	// resulting from the operation.
	OperationID string `json:"operationID"`
	// contains filtered or unexported fields
}

TableResult is returned from Client.GetTable() and Client.DoTableRequest() operations. It encapsulates the state of the table specified in the request.

Operations available in Client.DoTableRequest() such as table creation, modification and drop are asynchronous operations. When such an operation has been performend, it is necessary to call Client.GetTable() until the status of the table is Active or there is an error condition. TableResult provides a convenience method WaitForCompletion() to perform such tasks and should be used whenever possible.

Client.GetTable() is synchronous, it returns static information about the table as well as its current state.

func (TableResult) ConsumedCapacity

func (r TableResult) ConsumedCapacity() (Capacity, error)

func (TableResult) String

func (r TableResult) String() string

String returns a JSON string representation of the TableResult.

func (*TableResult) WaitForCompletion

func (r *TableResult) WaitForCompletion(client *Client, timeout, pollInterval time.Duration) (*TableResult, error)

WaitForCompletion waits for a table operation to complete.

Table operations are asynchronous. The method blocks checking for the table state until the specified timeout elapses or the table reaches a terminal state, which is either Active or Dropped. It is a polling style wait that pauses the current goroutine for a specified duration between each polling attempts.

This instance must be the return value of a previous Client.DoTtableRequest() and contain a non-nil operation id representing the in-progress operation unless the operation has already completed.

The timeout parameter specifies the total amount of time to wait. It must be greater than the specified pollInterval.

The pollInterval parameter specifies the amount of time to wait between polling attempts. It must be greater than or equal to 1 millisecond. If it is set to zero, the default of 500 milliseconds will be used.

If the table has reached the terminal state before specified timeout elapses, the method returns a TableResult that contains the current table state, and a nil error. Otherwise, it returns a nil TableResult and the error ocurred.

This instance is modified with any change in table state or metadata.

type TableUsage

type TableUsage struct {
	// StartTime represents the start time for this usage record.
	StartTime time.Time `json:"startTime"`

	// EndTime represents the end time for this usage record.
	EndTime time.Time `json:"endTime"`

	// ReadUnits represents the number of read uits consumed during this period.
	ReadUnits int `json:"readUnits"`

	// WriteUnits represents the number of write uits consumed during this period.
	WriteUnits int `json:"writeUnits"`

	// StorageGB represents the amount of storage consumed by the table.
	// This information may be out of date as it is not maintained in real time.
	StorageGB int `json:"storageGB"`

	// ReadThrottleCount represents the number of read throttling exceptions on
	// this table in the time period.
	ReadThrottleCount int `json:"readThrottleCount"`

	// WriteThrottleCount represents the number of write throttling exceptions
	// on this table in the time period.
	WriteThrottleCount int `json:"writeThrottleCount"`

	// StorageThrottleCount represents the number of storage throttling
	// exceptions on this table in the time period.
	StorageThrottleCount int `json:"storageThrottleCount"`
}

TableUsage represents a single usage record, or slice, that includes information about read and write throughput consumed during that period as well as the current information regarding storage capacity. In addition the count of throttling exceptions for the period is reported.

func (TableUsage) String

func (r TableUsage) String() string

String returns a JSON string representation of the TableUsage.

type TableUsageRequest

type TableUsageRequest struct {
	// TableName specifies the name of table for the request.
	// It is required and must be non-empty.
	TableName string `json:"tableName"`

	// StartTime specifies the start time to use for the request.
	// It is optional.
	// If no time range is set for this request the most recent complete usage
	// record is returned.
	StartTime time.Time `json:"startTime,omitempty"`

	// EndTime specifies the end time to use for the request.
	// It is optional.
	// If no time range is set for this request the most recent complete usage
	// record is returned.
	EndTime time.Time `json:"endTime,omitempty"`

	// Limit specifies the limit on the number of usage records desired.
	// It is optional.
	// If not set, or set to 0 there is no limit, but not all usage records may
	// be returned in a single request due to size limitations.
	Limit uint `json:"limit,omitempty"`

	// Timeout specifies the timeout value for the request.
	// It is optional.
	// If set, it must be greater than or equal to 1 millisecond, otherwise an
	// IllegalArgument error will be returned.
	// If not set, the default timeout value configured for Client is used,
	// which is determined by Client.DefaultRequestTimeout().
	Timeout time.Duration `json:"timeout"`

	common.InternalRequestData
}

TableUsageRequest represents the input of a Client.GetTableUsage() operation which returns dynamic information associated with a table, as returned in TableUsageResult. This information includes a time series of usage snapshots, each indicating data such as read and write throughput, throttling events, etc, as found in TableUsageResult.UsageRecords.

It is possible to return a range of usage records or, by default, only the most recent usage record. Usage records are created on a regular basis and maintained for a period of time. Only records for time periods that have completed are returned so that a user never sees changing data for a specific range.

This request is used for cloud service only.

type TableUsageResult

type TableUsageResult struct {
	DelayInfo

	// TableName represents table name used by the operation.
	TableName string `json:"tableName"`

	// UsageRecords represent a slice of usage records based on the parameters
	// of the TableUsageRequest used.
	UsageRecords []TableUsage `json:"usageRecords"`
	// contains filtered or unexported fields
}

TableUsageResult represents the result of a Client.GetTableUsage() operation.

It encapsulates the dynamic state of the requested table.

This is used for cloud service only.

func (TableUsageResult) ConsumedCapacity

func (r TableUsageResult) ConsumedCapacity() (Capacity, error)

func (TableUsageResult) String

func (r TableUsageResult) String() string

String returns a JSON string representation of the TableUsageResult.

type UserInfo

type UserInfo struct {
	// ID represents user id.
	ID string

	// Name represents user name.
	Name string
}

UserInfo encapsulates the information associated with a user including the id and user name in the system.

This is used for on-premise only.

type WriteMultipleRequest

type WriteMultipleRequest struct {
	// TableName specifies the name of table for the request.
	// It is required and must be non-empty.
	TableName string `json:"tableName"`

	// Operations specifies a list of operations for the request.
	// Usually it should not be set explicitly, instead, use the AddPutRequest()
	// or AddDeleteRequest() methods to add the operations.
	Operations []*WriteOperation `json:"operations"`

	// Timeout specifies the timeout value for the request.
	// It is optional.
	// If set, it must be greater than or equal to 1 millisecond, otherwise an
	// IllegalArgument error will be returned.
	// If not set, the default timeout value configured for Client is used,
	// which is determined by Client.DefaultRequestTimeout().
	Timeout time.Duration `json:"timeout"`

	// Durability is currently only used in On-Prem installations.
	// Added in SDK Version 1.3.0
	Durability types.Durability `json:"durability"`

	common.InternalRequestData
	// contains filtered or unexported fields
}

WriteMultipleRequest represents the input to a Client.WriteMultiple() operation.

This request can be used to perform a sequence of PutRequest or DeleteRequest operations associated with a table that share the same shard key portion of their primary keys, the WriteMultiple operation as whole is atomic. It is an efficient way to atomically modify multiple related rows.

On a successful operation WriteMultipleResult.Success returns true. The execution result of each operations can be retrieved using WriteMultipleResult.ResultSet.

If the WriteMultiple operation is aborted because of the failure of an operation with AbortOnFail set to true, then WriteMultipleResult.Success returns false, the index of failed operation can be accessed using WriteMultipleResult.FailedOperationIndex.

func (*WriteMultipleRequest) AddDeleteRequest

func (r *WriteMultipleRequest) AddDeleteRequest(d *DeleteRequest, abortOnFail bool) error

AddDeleteRequest adds a Delete request as a sub request of the WriteMultiple request. If abortOnFail is set to true, the WriteMultiple request will fail if any of the sub requests fail.

func (*WriteMultipleRequest) AddPutRequest

func (r *WriteMultipleRequest) AddPutRequest(p *PutRequest, abortOnFail bool) error

AddPutRequest adds a Put request as a sub request of the WriteMultiple request. If abortOnFail is set to true, the WriteMultiple request will fail if any of the sub requests fail.

func (*WriteMultipleRequest) Clear

func (r *WriteMultipleRequest) Clear()

Clear removes all of the operations from the WriteMultiple request.

type WriteMultipleResult

type WriteMultipleResult struct {
	Capacity
	DelayInfo

	// ResultSet represents the list of execution results for the operations.
	ResultSet []OperationResult `json:"resultSet"`

	// FailedOperationIndex represents the index of failed operation that
	// results in the entire WriteMultiple operation aborting.
	FailedOperationIndex int `json:"failedOperationIndex"`
}

WriteMultipleResult represents the result of a Client.WriteMultiple() operation.

If the WriteMultiple succeeds, the execution result of each sub operation can be retrieved using WriteMultipleResult.ResultSet.

If the WriteMultiple operation is aborted because of the failure of an operation with abortOnFail set to true, then the index of failed operation can be accessed using WriteMultipleResult.FailedOperationIndex, and the execution result of failed operation can be accessed using WriteMultipleResult.GetFailedOperationResult().

func (WriteMultipleResult) GetFailedOperationResult

func (r WriteMultipleResult) GetFailedOperationResult() *OperationResult

GetFailedOperationResult returns the result of the operation that results in the entire WriteMultiple operation aborting.

func (WriteMultipleResult) IsSuccess

func (r WriteMultipleResult) IsSuccess() bool

IsSuccess checks whether the operation succeeded or not. It returns true if the WriteMultiple operation succeeded, or false if the operation is aborted due to the failure of a sub operation.

func (WriteMultipleResult) String

func (r WriteMultipleResult) String() string

String returns a JSON string representation of the WriteMultipleResult.

type WriteOperation

type WriteOperation struct {
	// AbortOnFail specifies whether to abort all operations that included in
	// the same WriteMultipleRequest when this operation fails.
	AbortOnFail bool `json:"abortOnFail"`

	// DeleteRequest specifies a delete operation.
	DeleteRequest *DeleteRequest `json:"deleteRequest,omitempty"`

	// PutRequest specifies a put operation.
	PutRequest *PutRequest `json:"putRequest,omitempty"`
}

WriteOperation represents a put or delete operation that can be added into a WriteMultipleRequest. Either specify a PutRequest or DeleteRequest for the WriteOperation. Specifying both PutRequest and DeleteRequest in a single WriteOperation would cause an IllegalArgument error.

type WriteResult

type WriteResult struct {
	// ExistingVersion represents the Version of an existing row.
	ExistingVersion types.Version `json:"existingVersion"`

	// ExistingValue represents the Value of an existing row.
	ExistingValue *types.MapValue `json:"existingValue"`

	// ExistingModificationTime represents the modification time of an existing row.
	// Its value is in milliseconds since January 1 1970.
	// Added in SDK Version 1.3.0
	ExistingModificationTime int64 `json:"existingModificationTime"`
}

WriteResult represents the result of single row for write operations such as put and delete.

func (WriteResult) ExistingValueAsJSON

func (r WriteResult) ExistingValueAsJSON() string

ExistingValueAsJSON returns a JSON string representation of the ExistingValue.

func (WriteResult) String

func (r WriteResult) String() string

String returns a JSON string representation of the WriteResult.

Directories

Path Synopsis
Package auth provides functionality and types used for authorization providers.
Package auth provides functionality and types used for authorization providers.
cloudsim
Package cloudsim provides authorization provider implementations for clients that connect to cloud simulator.
Package cloudsim provides authorization provider implementations for clients that connect to cloud simulator.
iam
Package iam provides authorization provider implementations for clients that connect to cloud via IAM (Oracle Identity and Access Management).
Package iam provides authorization provider implementations for clients that connect to cloud via IAM (Oracle Identity and Access Management).
kvstore
Package kvstore provides authorization provider implementations for clients that connect to on-premise NoSQL servers.
Package kvstore provides authorization provider implementations for clients that connect to on-premise NoSQL servers.
Package common provides common utilities used for NoSQL client.
Package common provides common utilities used for NoSQL client.
Package httputil provides utility functions used for HTTP clients.
Package httputil provides utility functions used for HTTP clients.
Package jsonutil provides utility functions for manipulating JSON.
Package jsonutil provides utility functions for manipulating JSON.
Package logger provides logging functionality.
Package logger provides logging functionality.
Package nosqlerr defines types and error code constants that represent errors which may return by the NoSQL client.
Package nosqlerr defines types and error code constants that represent errors which may return by the NoSQL client.
Package types defines types and values used to represent and manipulate data in the Oracle NoSQL Database.
Package types defines types and values used to represent and manipulate data in the Oracle NoSQL Database.
internal
sdkutil
Package sdkutil provides internal utility functions for the SDK.
Package sdkutil provides internal utility functions for the SDK.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL