12. API: SodaDocument Class
SodaDocuments represents the document for SODA read and write operations.
Note
In this release, SODA is only supported in the node-oracledb Thick mode. See Enabling node-oracledb Thick Mode.
SODA can be used with Oracle Database 18.3 and above, when node-oracledb
uses Oracle Client 18.5 or Oracle Client 19.3, or later. The SODA bulk
insert methods sodaCollection.insertMany()
and
sodaCollection.insertManyAndGet()
are in Preview status.
SodaDocument objects can be created in three ways:
The result of
sodaDatabase.createDocument()
. This is a proto SodaDocument object usable for SODA insert and replace methods. The SodaDocument will have content and media type components set. Attributes likecreatedOn
will not be defined. Optional attributes not specified when callingcreateDocument()
will also not be defined.The result of a read operation from the database, such as calling
sodaOperation.getOne()
, or fromsodaDocumentCursor.getNext()
after asodaOperation.getCursor()
call. These return complete SodaDocument objects containing the document content and attributes, such as time stamps.The result of
sodaCollection.insertOneAndGet()
,sodaOperation.replaceOneAndGet()
, orsodaCollection.insertManyAndGet()
methods. These return SodaDocuments that contain all attributes except the document content itself. They are useful for finding document attributes such as system generated keys, and versions of new and updated documents.
12.1. SodaDocument Properties
The available document properties are shown below. Document content of
queried SodaDocument objects is only accessible via one of the accessor
methods getContent()
,
sodaDocument.getContentAsBuffer()
or
sodaDocument.getContentAsString()
.
Other properties of a SodaDocument object can be accessed directly. They are read-only. The properties for default collections are listed below.
Added in version 3.0.
- sodaDocument.createdOn
This read-only property returns the creation time of the document as a string in the UTC time zone using an ISO8601 format such as ‘2018-07-11T01:37:50.123456Z’ or ‘2018-07-11T01:37:50.123Z’. By default, SODA sets this automatically.
- sodaDocument.key
This read-only property is a string that returns a unique key value for this document. By default, SODA automatically generates the key.
- sodaDocument.lastModified
This read-only property returns the last modified time of the document as a string in the UTC time zone using an ISO8601 format such as ‘2018-07-11T01:37:50.123456Z’ or ‘2018-07-11T01:37:50.123Z’. By default, SODA sets this automatically.
- sodaDocument.mediaType
This read-only property is an arbitrary string value designating the content media type. The recommendation when creating documents is to use a MIME type for the media type. By default, collections store only JSON document content and this property will be ‘application/json’. This property will be null if the media type is unknown, which will only be in the rare case when a collection was created to store mixed or non-JSON content on top of a pre-existing database table, and that table has NULLs in its
mediaType
column.
- sodaDocument.version
This read-only property is a string that returns the version of the document. By default, SODA automatically updates the version each time the document is changed.
12.2. SodaDocument Methods
These methods return the document content stored in a SodaDocument.
Which one to call depends on the content and how you want to use it. For
example, if the document content is JSON, then any of the methods may be
called. But if the document content is binary, then only
sodaDocument.getContentAsBuffer()
may be called.
Although documents cannot be null, content can be.
- sodaDocument.getContent()
Added in version 3.0.
getContent()
A synchronous method that returns the document content as an object. An exception will occur if the document content is not JSON and cannot be converted to an object.
- sodaDocument.getContentAsBuffer()
Added in version 3.0.
getContentAsBuffer()
A synchronous method that returns the document content as a Buffer.
If the documents were originally created with
sodaDatabase.createDocument()
, then documents are returned as they were created.For documents fetched from the database where the collection storage is BLOB (which is the default), and whose
mediaType
is ‘application/json’, then the buffer returned is identical to that which was stored. If the storage is not BLOB, it is UTF-8 encoded.
- sodaDocument.getContentAsString()
Added in version 3.0.
getContentAsString()
A synchronous method that returns JSON document content as a String.
An exception will occur if the document content cannot be converted to a string.
If the document encoding is not known, UTF8 will be used.