Class FieldValue
Inheritance
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 |
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.
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 |
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 |
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:
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.var recordValue = new RecordValue(); recordValue["id"] = 1000; recordValue["firstName"] = "John";
-
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 theseAs...
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 tostring
using JSON conversion described below. Instances of StringValue can useTo...
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 theTo...
methods for details.
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.
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. |