Marker type that represents types of field values in a table, which are as
used property values for rows and primary keys.
FieldValue represents a data item in Oracle NoSQL Database.
FieldValue objects can be one of several JavaScript and Node.js types,
the type being dependent on how this value maps onto a given database
type. For put and other operations where field values are used as input
their type must be one of the allowable types that maps onto given
database type (usually being the type of a table field).
FieldValue objects used for put operations are not validated against the
target table schema in the driver. Validation happens where the table
schema is available. If an instance does not match the target table an
error results.
You may specify field value as a (synchronous) function. In this case the
function will be called with no arguments and its return value will be used
as the field value. This could be useful if this function is returned from
a closure context or bound to a class that automatically generates field
values in some manner.
FieldValue objects returned by the driver (such as from get or query
operations) always conform to a table schema, or to the shape implied
by a query projection.
Here we will discuss how JavaScript types map onto the database types and
vice versa. When field values are used as an input (such as by
put), some conversions are allowed so there could be
more than one JavaScript type used for given database type. In this
instance, we will list preferred JavaScript type first followed by others
if any. For output field values returned by the driver (such as by
get and query)
there is a definite JavaScript type used for a given database type. For
completeness, we will list mappings on input and on output separately.
Note that for composite database types such as Array, Map, Record and
JSON, their constituent elements also follow these mappings.
For datatype Number, the driver supports integration with 3rd
party number libraries such as decimal.js, bignumber.js and others. See
DBNumberConfig for details. If this feature is enabled, the
field value will be an object representing number in the 3rd party
library, indicated in the table below as "3rd party number". Thus 3rd
party number will be the output type and preferred input type. If this
feature is not enabled, the output type and preferred input type will be
Javascript number. In both cases, you may also use string (representing
number) as an input type.
Oracle NoSQL Database has a special type JSON NULL, which represents a
JSON type NULL. JSON NULL may occur as a
value of a field of Oracle NoSQL Database type JSON or one of its
subfields that has a value 'null'. JSON NULL value is different and
separate from SQL NULL. For example, if table MyTable has a field
info of type JSON, a query such as
SELECT info.name from MyTable will yield different results for
records where the value of info.name is null (e.g. if the value of
info is { "name": null }) with result being JSON NULL and for
records where the value of the info field itself is NULL
(SQL NULL), with result being a SQL NULL. In addition, the info
field itself may take values of SQL NULL or JSON NULL which are distinct
values, the latter being a value of a JSON type NULL (i.e. the value of
info is JSON value null). For more details, please see
SQL Reference Guide
and SQL for Oracle NoSQL Database Specification.
The driver represents JSON NULL as JavaScript type null and SQL NULL
as JavaScript type undefined. When such distinction is not
important, you may use non-strict comparison (e.g. value == null)
to determine if the field value is NULL (either SQL or JSON). To
distinquish between JSON and SQL NULL, use strict comparison (e.g.
value === undefined). Note that for non-JSON fields, on input you
may pass either undefined or null, or omit a field alltogether for
put operations, all of the above being interpreted as
SQL NULL. For JSON fields, on input you may use either null or undefined
as a value of the subfield (e.g. info.name) which will be
interpreted as JSON NULL, but for the field itself (e.g. info)
null and undefined will be treated as distinct values (JSON NULL and SQL
NULL correspondingly) as mentioned above.
Database Type
JavaScript Input Type(s)
JavaScript
Output Type
Array
Array
Array
Binary
Buffer
Buffer
Boolean
boolean
boolean
Double
number
number
Enum
string
string
Fixed Binary
Buffer
Buffer
Float
number
number
Integer
number
number
Json
object, string, Map
object
Json Null
null, undefined (only as sub-field of JSON field)
null
Long
number, bigint
number, bigint
Map
object, Map
object
SQL Null
undefined (or omit field), null (only for non-JSON fields)
undefined
Number
3rd party number, Javascript number (with limitation), string
3rd party number or Javascript number (with limitation)
Record
object, Map
object
String
string
string
Timestamp
Date, string
Date
Note the following:
For database types Binary and FixedBinary the driver uses Node.js
Buffer class
For database type Long, you have an option to use either
JavaScript type number or bigint. By default,
number is used. Note that JavaScript type number cannot
have precise representation of integers outside of safe integer range,
that is outside of range from
Number.MIN_SAFE_INTEGER to
Number.MAX_SAFE_INTEGER. For values
outside that range (that is when their magnitude exceeds 53 bits in size),
loss of precision may occur. Alternatively, you can use JavaScript type
BigInt by setting option longAsBigInt.
In this case, values of datatype Long returned by get and query
operations will be represented as bigint, which avoids the loss of
precision for the entire range of datatype Long. For values
passed to operations such as put and delete, you may use either
bigint or number. Note that in either case Long
values passed to the driver may not be outside the range of datatype
Long (from -2^63 to 2^63-1)
For datatype Number, unless you are using 3rd party number
library feature (see DBNumberConfig), the driver will return
Javascript number values in the results, which means loss of precision and
rounding errors may occur in some cases. On input (for put operations),
you may pass NoSQL Number values either as 3rd party numbers (if enabled),
Javascript numbers or strings
To represent database type Timestamp, you may use either
JavaScript Date class or a string. The string
should represent a date in valid ISO 8601 format. Timestamps are always
stored and managed in UTC
Typescript-specific:
Use the above description as a guide to what types are allowed for use as
field values. The users are encouraged to create interfaces or types that
represent the shape of their table rows based on the types described above
and use them as TRow type parameters for APIs such as
get, put,
delete, writeMany,
query, etc.
For Javascript users:
Marker type that represents types of field values in a table, which are as used property values for rows and primary keys.
FieldValue represents a data item in Oracle NoSQL Database. FieldValue objects can be one of several JavaScript and Node.js types, the type being dependent on how this value maps onto a given database type. For put and other operations where field values are used as input their type must be one of the allowable types that maps onto given database type (usually being the type of a table field).
FieldValue objects used for put operations are not validated against the target table schema in the driver. Validation happens where the table schema is available. If an instance does not match the target table an error results.
You may specify field value as a (synchronous) function. In this case the function will be called with no arguments and its return value will be used as the field value. This could be useful if this function is returned from a closure context or bound to a class that automatically generates field values in some manner.
FieldValue objects returned by the driver (such as from get or query operations) always conform to a table schema, or to the shape implied by a query projection.
Here we will discuss how JavaScript types map onto the database types and vice versa. When field values are used as an input (such as by put), some conversions are allowed so there could be more than one JavaScript type used for given database type. In this instance, we will list preferred JavaScript type first followed by others if any. For output field values returned by the driver (such as by get and query) there is a definite JavaScript type used for a given database type. For completeness, we will list mappings on input and on output separately. Note that for composite database types such as Array, Map, Record and JSON, their constituent elements also follow these mappings.
For datatype Number, the driver supports integration with 3rd party number libraries such as decimal.js, bignumber.js and others. See DBNumberConfig for details. If this feature is enabled, the field value will be an object representing number in the 3rd party library, indicated in the table below as "3rd party number". Thus 3rd party number will be the output type and preferred input type. If this feature is not enabled, the output type and preferred input type will be Javascript number. In both cases, you may also use string (representing number) as an input type.
Oracle NoSQL Database has a special type JSON NULL, which represents a JSON type NULL. JSON NULL may occur as a value of a field of Oracle NoSQL Database type JSON or one of its subfields that has a value 'null'. JSON NULL value is different and separate from SQL NULL. For example, if table MyTable has a field info of type JSON, a query such as SELECT info.name from MyTable will yield different results for records where the value of info.name is null (e.g. if the value of info is { "name": null }) with result being JSON NULL and for records where the value of the info field itself is NULL (SQL NULL), with result being a SQL NULL. In addition, the info field itself may take values of SQL NULL or JSON NULL which are distinct values, the latter being a value of a JSON type NULL (i.e. the value of info is JSON value null). For more details, please see SQL Reference Guide and SQL for Oracle NoSQL Database Specification.
The driver represents JSON NULL as JavaScript type null and SQL NULL as JavaScript type undefined. When such distinction is not important, you may use non-strict comparison (e.g. value == null) to determine if the field value is NULL (either SQL or JSON). To distinquish between JSON and SQL NULL, use strict comparison (e.g. value === undefined). Note that for non-JSON fields, on input you may pass either undefined or null, or omit a field alltogether for put operations, all of the above being interpreted as SQL NULL. For JSON fields, on input you may use either null or undefined as a value of the subfield (e.g. info.name) which will be interpreted as JSON NULL, but for the field itself (e.g. info) null and undefined will be treated as distinct values (JSON NULL and SQL NULL correspondingly) as mentioned above.
Note the following:
Typescript-specific:
Use the above description as a guide to what types are allowed for use as field values. The users are encouraged to create interfaces or types that represent the shape of their table rows based on the types described above and use them as TRow type parameters for APIs such as get, put, delete, writeMany, query, etc.