types

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: 4 Imported by: 0

Documentation

Overview

Package types defines types and values used to represent and manipulate data in the Oracle NoSQL Database. A table in Oracle NoSQL database is defined using a fixed schema that describes the data that table will hold. Application developers should know the data types for each field in the table. The values provided to the table field in an application must conform to the table schema, Go driver makes best effort to map the provided Go values to table field values, the values are validated against the table schema on the backend Oracle NoSQL Database and if they do not conform an error is reported.

On input, the mappings between Go driver types and database types:

Go Driver Types                              Database Types
=========================================    ===============
byte, int8, uint8, int16, uint16, int32      INTEGER
uint32 (0 <= x <= math.MaxInt32)
int (math.MinInt32 <= x <= math.MaxInt32)
-----------------------------------------    ---------------
int64                                        LONG
uint64 (0 <= x <= math.MaxInt64)
uint32 (math.MaxInt32 < x <= math.MaxInt64)
uint (math.MaxInt32 < x <= math.MaxInt64)
int (math.MaxInt32 < x <= math.MaxInt64 or
     math.MinInt64 <= x < math.MinInt32)
-----------------------------------------    ---------------
*big.Rat                                     NUMBER
uint64 (x > math.MaxInt64)
uint (x > math.MaxInt64)
-----------------------------------------    ---------------
float32, float64                             DOUBLE
-----------------------------------------    ---------------
*string                                      STRING
string
-----------------------------------------    ---------------
[]byte                                       BINARY
-----------------------------------------    ---------------
bool                                         BOOLEAN
-----------------------------------------    ---------------
*MapValue                                    MAP
map[string]interface{}
-----------------------------------------    ---------------
[]FieldValue                                 ARRAY
[]interface{}
-----------------------------------------    ---------------
time.Time                                    TIMESTAMP
string representation of time.Time in the
form "2006-01-02T15:04:05.999999999"

On output, the mappings between database types and Go driver types:

Database Types      Go Driver Types
==============      ================
INTEGER             int
LONG                int64
NUMBER              *big.Rat
DOUBLE              float64
STRING              *string
BINARY              []byte
BOOLEAN             bool
MAP                 *MapValue
ARRAY               []FieldValue
TIMESTAMP           time.Time

Note that there are several database types that do not have direct equivalents.

1. ENUM. Enumerations require a schema. When an application fetches a row with an enumeration its value will be mapped to a string value. On input, a string value must be created to represent an ENUM.

2. FIXED_BINARY. This is a specialization of BINARY that uses a fixed number of bytes. It is mapped to []byte that is validated on input.

3. RECORD. This is a fixed-schema map. It is represented as a MapValue, which is more flexible, but is validated on input.

The database types of MAP and ARRAY are fixed-type in that they contain a single type, for example a MAP of INTEGER, an ARRAY of LONG. Although the corresponding Go driver types map[string]interface{} and []interface{} are not fixed-type, on input the types of the elements of these collections must match the table schema.

JSON Mappings

JSON is commonly used as a format for data and there are also well-defined mappings between JSON types and Go driver types. It is a common pattern to construct a row (MapValue) from JSON and generate JSON from a row. Methods on the MapValue type make this pattern easy to use. The following table defines the mappings from JSON types to Go driver types.

JSON Types          Go Driver Types
============        ==============
ARRAY               []FieldValue
BOOLEAN             bool
NUMBER              int, int64, float64 or *big.Rat
OBJECT              *MapValue
STRING              string

JSON has only a single numeric type. By default JSON numbers will be mapped to the most appropriate numeric type (int, int64, float64 or *big.Rat) depending on the value.

The special values JSONNullValueInstance, NullValueInstance and EmptyValueInstance are served as output of the queries for the Oracle NoSQL database, they should not be used as input values.

Index

Constants

