Show / Hide Table of Contents

Oracle.NoSQL.SDK

Class FieldValue

FieldValue is the base class for all data items in Oracle NoSQL Database.

Inheritance

FieldValue

Implements

IComparable<FieldValue>

IEquatable<FieldValue>

Namespace: Oracle.NoSQL.SDK

Assembly: Oracle.NoSQL.SDK.dll

Syntax

public abstract class FieldValue : Object

Remarks

Each data item is an instance of FieldValue and is used to represent and manipulate data in Oracle NoSQL Database. FieldValue instances are typed and different data types are represented by different subclasses of FieldValue. The type system used here aims to represent all Oracle NoSQL Database data types as well as values of table rows and primary/index keys, although important considerations apply:

A table is defined using a fixed schema that describes the data that the table will hold. The instances of FieldValue do not have access to the table schema and thus allow constructing values of fields or table rows that do not conform to the given table schema. This means the applications must be written knowing the schema. During operations that take data (such as PutAsync(String, MapValue, PutOptions, CancellationToken)), the constructed FieldValue instance is validated against the table schema and if it does not conform the exception is thrown. This validation is not done by the driver, but by the service where the operation is performed. This applies both to the table row as a whole as well as individual fields, as many of Oracle NoSQL data types also specify a schema (e.g. the type of values in an Array field, a sequence of field names and their types in a Record field, a set of values for Enum field, precision of Fixed Binary field, etc.) and FieldValue instances themselves are not aware of that schema.