View Source
const (
	// SyncPolicySync writes and synchronously flushes the log on transaction commit.
	// Transactions exhibit all the ACID (atomicity, consistency,
	// isolation, and durability) properties.
	SyncPolicySync = iota + 1 // 1

	// SyncPolicyNoSync does not write or synchronously flush the log on transaction commit.
	// Transactions exhibit the ACI (atomicity, consistency, and isolation)
	// properties, but not D (durability); that is, database integrity will
	// be maintained, but if the application or system fails, it is
	// possible some number of the most recently committed transactions may
	// be undone during recovery. The number of transactions at risk is
	// governed by how many log updates can fit into the log buffer, how
	// often the operating system flushes dirty buffers to disk, and how
	// often log checkpoints occur.
	SyncPolicyNoSync // 2

	// SyncPolicyWriteNoSync writes but does not synchronously flush the log on transaction commit.
	// Transactions exhibit the ACI (atomicity, consistency, and isolation)
	// properties, but not D (durability); that is, database integrity will
	// be maintained, but if the operating system fails, it is possible
	// some number of the most recently committed transactions may be
	// undone during recovery. The number of transactions at risk is
	// governed by how often the operating system flushes dirty buffers to
	// disk, and how often log checkpoints occur.
	SyncPolicyWriteNoSync // 3
)
View Source
const (
	// ReplicaAckPolicyAll defines that all replicas must acknowledge that they
	// have committed the transaction. This policy should be selected only if
	// your replication group has a small number of replicas, and those replicas are on
	// extremely reliable networks and servers.
	ReplicaAckPolicyAll = iota + 1 // 1

	// ReplicaAckPolicyNone defines that no transaction commit acknowledgments
	// are required and the master will never wait for replica acknowledgments.
	// In this case, transaction durability is determined entirely by the type of commit
	// that is being performed on the master.
	ReplicaAckPolicyNone // 2

	// ReplicaAckPolicySimpleMajority defines that a simple majority of replicas
	// must acknowledge that they have committed the transaction. This
	// acknowledgment policy, in conjunction with an election policy which
	// requires at least a simple majority, ensures that the changes made by
	// the transaction remains durable if a new election is held.
	ReplicaAckPolicySimpleMajority // 3
)
View Source
const ISO8601Layout = "2006-01-02T15:04:05.999999999"

ISO8601Layout represents the ISO 8601 format of Go's reference time.

View Source
const ISO8601ZLayout = "2006-01-02T15:04:05.999999999Z"

ISO8601ZLayout includes literal "Z"

Variables

View Source
var (
	// JSONNullValueInstance represents an instance of JSONNullValue.
	// This should be used as an immutable singleton object.
	JSONNullValueInstance = &JSONNullValue{}

	// NullValueInstance represents an instance of NullValue.
	// This should be used as an immutable singleton object.
	NullValueInstance = &NullValue{}

	// EmptyValueInstance represents an instance of EmptyValue.
	// This should be used as an immutable singleton object.
	EmptyValueInstance = &EmptyValue{}
)

Functions

This section is empty.

Types

type CapacityMode added in v1.3.0

type CapacityMode int

CapacityMode defines the type of limits for a table.

const (
	// Provisioned table: fixed maximum of read/write units.
	// Note this value is purposefully zero as it is the default and
	// this enables existing app code to work properly
	Provisioned CapacityMode = iota // 0

	// OnDemand table: table scales with usage
	// Added in SDK Version 1.3.0
	OnDemand // 1
)

type Consistency

type Consistency int

Consistency is used to provide consistency guarantees for read operations.

There are two consistency values available: Eventual and Absolute.

1. Eventual consistency means that the values read may be very slightly out of date.

2. Absolute consistency may be specified to guarantee that current values are read.

Absolute consistency results in higher cost, consuming twice the number of read units for the same data relative to Eventual consistency, and should only be used when required.

It is possible to set a default Consistency for a nosqldb.Client instance by using nosqldb.Config.Consistency. If no Consistency is specified in an operation and there is no default value, Eventual consistency is used.

Consistency can be specified as an optional argument to all read operations.

const (
	// Absolute consistency.
	Absolute Consistency = iota + 1 // 1

	// Eventual consistency.
	Eventual // 2
)

func (Consistency) String

func (i Consistency) String() string

type DbType

type DbType int

DbType represents the Oracle NoSQL database types used for field values.

const (
	// Array represents the Array data type.
	// An array is an ordered collection of zero or more elements,
	// all elements of an array have the same type.
	Array DbType = iota // 0

	// Binary represents the Binary data type.
	// A binary is an uninterpreted sequence of zero or more bytes.
	Binary // 1

	// Boolean data type has only two possible values: true and false.
	Boolean // 2

	// Double data type represents the set of all IEEE-754 64-bit floating-point numbers.
	Double // 3

	// Integer data type represents the set of all signed 32-bit integers (-2147483648 to 2147483647).
	Integer // 4

	// Long data type represents the set of all signed 64-bit
	// integers (-9223372036854775808 to 9223372036854775807).
	Long // 5

	// Map represents the Map data type.
	// A map is an unordered collection of zero or more key-value pairs,
	// where all keys are strings and all the values have the same type.
	Map // 6

	// String represents the set of string values.
	String // 7

	// Timestamp represents a point in time as a date or a time.
	Timestamp // 8

	// Number represents arbitrary precision numbers.
	Number // 9

	// JSONNull represents a special value that indicates the absence of
	// an actual value within a JSON data type.
	JSONNull // 10

	// Null represents a special value that indicates the absence of
	// an actual value, or the fact that a value is unknown or inapplicable.
	Null // 11

	// Empty represents the Empty data type.
	// It is used to describe the result of a query expression is empty.
	Empty // 12
)

func (DbType) String

func (i DbType) String() string

type Durability added in v1.3.0

type Durability struct {
	// The sync policy in effect on the Master node.
	MasterSync SyncPolicy `json:"masterSync"`

	// The sync policy in effect on a replica.
	ReplicaSync SyncPolicy `json:"replicaSync"`

	// The replica acknowledgment policy to be used.
	ReplicaAck ReplicaAckPolicy `json:"replicaAck"`
}

Durability defines the durability characteristics associated with a standalone write (put or update) operation.

Added in SDK Version 1.3.0

This is currently only supported in On-Prem installations. It is ignored in the cloud service.

The overall durability is a function of the SyncPolicy and ReplicaAckPolicy in effect for the Master, and the SyncPolicy in effect for each Replica.

func (*Durability) IsSet added in v1.3.0

func (d *Durability) IsSet() bool

IsSet returns true if any durability values are nonzero

type EmptyValue

type EmptyValue struct{}

EmptyValue represents an empty value.

This type is only relevant inside a table field of type JSON and only when that field is indexed.

It is used in index keys to represent missing value for the indexed field.

It is different from a JSONNullValue value, which is a concrete value.

It is also different from NullValue which represents a null or missing field in a fully-typed field in the table schema as opposed to a JSON field.

func (*EmptyValue) MarshalJSON

func (e *EmptyValue) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of EmptyValue.

This implements the json.Marshaler interface.

type FieldRange

type FieldRange struct {
	// FieldPath specifies the path to the field used in the range.
	FieldPath string

	// Start specifies the start value of the range.
	Start interface{}

	// End specifies the end value of the range.
	End interface{}

	// StartInclusive specifies whether Start value is included in the range,
	// i.e., Start value is less than or equal to the first FieldValue in the range.
	//
	// This value is valid only if the Start value is specified.
	StartInclusive bool

	// EndInclusive specifies whether End value is included in the range,
	// i.e., End value is greater than or equal to the last FieldValue in the range.
	//
	// This value is valid only if the End value is specified.
	EndInclusive bool
}

FieldRange defines a range of values to be used in a Client.MultiDelete() operation, as specified in MultiDeleteRequest.FieldRange.

FieldRange is used as the least significant component in a partially specified key value in order to create a value range for an operation that returns multiple rows or keys. The data types supported by FieldRange are limited to the atomic types which are valid for primary keys.

The least significant component of a key is the first component of the key that is not fully specified. For example, if the primary key for a table is defined as the tuple:

<a, b, c>

A FieldRange can be specified for:

"a" if the primary key supplied is empty.
"b" if the primary key supplied to the operation has a concrete value for "a" but not for "b" or "c".

This object is used to scope a Client.MultiDelete() operation. The FieldPath specified must name a field in a table's primary key. The Start and End values used must be of the same type and that type must match the type of the field specified.

Validation of this object is performed when it is used in an operation. Validation includes verifying that the field is in the required key and, in the case of a composite key, that the field is in the proper order relative to the key used in the operation.

type FieldValue

type FieldValue interface{}

FieldValue represents a field value of NoSQL database tables. This is an empty interface.

type JSONNullValue

type JSONNullValue struct{}

JSONNullValue represents an explicit JSON null value in a JSON object or array. On input this type can only be used in a table field of type JSON.

This should be used as an immutable singleton object.

func (*JSONNullValue) MarshalJSON

func (jn *JSONNullValue) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of JSONNullValue.

This implements the json.Marshaler interface.

type MapValue

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

MapValue represents a row in a NoSQL Database table. A top-level row is always a MapValue instance that contains FieldValue objects which may be instances of atomic types, embedded MapValue or an array of aforementioned types, creating a structured row.

MapValue is also used to represent key values used in get operations as well as nested maps or records within a row.

Field names in a MapValue are case-sensitive string values with no duplicates. On input, MapValues of any structure can be created, but when put into a table using a method such as Client.Put() they must conform to the schema of the target table or an error will be returned. Note that in the context of a RECORD field in a table schema, field names are treated as case-insensitive. If a MapValue represents JSON, field names are case-sensitive.