For operations that return field value instances (such as GetAsync(String, MapValue, GetOptions, CancellationToken) and QueryAsync the returned FieldValue instances always conform to a table schema, or to the shape implied by a query projection.

Data Type Mappings

The following describes the mappings between Oracle NoSQL Database types and corresponding subclasses of FieldValue:

Database Type	Class
Array	ArrayValue
Binary	BinaryValue
Boolean	BooleanValue
Double	DoubleValue
Enum	StringValue
Fixed Binary	BinaryValue
Float	DoubleValue
Integer	IntegerValue
Long	LongValue
Number	NumberValue
Map	MapValue
Record	RecordValue
String	StringValue
Timestamp	TimestampValue

Please note that the above does not represent one-to-one mapping between database types and subclasses of FieldValue. Applications need to be aware of the table schema and ensure that on input the values represented fit into corresponding table field. In particular:

Both data types Double and Float are represented by DoubleValue. Both data types Binary and Fixed Binary are represented by BinaryValue. Both data types String and Enum are represented by StringValue. When using the Enum data type, make sure the value is one of the values defined for the enumeration. On input (for operations such as PutAsync(String, MapValue, PutOptions, CancellationToken)), a Base64 encoded string is also accepted for fields of data types Binary and Fixed Binary.

Table rows and primary keys

Both MapValue and RecordValue classes represent a dictionary with string keys and values of type FieldValue (which can be any of its subclasses). Thus they represent a collection of database field name-value pairs. MapValue represents the dictionary with unordered keys, whereas RecordValue represents an order-preserving dictionary, with the keys preserving the same order in which they were added to the dictionary and thus using the same order when the dictionary is iterated over. Note that RecordValue is a subclass of MapValue thus any RecordValue instance is also an instance of MapValue.
Table rows are ordered collections of field values and thus are represented by RecordValue class. Any table rows returned by the driver, such as from operations GetAsync(String, MapValue, GetOptions, CancellationToken), QueryAsync, etc. are represented by instances of RecordValue. However, on input, when providing table rows to operations such as PutAsync(String, MapValue, PutOptions, CancellationToken) and WriteManyAsync the field ordering is not required, so you may use either MapValue or RecordValue to provide table rows. Primary key values are only used as input to operations such as GetAsync(String, MapValue, GetOptions, CancellationToken), thus they do not require field order and can also be represented as either MapValue or RecordValue. Note that the ordered dictionary is more memory and computation expensive then unordered one and thus MapValue is preferred whenever the field ordering is not required.
In addition to representing table rows and primary keys, these classes also represent data types Map, Record as well as Json objects.

Special values

Two of the FieldValue subclasses represent special values used in Oracle NoSQL Database:

NullValue represents SQL NULL which indicates that value is unknown or inapplicable.
JsonNullValue represents JSON NULL which indicates null value inside field of type Json.

Both of these classes are singletons and each represents a single immutable value defined as Null and JsonNull correspondingly. You may use comparisons like value == FieldValue.Null or value == FiledValue.JsonNull or check by the field value type as value.DbType == DbType.Null or value.DbType == DbType.JsonNull.

JSON Mappings

Oracle NoSQL Database supports fields of data type Json which can represent any valid JSON value. JSON values may be either atomic or complex and can be represented by instances of FieldValue. There are well-defined mappings mappings between JSON types and FieldValue subclasses.
Because the data model supported by FieldValue is richer than JSON it is necessary to define potentially ambiguous mappings as well as provide the ability to affect mappings that are flexible. The following table defines the mappings from JSON types to FieldValuesubclasses:

JSON Type	Class
Array	ArrayValue
Boolean	BooleanValue
Number	One of IntegerValue, LongValue, DoubleValue, NumberValue.
Object	MapValue
String	StringValue
Null	JsonNullValue

Note that JSON only has a single numeric type Number, but there are several numeric types supported in Oracle NoSQL Database. On input (for operations such as PutAsync(String, MapValue, PutOptions, CancellationToken)) you may use any of the numeric FieldValue subclasses as listed above for JSON numeric values. For values returned from the database (such as by operations GetAsync(String, MapValue, GetOptions, CancellationToken) and QueryAsync) the driver will use the most appropriate class among IntegerValue,LongValue, DoubleValue, NumberValue. If the number can be represented as signed 32 bit integer, IntegerValue will be used. If not, but the number can be represented as signed 64-bit integer, LongValue will be used. Floating point numbers are mapped to DoubleValue if the number can be represented as double precision floating point. Otherwise, NumberValue will be used. Note that currently there are some limitations on values NumberValue can represent, see NumberValue for more info.

Corresponding language types

Each subclass of FieldValue representing atomic data type uses corresponding C# type representing its value as follows:

Class	C# Type
BinaryValue	`byte[]`
BooleanValue	`bool`
DoubleValue	`double`
IntegerValue	`int`
LongValue	`long`
NumberValue	`decimal`
StringValue	`string`
TimestampValue	DateTime

Note that the TimestampValue instances always represent date and time in universal time (the Kind property value of DateTime is always Utc).
The casts between corresponding FieldValue instances and their C# types will always succeed as described below.
. There are no corresponding C# types for special values such as NullValue or JsonNullValue or complex values such as ArrayValue, MapValue and RecordValue although you can access atomic parts of the complex value via indexers as described below.

FieldValue conversions.

In order to facilitate creation and using of FieldValue instances by an application, the following casts and conversions are defined:

Implicit conversions from language types such as int, long, double, string, etc. representing atomic values to corresponding instances of FieldValue subclasses such as IntegerValue, LongValue, DoubleValue, StringValue, etc. This allows instantiation and assignment of field values that are part of a complex data type without explicitly instantiating corresponding FieldValue subclasses. For example:
```
                var recordValue = new RecordValue();
                recordValue["id"] = 1000;
                recordValue["firstName"] = "John";
```
Using C# syntax for object and collection initialization the instantiation of field values can be made even more simple as shown in the example below.
Explicit conversions from FieldValue instances representing atomic values to corresponding language types such as int, long, double, string etc. using properties such as AsInt32, AsInt64, AsDouble, AsString etc. Note that these As... properties only perform conversions to their corresponding language data types and do not perform value conversions and do not perform value conversions from one type to another. In case the target language type does not match the calling instance, InvalidCastException is thrown. For example, AsInt32 will only succeed if the instance is IntegerValue.
Explicit cast operators from FieldValue instances to language types representing atomic values. These are the same as As... properties described above and do not perform value conversions.
Several To... methods provide limited ability for value conversion between different types. E.g. ToString() will convert FieldValue instances to string using JSON conversion described below. Instances of StringValue can use To... methods to convert to corresponding language type by parsing the string representation of value.
Conversions between numeric FieldValue instances are allowed and follow the semantics of corresponding methods of the Convert class. Numeric conversions may result in loss of precision, e.g. when calling ToInt32() or ToDouble(). In a checked context, OverflowException will be thrown if the value represented by the instance is outside the range of the target type.
In addition, ToInt64() will return number of milliseconds since Unix Epoch and ToDateTime() and ToDateTime() will do the reverse conversion.
See documentation for the To... methods for details.

To instantiate complex values from string, use using FromJsonString(String, JsonInputOptions) as described below.

JSON conversions.

You can convert FieldValue instances, whether atomic or complex, to JSON string using ToJsonString(JsonOutputOptions). Use JsonOutputOptions to customize the result. You may also construct FieldValue instances from JSON strings using FromJsonString(String, JsonInputOptions). Use JsonInputOptions to customize the conversion.
This also allows you to create table rows from JSON by creating MapValue instances from JSON input and using them with operations like PutAsync(String, MapValue, PutOptions, CancellationToken).
Couple of cases require clarification:

When creating FieldValue from JSON string, the driver will decide which numeric FieldValue subclass to use for JSON Number type. This is similar to values in JSON fields returned from the database by operations such as GetAsync(String, MapValue, GetOptions, CancellationToken) as described above. By default, FromJsonString(String, JsonInputOptions) will have the same semantics. You may customize whether you prefer to store fractional numbers as DoubleValue or NumberValue by using PreferDecimal. See JsonInputOptions for more details.
Instances of BinaryValue are represented in Base64 when converted to JSON string. Currently FromJsonString(String, JsonInputOptions) will not create BinaryValue instances because JSON String type maps to StringValue, but you can create them manually by using FromBase64String(String) and constructing BinaryValue from the resulting byte array.
Instances of both NullValue and JsonNullValue will map to JSON type null. When reading JSON with FromJsonString(String, JsonInputOptions), JSON null will be mapped to JsonNullValue (more specifically, singleton value JsonNull.
Instances of DoubleValue that contain special values such as PositiveInfinity, NegativeInfinity and NaN cannot be represented by JSON type Number and will be represented by strings "Infinity", "-Infinity" and "NaN" respectively when converted to JSON, thus they cannot be converted back from JSON to instances of DoubleValue.

See JsonOutputOptions and JsonInputOptions for more ways to customize JSON conversion, such as representing TimestampValue as number of milliseconds since Unix Epoch.

Other operations.

FieldValue also has indexers by int and string. int indexer allows accessing elements of ArrayValue and string indexer allows accessing values of MapValue and RecordValue by key (see example below). Exception is thrown if an indexer is used on inappropriate subclass of FieldValue.
In addition, FieldValue instances support comparisons and equality checks through interfaces IEquatable<T> and IComparable<T> and overloaded operators ==, !=, <, <=, > and >=. The semantics of the comparisons and equality checks is the same as in SQL and is described in Value Comparison Operators section of the Oracle NoSQL Database SQL Reference Guide. See Equals(FieldValue) and CompareTo(FieldValue) for more details.

FieldValue instances are not thread-safe. Mutable instances such as ArrayValue, MapValue and RecordValue should not be modified while being used by database operations.

Examples

Initializing a MapValue instance representing a row in a table that has fields id LONG, name STRING, address RECORD(street STRING, city STRING), dob TIMESTAMP(0), photo BINARY, friends ARRAY(INTEGER)

	var row = new MapValue
	{
              id = 1001,
	    name = "John Doe",
	    address = new RecordValue
	    {
	        street = "10 1st Street",
	        city = "Some City"
	    },
	    dob = new DateTime(1960, 3, 5),
	    photo = File.ReadAllBytes("photo.jpg"),
	    friends = new ArrayValue { 1002, 1003, 1004 }
          };

Constructors

Name	Description
FieldValue()

Fields

Name	Description
JsonNull	Singleton instance of JsonNullValue.
Null	Singleton instance of NullValue.

Properties

Name	Description
AsArrayValue	Gets the value of this instance as ArrayValue.
AsBoolean	Gets the value of this instance as boolean.
AsByteArray	Gets the value of this instance as byte array.
AsDateTime	Gets the value of this instance as date and time.
AsDecimal	Gets the value of this instance as decimal number.
AsDouble	Gets the value of this instance as double precision floating point number.
AsInt32	Gets the value of this instance as 32-bit signed integer.
AsInt64	Gets the value of this instance as 64-bit signed integer.
AsMapValue	Gets the value of this instance as MapValue.
AsRecordValue	Gets the value of this instance as RecordValue.
AsString	Gets the value of this instance as string.
Count	Gets the number of elements in the collection.
DbType	Gets DbType of this instance which represents the type of this value.
Item[Int32]	Gets or sets the element at the specified index.
Item[String]	Gets or sets the value associated with the specified key.

Methods

Name	Description
CompareTo(FieldValue)	Compares this instance to the specified FieldValue instance and returns and returns an integer that indicates whether this instance is less than, the same as, or greater than the specified FieldValue instance.
DeserializeFromJson(ref Utf8JsonReader, JsonInputOptions)	Creates FieldValue instance from JSON data represented by Utf8JsonReader.
Equals(FieldValue)	Returns a value indicating whether the value of this instance is equal to the value of the specified FieldValue instance.
Equals(Object)	Returns a value indicating whether this instance is equal to a specified object.
FromJsonString(String, JsonInputOptions)	Creates FieldValue instance from JSON string.
GetHashCode()	Returns the hash code for this instance.
SerializeAsJson(Utf8JsonWriter, JsonOutputOptions)	Writes JSON representation of the value to the stream represented by Utf8JsonWriter.
ToBoolean()	Converts value of this instance to boolean.
ToByteArray()	Converts value of this instance to byte array.
ToDateTime()	Converts value of this instance to date and time value.
ToDecimal()	Converts value of this instance to decimal number.
ToDouble()	Converts value of this instance to double precision floating point number.
ToInt32()	Converts value of this instance to 32-bit signed integer.
ToInt64()	Converts value of this instance to 64-bit signed integer.
ToJsonString(JsonOutputOptions)	Returns JSON representation of the value.
ToString()	Converts value of this instance to `string`.

Operators

Name	Description
Equality(FieldValue, FieldValue)	Determines whether two specified instances of FieldValue are equal.
Explicit(FieldValue to Boolean)	Defines an explicit conversion from FieldValue instance to boolean.
Explicit(FieldValue to Byte[])	Defines an explicit conversion from FieldValue instance to byte array.
Explicit(FieldValue to DateTime)	Defines an explicit conversion from FieldValue instance to date and time.
Explicit(FieldValue to Decimal)	Defines an explicit conversion from FieldValue instance to decimal number.
Explicit(FieldValue to Double)	Defines an explicit conversion from FieldValue instance to double precision floating point number.
Explicit(FieldValue to Int32)	Defines an explicit conversion from FieldValue instance to 32-bit signed integer.
Explicit(FieldValue to Int64)	Defines an explicit conversion from FieldValue instance to 64-bit signed integer.
Explicit(FieldValue to String)	Defines an explicit conversion from FieldValue instance to string.
GreaterThan(FieldValue, FieldValue)	Determines whether one specified instance of FieldValue is greater than another specified instance of FieldValue.
GreaterThanOrEqual(FieldValue, FieldValue)	Determines whether one specified instance of FieldValue is greater than or equal to another specified instance of FieldValue.
Implicit(Boolean to FieldValue)	Defines implicit conversion from `bool` value to FieldValue instance of subclass BooleanValue.
Implicit(Byte[] to FieldValue)	Defines implicit conversion from `byte[]` value to FieldValue instance of subclass BinaryValue.
Implicit(DateTime to FieldValue)	Defines implicit conversion from DateTime value to FieldValue instance of subclass TimestampValue.
Implicit(Decimal to FieldValue)	Defines implicit conversion from `decimal` value to FieldValue instance of subclass NumberValue.
Implicit(Double to FieldValue)	Defines implicit conversion from `double` value to FieldValue instance of subclass DoubleValue.
Implicit(Int32 to FieldValue)	Defines implicit conversion from `int` value to FieldValue instance of subclass IntegerValue.
Implicit(Int64 to FieldValue)	Defines implicit conversion from `long` value to FieldValue instance of subclass LongValue.
Implicit(String to FieldValue)	Defines implicit conversion from String value to FieldValue instance of subclass StringValue.
Inequality(FieldValue, FieldValue)	Determines whether two specified instances of FieldValue are not equal.
LessThan(FieldValue, FieldValue)	Determines whether one specified instance of FieldValue is less than another specified instance of FieldValue.
LessThanOrEqual(FieldValue, FieldValue)	Determines whether one specified instance of FieldValue is less than or equal to another specified instance of FieldValue.