When a MapValue is received on output, such as from Client.Get() and Client.Query(), the value will always conform to the schema of the table from which the value was received or the implied schema of a query projection.

func NewMapValue

func NewMapValue(m map[string]interface{}) *MapValue

NewMapValue creates a MapValue with the specified map m.

func NewMapValueFromJSON

func NewMapValueFromJSON(jsonStr string) (*MapValue, error)

NewMapValueFromJSON creates a MapValue from the specified JSON string. It returns an error if jsonStr is not a valid JSON encoding.

It unmarshals a number specified in jsonStr as a json.Number instead of as a float64. Non-numeric numbers such as NaN, -Inf, +Inf are not allowed.

func NewOrderedMapValue

func NewOrderedMapValue() *MapValue

NewOrderedMapValue creates an ordered MapValue which keeps insertion orders when key/value pairs are inserted into MapValue over the Put() method. An ordered MapValue guarantees that key/value pairs can be retrieved over the GetByIndex(i int) method by specifying the insertion order.

func ToMapValue

func ToMapValue(k string, v interface{}) *MapValue

ToMapValue is a convenience function that converts a key/value pair into a MapValue.

func (*MapValue) Delete

func (m *MapValue) Delete(k string)

Delete removes the value indexed by k from MapValue. If MapValue is ordered and the desired value is removed, the insertion order is adjusted accordingly to reflect the changes. The insertion order of key/value pairs that were inserted after the removed one is advanced by 1.

It is not recommended to use Delete on an ordered MapValue frequently as it is inefficient to keep track of and adjust insertion order after a value is deleted.

func (*MapValue) Get

func (m *MapValue) Get(k string) (v interface{}, ok bool)

Get looks for a value v with specified key k. If it finds the value, it returns that value and sets ok to true. Otherwise, it returns nil and sets ok to false.

func (*MapValue) GetByIndex

func (m *MapValue) GetByIndex(idx int) (k string, v interface{}, ok bool)

GetByIndex only applies to an ordered MapValue. It looks for key k and value v with specified index idx, which is 1-based index representing the insertion order. For example, the index of first key/value pairs inserted into MapValue is 1, the index of second key/value pairs inserted is 2, and so on. If the method finds k and v, it returns them and sets ok to true. Otherwise, it returns zero value for k and v, and sets ok to false.

func (*MapValue) GetFloat64

func (m *MapValue) GetFloat64(k string) (f64 float64, ok bool)

GetFloat64 returns the float64 value f64 associated with the specified key k. If the value does not exist, or is not a float64 value, this method returns 0 and sets ok to false.

func (*MapValue) GetInt

func (m *MapValue) GetInt(k string) (i int, ok bool)

GetInt returns the int value i associated with the specified key k. If the value does not exist, or is not an int value, this method returns 0 and sets ok to false.

func (*MapValue) GetInt64

func (m *MapValue) GetInt64(k string) (i64 int64, ok bool)

GetInt64 returns the int64 value i64 associated with the specified key k. If the value does not exist, or is not an int64 value, this method returns 0 and sets ok to false.

func (*MapValue) GetString

func (m *MapValue) GetString(k string) (s string, ok bool)

GetString returns the string value s associated with the specified key k. If the value does not exist, or is not a string value, this method returns an empty string and sets ok to false.

func (*MapValue) IsOrdered

func (m *MapValue) IsOrdered() bool

IsOrdered reports whether the MapValue keeps insertion order.

func (*MapValue) Len

func (m *MapValue) Len() int

Len returns the number of key/value pairs stored in MapValue.

func (*MapValue) Map

func (m *MapValue) Map() map[string]interface{}

Map returns the underlying map of MapValue.

func (*MapValue) MarshalJSON

func (m *MapValue) MarshalJSON() ([]byte, error)

MarshalJSON returns MapValue m as the JSON encoding of m.

This implements the json.Marshaler interface.

func (*MapValue) Put

func (m *MapValue) Put(k string, v interface{}) *MapValue

Put inserts a value v indexed by key k into MapValue. If MapValue is ordered, it keeps track of the insertion order.

type NullValue

type NullValue struct{}

NullValue represents a null value or missing value in a fully-typed schema.

This type only exists in index keys on a fully-typed field and never inside indexed JSON.

func (*NullValue) MarshalJSON

func (n *NullValue) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of NullValue.

This implements the json.Marshaler interface.

type OperationState

type OperationState int

OperationState represents the current state of the operation.

This is used for on-premise only.

const (
	// UnknownOpState represents the operation state is unknown.
	UnknownOpState OperationState = iota // 0

	// Complete represents the operation is complete and was successful.
	Complete // 1

	// Working represents the operation is in progress.
	Working // 2
)

func (OperationState) GoString

func (st OperationState) GoString() string

GoString defines the Go syntax for the OperationState value.

This implements the fmt.GoStringer interface.

func (OperationState) String

func (i OperationState) String() string

type PutOption

type PutOption int

PutOption represents an option for the put operation. It is used by PutRequest. The available put options are:

PutIfAbsent
PutIfPresent
PutIfVersion
const (
	// PutIfAbsent means put operation should only succeed if the row does not exist.
	PutIfAbsent PutOption = 4 // 4

	// PutIfPresent means put operation should only succeed if the row exists.
	PutIfPresent PutOption = 5 // 5

	// PutIfVersion means put operation should succeed only if the row exists
	// and its Version matches the specified version.
	PutIfVersion PutOption = 6 // 6
)

func (PutOption) GoString

func (opt PutOption) GoString() string

GoString defines the Go syntax for the PutOption value.

This implements the fmt.GoStringer interface.

func (PutOption) String

func (i PutOption) String() string

type ReplicaAckPolicy added in v1.3.0

type ReplicaAckPolicy int

ReplicaAckPolicy defines the policy for how replicated commits are handled. A replicated environment makes it possible to increase an application's transaction commit guarantees by committing changes to its replicas on the network.

type SyncPolicy added in v1.3.0

type SyncPolicy int

SyncPolicy represents policies to be used when committing a transaction. High levels of synchronization offer a greater guarantee that the transaction is persistent to disk, but trade that off for lower performance.

type TableState

type TableState int

TableState represents current state of a table.

The available table states are:

Active
Creating
Dropped
Dropping
Updating
const (
	// Active represents the table is ready to be used.
	// This is the steady state after table creation or modification.
	Active TableState = iota // 0

	// Creating represents the table is being created and cannot yet be used.
	Creating // 1

	// Dropped represents the table has been dropped or does not exist.
	Dropped // 2

	// Dropping represents the table is being dropped and cannot be used.
	Dropping // 3

	// Updating represents the table is being updated.
	// It is available for normal use, but additional table modification
	// operations are not permitted while the table is in this state.
	Updating // 4
)

func (TableState) GoString

func (st TableState) GoString() string

GoString defines the Go syntax for the TableState value.

This implements the fmt.GoStringer interface.

func (TableState) IsTerminal

func (st TableState) IsTerminal() bool

IsTerminal checks if current table state is a terminal state. This returns true if current state is either Active or Dropped, returns false otherwise.

func (TableState) String

func (i TableState) String() string

type TimeToLive

type TimeToLive struct {
	// Value represents number of time units.
	Value int64

	// Unit represents the time unit that is either Hours or Days.
	Unit TimeUnit
}

TimeToLive represents a period of time, specialized to the needs of this driver.

This is restricted to durations of days and hours. It is only used as input related to time to live (TTL) for row instances.

Construction of TimeToLive values allows only day and hour durations for efficiency reasons. Durations of days are recommended as they result in the least amount of storage overhead.

Only positive durations are allowed on input, although negative durations can be returned if the expiration time of a row is in the past relative to the reference time.

func (TimeToLive) ToDuration

func (ttl TimeToLive) ToDuration() time.Duration

ToDuration converts the TimeToLive value into a time.Duration value.

type TimeUnit

type TimeUnit int

TimeUnit represents time durations at a given unit.

const (
	// Hours represents time durations in hours.
	Hours TimeUnit = iota + 1 // 1

	// Days represents time durations in days.
	Days // 2
)

func (TimeUnit) GoString

func (tu TimeUnit) GoString() string

GoString defines the Go syntax for the TimeUnit value.

This implements the fmt.GoStringer interface.

func (TimeUnit) String

func (i TimeUnit) String() string

type Version

type Version []byte

Version represents the version of a row in the database. This is an opaque object from an application perspective.

It is returned by successful Client.Put() or Client.Get() operations and can be used in PutRequest.MatchVersion and DeleteRequest.MatchVersion to conditionally perform those operations to ensure an atomic read-modify-write cycle. Use of Version in this way adds cost to operations so it should be done only if necessary.

Jump to

Keyboard shortcuts

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