9. API: SodaCollection Class
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.
Note
In this release, SODA is only supported in the node-oracledb Thick mode. See Enabling node-oracledb Thick Mode.
9.1. SodaCollection Properties
Each SodaCollection object contains read-only properties:
- sodaCollection.metaData
New in version 3.0.
This read-only property is an object which contains the metaData of the current collection. See SODA Client-Assigned Keys and Collection Metadata.
Its type was changed to Object in node-oracledb 4.0.
- sodaCollection.name
New in version 3.0.
This read-only property is a string which specifies the name of the current collection.
9.2. SodaCollection Methods
- sodaCollection.createIndex()
New in version 3.0.
Promise:
promise = createIndex(Object indexSpec);
Creates an index on a SODA collection, to improve the performance of SODA query-by-examples (QBE) or enable text searches. See Creating and Dropping SODA Indexes for information on indexing.
Note that a commit should be performed before attempting to create an index.
If
oracledb.autoCommit
is true, andcreateIndex()
succeeds, then any open user transaction is committed. Note SODA DDL operations do not commit an open transaction the way that SQL always does for DDL statements.The parameters of the
sodaCollection.createIndex()
method are: Parameter
Data Type
Description
indexSpec
Object
An object with fields as shown in the SODA Index Specifications (Reference) manual.
Callback:
If you are using the callback programming style:
createIndex(Object indexSpec, function(Error error){});
See sodaCollection.createIndex() Parameters for information on the parameters.
The parameters of the callback function
function(Error error)
are:Callback Function Parameter
Description
Error
error
If
createIndex()
succeeds,error
is NULL. If an error occurs, thenerror
contains the error message.See Creating and Dropping SODA Indexes for more information.
- sodaCollection.drop()
New in version 3.0.
Promise:
promise = drop();
Drops the current collection.
An error such as ORA-40626 will be returned and the collection will not be dropped if there are uncommitted writes to the collection in the current transaction.
If the collection was created with mode oracledb.SODA_COLL_MAP_MODE, then
drop()
will not physically delete the database storage containing the collection, and won’t drop SODA indexes. Instead it will simply unmap the collection, making it inaccessible to SODA operations.If
oracledb.autoCommit
is true, anddrop()
succeeds, then any open user transaction is committed. Note SODA operations do not commit an open transaction the way that SQL always does for DDL statements.If the collection was created with custom metadata changing the key assignment method to SEQUENCE, the
drop()
method will not delete the underlying Oracle sequence. This is in case it was created outside SODA. To drop the sequence, use the SQL command DROP SEQUENCE afterdrop()
has completed.Note you should never use SQL DROP TABLE command on the database table underlying a collection. This will not clean up SODA’s metadata. If you do accidentally execute DROP SQL, you should cleanup the metadata with
drop()
or execute the SQL statement:SELECT DBMS_SODA.DROP_COLLECTION('myCollection') FROM DUAL;
.Callback:
If you are using the callback programming style:
drop(function(Error error, Object result){});
The parameters of the callback function
function(Error error, Object result)
are:Callback Function Parameter
Description
Error
error
If
drop()
succeeds,error
is NULL. It is not an error if the collection does not exist. If an error occurs, thenerror
contains the error message.Object
result
The
result
object contains one attribute:Boolean dropped
If the drop operation succeeded,
dropped
will be true. If no collection was found,dropped
will be false.
- sodaCollection.dropIndex()
New in version 3.0.
Promise:
promise = dropIndex(String indexName [, Object options]);
Drops the specified index.
If
oracledb.autoCommit
is true, anddropIndex()
succeeds, then any open user transaction is committed. Note SODA operations do not commit an open transaction the way that SQL always does for DDL statements.The parameters of the
sodaCollection.dropIndex()
method are: Parameter
Data Type
Description
indexName
String
Name of the index to be dropped.
options
Object
The
options
parameter can have the following attribute:Boolean force
Setting
force
to true forces dropping of a JSON Search index or Spatial index if the underlying Oracle Database domain index does not permit normal dropping. See DROP INDEX.Callback:
If you are using the callback programming style:
dropIndex(String indexName [, Object options], function(Error error, Object result){});
See sodaCollection.dropIndex() Parameters for information on the
indexName
andoptions
parameters.The parameters of the callback function
function(Error error, Object result)
are:Callback Function Parameter
Description
Error
error
If
dropIndex()
succeeds,error
is NULL. It is not an error if the index does not exist. If an error occurs, thenerror
contains the error message.Object
result
If dropping the index succeeded,
dropped
will be true. If no index was found,dropped
will be false.See Creating and Dropping SODA Indexes for an example.
- sodaCollection.find()
New in version 3.0.
find()
The synchronous
find()
method is used to locate and order a set of SODA documents for retrieval, replacement, or removal. It creates and returns a SodaOperation object which is used via method chaining with non-terminal and terminal methods described below. Note that SodaOperation is an internal object whose attributes should not be accessed directly.Returns a SodaOperation object.
Example
documents = await collection.find().filter({"address.city": "Melbourne", "salary": {"$gt": 500000}}).getDocuments();
See Simple Oracle Document Access (SODA) for more examples.
- sodaCollection.listIndexes()
New in version 6.2.
Promise::
promise = listIndexes();
Retrieves all the indexes from a SODA collection. This method returns an array of objects that contains the index specifications.
This method requires Oracle Client 21.3 or later (or Oracle Client 19 from 19.13).
Callback:
If you are using the callback programming style:
listIndexes(function(Error error, Array listIndexes){});
The parameters of the callback function
function(Error error, Array listIndexes)
are:Callback Function Parameter
Description
Error
error
If
listIndexes()
succeeds,error
is NULL. If an error occurs, thenerror
contains the error message.Array
listIndexes
An array of objects, each containing the index specifications of the SODA collection.
See Retrieving All Index Specifications for an example.
9.3. SodaOperation Class
You can chain together SodaOperation methods to specify read or write operations against a collection.
Non-terminal SodaOperation methods return the same object on which they are invoked, allowing them to be chained together.
A terminal SodaOperation method always appears at the end of a method chain to execute the operation.
A SodaOperation object is an internal object. You should not directly modify its properties.
9.3.1. Non-terminal SodaOperation Methods
Non-terminal SodaOperation methods are chained together to set criteria that documents must satisfy. At the end of the chain, a single terminal method specifies the operation to be performed on the matching documents.
When a non-terminal method is repeated, the last one overrides the
earlier one. For example if find().key("a").key("b")...
was used,
then only documents with the key “b” are matched. If
find().keys(["a","b"]).key("c")...
is used, then only the document
with the key “c” is matched.
- sodaOperation.fetchArraySize()
New in version 5.0.
fetchArraySize(Number size)
Sets the size of an internal buffer used for fetching documents from a collection with the terminal SodaOperation methods
getCursor()
andgetDocuments()
. Changingsize
may affect performance but does not affect how many documents are returned.If
fetchArraySize()
is not used, the size defaults to the current value oforacledb.fetchArraySize
.For node-oracledb examples, see SODA Query-by-Example Searches for JSON Documents.
It requires Oracle Client 19.5 or later, and Oracle Database 18.3 or later.
- sodaOperation.filter()
New in version 3.0.
filter(Object filterSpec)
Sets a filter specification for the operation, allowing for complex document queries and ordering of JSON documents. Filter specifications can include comparisons, regular expressions, logical, and spatial operators, among others. See Overview of SODA Filter Specifications (QBEs) and SODA Filter Specifications (Reference).
For node-oracledb examples, see SODA Query-by-Example Searches for JSON Documents.
- sodaOperation.hint()
New in version 5.2.
hint(String hint)
The
hint()
value can be used to pass an Oracle hint to terminal SodaOperation Methods. It is string in the same format as a SQL hint but without any comment characters, for examplehint("MONITOR")
. Pass only the hint"MONITOR"
(turn on monitoring) or"NO_MONITOR"
(turn off monitoring). See the Oracle Database SQL Tuning Guide documentation MONITOR and NO_MONITOR Hints and Monitoring Database Operations for more information.It requires Oracle Client 21.3 or higher (or Oracle Client 19 from 19.11).
- sodaOperation.key()
New in version 3.0.
key(String value)
Sets the key value to be used to match a document for the operation. Any previous calls made to this method or
keys()
will be ignored.SODA document keys are unique.
- sodaOperation.keys()
New in version 3.0.
keys(Array value)
Sets the keys to be used to match multiple documents for the operation. Any previous calls made to this method or
sodaOperation.key()
will be ignored.SODA document keys are unique.
A maximum of 1000 keys can be used.
- sodaOperation.limit()
New in version 3.0.
limit(Number n)
Sets the maximum number of documents that a terminal method will apply to. The value of
n
must be greater than 0. The limit is applied to documents that match the other SodaOperation criteria. Thelimit()
method only applies to SodaOperation read operations likegetCursor()
andgetDocuments()
. If a filter$orderby
is not used, the document order is internally defined.The
limit()
method cannot be used in conjunction withcount()
.
- sodaOperation.lock()
New in version 6.2.
lock()
Locks the documents fetched from the collection.
Using
lock()
allows for pessimistic locking, that is, only the current user that performed the lock can modify the documents in the collection. Other users can only perform operations on these documents once they are unlocked. The functionality of this method is equivalent to theSELECT FOR UPDATE
clause.The documents can be unlocked with an explicit call to
commit()
orrollback()
on the connection. Ensure that theoracledb.autoCommit
is set to false for the connection. Otherwise, the documents will be unlocked immediately after the operation is complete.This method should only be used with read operations (other than
count()
), and should not be used in conjunction with non-terminal methodsskip()
andlimit()
.If this method is specified in conjunction with a write operation, then this method is ignored.
This method requires Oracle Client 21.3 or later (or Oracle Client 19 from 19.11).
- sodaOperation.skip()
New in version 3.0.
skip(Number n)
Sets the number of documents that will be skipped before the terminal method is applied. The value of
n
must be greater or equal to 0. The skip applies to documents that match the other SodaOperation criteria.If a filter
$orderby
is not used, the document order (and hence which documents are skipped) is internally defined.The
skip()
method only applies to SodaOperation read operations likegetDocuments()
. It cannot be used withcount()
.
- sodaOperation.version()
New in version 3.0.
version(String value)
Sets the document version that documents must have.
This is typically used in conjunction with a key, for example
collection.find().key("k").version("v").replaceOne(doc)
.Using
version()
allows for optimistic locking, so that the subsequent SodaOperation terminal method does not affect a document that someone else has already modified. If the requested document version is not matched, then your terminal operation will not impact any document. The application can then query to find the latest document version and apply any desired change.
9.3.2. Terminal SodaOperation Methods
A terminal SodaOperation method operates on the set of documents that satisfy the criteria specified by previous non-terminal methods in the method chain. Only one terminal method can be used in each chain.
- sodaOperation.count()
New in version 3.0.
Promise:
promise = count();
Finds the number of documents matching the given SodaOperation query criteria.
If
skip()
orlimit()
are set, thencount()
will return an error.If
oracledb.autoCommit
is true, andcount()
succeeds, then any open transaction on the connection is committed.Callback:
If you are using the callback programming style:
count(function (Error error, Object result){});
The parameters of the callback function
function (Error error, Object result)
are:Callback Function Parameter
Description
Error
error
If
count()
succeeds,error
is NULL. If an error occurs, thenerror
contains the error message.Object
result
The result object contains one attribute:
Number count
The number of documents matching the SodaOperation criteria.
Due to Node.js type limitations, the largest
count
value will be 232 - 1, even if more rows exist. Larger values will wrap.
- sodaOperation.getCursor()
New in version 3.0.
Promise:
promise = getCursor()
Returns a SodaDocumentCursor for documents that match the SodaOperation query criteria. The cursor can be iterated over with
sodaDocumentCursor.getNext()
to access each SodaDocument.When the application has completed using the cursor it must be closed with
sodaDocumentCursor.close()
.If the number of documents is known to be small, it is recommended to use
sodaOperation.getDocuments()
instead.If
oracledb.autoCommit
is true, andgetCursor()
succeeds, then any open transaction on the connection is committed.Callback:
If you are using the callback programming style:
getCursor(function(Error error, SodaDocumentCursor cursor){});
The parameters of the callback function
function(Error error, SodaDocumentCursor cursor)
are:Callback Function Parameter
Description
Error
error
If
getCursor()
succeeds,error
is NULL. If an error occurs, thenerror
contains the error message.SodaDocumentCursor
cursor
A cursor that can be iterated over to access SodaDocument objects matching the SodaOperation search criteria.
- sodaOperation.getDocuments()
New in version 3.0.
Promise:
promise = getDocuments();
Gets an array of SodaDocuments matching the SodaOperation query criteria. An empty array will be returned when no documents match.
Where the number of matching documents is known to be small, this API should be used in preference to
sodaOperation.getCursor()
.If
oracledb.autoCommit
is true, andgetDocuments()
succeeds, then any open transaction on the connection is committed.Callback:
If you are using the callback programming style:
getDocuments(function(Error error, Array documents){});
The parameters of the callback function
function(Error error, Array documents)
are:Callback Function Parameter
Description
Error
error
If
getDocuments()
succeeds,error
is NULL. If an error occurs, thenerror
contains the error message.Array
documents
An array of SodaDocuments that match the SodaOperation query criteria.
- sodaOperation.getOne()
New in version 3.0.
Promise:
promise = getOne();
Obtains one document matching the SodaOperation query criteria. If the criteria match more than one document, then only the first is returned.
Typically
getone()
should be used withkey(k)
orkey(k).version(v)
to ensure only one document is matched.If
oracledb.autoCommit
is true, andgetOne()
succeeds, then any open transaction on the connection is committed.Callback:
If you are using the callback programming style:
getOne(function(Error error, SodaDocument document){});
The parameters of the callback function
function(Error error, SodaDocument document)
are:Callback Function Parameter
Description
Error
error
If
getOne()
succeeds,error
is NULL. If an error occurs, thenerror
contains the error message.SodaDocument
document
One SodaDocument that matches the sodaOperation query criteria. If no document is found, then
document
will be undefined.
- sodaOperation.remove()
New in version 3.0.
Promise:
promise = remove();
Removes a set of documents matching the SodaOperation query criteria.
Note settings from
skip()
andlimit()
non-terminals are ignored because they only apply to read operations.If
oracledb.autoCommit
is true, andremove()
succeeds, then removal and any open transaction on the connection is committed.Callback:
If you are using the callback programming style:
remove(function(Error error, Object result){});
The parameters of the callback function
function(Error error, Object result)
are:Callback Function Parameter
Description
Error
error
If
remove()
succeeds,error
is NULL. If an error occurs, thenerror
contains the error message.Object
result
The result object contains one attribute:
result.count
The number of documents removed from the collection.
Due to Node.js type limitations, the largest
count
value will be 232 - 1, even if Oracle Database removed more rows. Larger values will wrap.
- sodaOperation.replaceOne()
New in version 3.0.
Promise:
promise = replaceOne(Object newDocumentContent); promise = replaceOne(SodaDocument newSodaDocument);
Replaces a document in a collection. The input document can be either a JavaScript object representing the data content, or it can be an existing SodaDocument.
The
mediaType
document component and content of the document that matches the SodaOperation query criteria will be replaced by the content and anymediaType
document component of the new document. Any other document components will not be affected. ThelastModified
andversion
document components of the replaced document will be updated.The
key()
non-terminal must be used when usingreplaceOne()
.No error is reported if the operation criteria do not match any document.
Note settings from
skip()
andlimit()
non-terminals are ignored because they only apply to read operations.If
oracledb.autoCommit
is true, andreplaceOne()
succeeds, then any open transaction on the connection is committed.The parameters of the
sodaOperation.replaceOne()
method are: Parameter
Data Type
Description
newDocumentContent
ornewSodaDocument
Object or SodaDocument
The new document. See
sodaCollection.insertOne()
, which has the same semantics for the document.Callback:
If you are using the callback programming style:
replaceOne(Object newDocumentContent, function(Error error, Object result){}); replaceOne(SodaDocument newSodaDocument, function(Error error, Object result){});
See sodaOperation.replaceOne() Parameters for information on the parameters.
The parameters of the callback function
function(Error error, Object result)
are:Callback Function Parameter
Description
Error
error
If
replaceOne()
succeeds,error
is NULL. It is not an error if no document is replaced. If an error occurs, thenerror
contains the error message.Object
result
The result object contains one attribute:
result.replaced
This attribute will be true if the document was successfully replaced, false otherwise.
- sodaOperation.replaceOneAndGet()
New in version 3.0.
Promise:
promise = replaceOneAndGet(Object newDocumentContent); promise = replaceOneAndGet(SodaDocument newSodaDocument);
Replaces a document in a collection similar to
sodaOperation.replaceOne()
, but also returns the result document which contains all SodaDocument components (key, version, etc.) except for content. Content itself is not returned for performance reasons. The result document has new values for components that are updated as part of the replace operation (such as version, last-modified timestamp, and media type)If
oracledb.autoCommit
is true, andreplaceOneAndGet()
succeeds, then any open transaction on the connection is committed.The parameters of the
sodaOperation.replaceOneAndGet()
method are: Parameter
Data Type
Description
newDocumentContent
ornewSodaDocument
Object or SodaDocument
The new document. See
sodaCollection.insertOne()
, which has the same semantics for the document.Callback:
If you are using the callback programming style:
replaceOneAndGet(Object newDocumentContent, function(Error error, SodaDocument updatedDocument){}); replaceOneAndGet(SodaDocument newSodaDocument, function(Error error, SodaDocument updatedDocument){});
See sodaOperation.replaceOneAndGet() Parameters for information on the parameters.
The parameters of the callback function
function(Error error, SodaDocument updatedDocument)
are:Callback Function Parameter
Description
Error
error
If
replaceOneAndGet()
succeeds,error
is NULL. It is not an error if no document is replaced. If an error occurs, thenerror
contains the error message.SodaDocument
updatedDocument
The updated SodaDocument if replacement was successful, otherwise
updatedDocument
will be undefined.The
lastModified
andversion
attributes of the stored SodaDocument will be updated. ThemediaType
attribute and the content will be replaced. Other attributes ofnewSodaDocument
are ignored.Note for performance reasons,
updatedDocument
will not have document content and cannot itself be passed directly to SODA insert or replace methods.
- sodaCollection.getDataGuide()
New in version 3.0.
Promise:
promise = getDataGuide();
Infers the schema of a collection of JSON documents at the current time. A JSON data guide shows details like the JSON property names, data types and lengths. It is useful for exploring the schema of a collection. The data guide is represented as JSON content in a SodaDocument.
This method is supported for JSON-only collections which have a
JSON Search index
where the “dataguide” option is “on”. An error will be returned if a data guide cannot be created.A data guide is a best effort heuristic and should not be used as a schema to validate new JSON documents. The data guide is always additive, and does not update itself when documents are deleted. There are some limits such as the maximum number of children under one node, and the maximum length of a path.
If
oracledb.autoCommit
is true, andgetDataGuide()
succeeds, then any open user transaction is committed.Callback:
If you are using the callback programming style:
getDataGuide(function(Error error, SodaDocument document){});
The parameters of the callback function
function(Error error, SodaDocument document)
are:Callback Function Parameter
Description
Error
error
If
getDataGuide()
succeeds,error
is NULL. It is not an error if no document is replaced. If an error occurs, thenerror
contains the error message.SodaDocument
document
The SodaDocument containing JSON content which can be accessed from the document as normal with
sodaDocument.getContents()
,sodaDocument.getContentAsString()
, orsodaDocument.getContentAsBuffer()
.
- sodaCollection.insertMany()
New in version 4.0.
Promise:
promise = insertMany(Array newDocumentContentArray); promise = insertMany(Array newSodaDocumentArray);
This is similar to
insertOne()
however it accepts an array of the Objects or SodaDocuments thatinsertOne()
accepts. When inserting multiple documents, usinginsertMany()
is recommended in preference toinsertOne()
.If an error occurs, the offset attribute on the Error objects will contain the number of documents that were successfully inserted. Subsequent documents in the input array will not be inserted.
This method is in Preview status and should not be used in production.
It requires Oracle Client 18.5 or higher.
Callback:
If you are using the callback programming style:
insertMany(Array newDocumentContentArray, function(Error error){}); insertMany(Array newSodaDocumentArray, function(Error error){});
- sodaCollection.insertManyAndGet()
New in version 4.0.
Promise:
promise = insertManyAndGet(Array newDocumentContentArray [, Object options ]); promise = insertManyAndGet(Array newSodaDocumentArray [, Object options ]);
Similar to
sodaCollection.insertMany()
but also returns an array of the inserted documents so system managed properties, such as the keys (in default collections), can be found. Content itself is not returned for performance reasons. When inserting multiple documents, usinginsertManyAndGet()
is recommended in preference toinsertOneAndGet()
.The
options
object can have one string propertyhint
. Hints are strings without SQL comment characters, for example{ hint: "MONITOR" }
. Use only the hint"MONITOR"
(turn on monitoring) or"NO_MONITOR"
(turn off monitoring). See the Oracle Database SQL Tuning Guide documentation MONITOR and NO_MONITOR Hints and Monitoring Database Operations for more information.This method is in Preview status and should not be used in production.
It requires Oracle Client 18.5 or higher. Use of the
hint
property requires Oracle Client 21.3 or higher (or Oracle Client 19 from 19.11).This method accepts an options parameter from node-oracledb 5.2 onwards.
Callback:
If you are using the callback programming style:
insertManyAndGet(Array newDocumentContentArray [, Object options ], function(Error error, Array SodaDocuments){}); insertManyAndGet(Array newSodaDocumentArray [, Object options ], function(Error error, Array SodaDocuments){});
- sodaCollection.insertOne()
New in version 3.0.
Promise:
promise = insertOne(Object newDocumentContent); promise = insertOne(SodaDocument newSodaDocument);
Inserts a given document to the collection. The input document can be either a JavaScript object representing the data content, or it can be an existing SodaDocument.
If
oracledb.autoCommit
is true, andinsertOne()
succeeds, then the new document and any open transaction on the connection is committed.The following examples are equivalent:
newDocumentContent = {name: "Alison"}; await sodaCollection.insertOne(newDocumentContent);
and:
newDocumentContent = {name: "Alison"}; doc = sodaDatabase.createDocument(newDocumentContent); await sodaCollection.insertOne(doc);
The parameters of the
sodaCollection.insertOne()
method are: Parameter
Data Type
Description
newDocumentContent
ornewSodaDocument
Object or SodaDocument
The document to insert.
Passed as a simple JavaScript object, the value is interpreted as JSON document content. Other document components (key, version, etc.) will be auto-generated by SODA during insert. The media type will be set to “application/json”.
Alternatively, a SodaDocument can be passed. The
content
andmediaType
supplied in the SodaDocument will be used. Thekey
, if set, will also be used if collection has client-assigned keys. Other components in the input SodaDocument, such as version and last-modified, will be ignored and auto-generated values will be used instead.Callback:
If you are using the callback programming style:
insertOne(Object newDocumentContent, function(Error error){}); insertOne(SodaDocument newSodaDocument, function(Error error){});
See sodaCollection.insertOne() Parameters for information on the
newDocumentContent
orSodaDocument
parameters.The parameters of the callback function
function(Error error)
are:Callback Function Parameter
Description
Error
error
If
insertOne()
succeeds,error
is NULL. If an error occurs, thenerror
contains the error message.
- sodaCollection.insertOneAndGet()
New in version 3.0.
Promise:
promise = insertOneAndGet(Object newDocumentContent [, Object options ]); promise = insertOneAndGet(SodaDocument newSodaDocument [, Object options ]);
Inserts a document in a collection similar to
sodaCollection.insertOne()
, but also returns the result document which contains all SodaDocument components (key, version, etc.) except for content. Content itself is not returned for performance reasons.If you want to insert the document again, use the original
newDocumentContent
ornewSodaDocument
. Alternatively construct a new object from the returned document and add content.The
options
object can have one string propertyhint
. Hints are strings without SQL comment characters, for example{ hint: "MONITOR" }
. Use only the hint"MONITOR"
(turn on monitoring) or"NO_MONITOR"
(turn off monitoring). See the Oracle Database SQL Tuning Guide documentation MONITOR and NO_MONITOR Hints and Monitoring Database Operations for more information.If
oracledb.autoCommit
is true, andinsertOneAndGet()
succeeds, then any open transaction on the connection is committed.This method accepts an options parameter from node-oracledb 5.2 onwards. Use of the
hint
property requires Oracle Client 21.3 or higher (or Oracle Client 19 from 19.11).The parameters of the
sodaCollection.insertOneAndGet()
method are: Parameter
Data Type
Description
newDocumentContent
ornewSodaDocument
Object or SodaDocument
The document to insert. For related documentation, see
sodaCollection.insertOne()
.Callback:
If you are using the callback programming style:
insertOneAndGet(Object newDocumentContent [, Object options ], function(Error error, SodaDocument document){}); insertOneAndGet(SodaDocument newSodaDocument [, Object options ], function(Error error, SodaDocument document){});
See sodaCollection.insertOneAndGet() Parameters for information on the
newDocumentContent
ornewSodaDocument
parameter.The parameters of the callback function
function(Error error, SodaDocument document)
are:Callback Function Parameter
Description
Error
error
If
insertOne()
succeeds,error
is NULL. If an error occurs, thenerror
contains the error message.SodaDocument
document
A result SodaDocument that is useful for finding the system generated key and other metadata of the newly inserted document.
Note for performance reasons,
document
will not have document content and cannot itself be passed directly to SODA insert or replace methods.
- sodaCollection.save()
New in version 5.0.
Promise:
promise = save(SodaDocument newSodaDocument);
This method behaves like
sodaCollection.insertOne()
with the exception that if a document with the same key already exists, then it is updated instead.The collection must use client-assigned keys keys, which is why
save()
accepts only a SodaDocument, unlikeinsertOne()
. If the collection is not configured with client-assigned keys, then the behavior is exactly the same assodaCollection.insertOne()
.It requires Oracle Client 19.9 or later, and Oracle Database 18.3 or later.
Callback:
If you are using the callback programming style:
save(SodaDocument newSodaDocument, function(Error error){});
- sodaCollection.saveAndGet()
New in version 5.0.
Promise:
promise = saveAndGet(SodaDocument newSodaDocument [, Object options ]);
This method behaves like
sodaCollection.insertOneAndGet()
with the exception that if a document with the same key already exists, then it is updated instead.The collection must use client-assigned keys keys, which is why
saveAndGet()
accepts only a SodaDocument, unlikeinsertOneAndGet()
. If the collection is not configured with client-assigned keys, then the behavior is exactly the same assodaCollection.insertOneAndGet()
.The
options
object can have one string propertyhint
. Hints are strings without SQL comment characters, for example{ hint: "MONITOR" }
. Use only the hint"MONITOR"
(turn on monitoring) or"NO_MONITOR"
(turn off monitoring). See the Oracle Database SQL Tuning Guide documentation MONITOR and NO_MONITOR Hints and Monitoring Database Operations for more information.It requires Oracle Client 19.9 or later, and Oracle Database 18.3 or later. Use of the
hint
property requires Oracle Client 21.3 or higher (or Oracle Client 19 from 19.11).This method accepts an options parameter from node-oracledb 5.2 onwards.
Callback:
If you are using the callback programming style:
saveAndGet(SodaDocument newSodaDocument [, Object options ], function(Error error, SodaDocument document){});
- sodaCollection.truncate()
New in version 5.0.
Promise
promise = truncate();
Truncates a collection, removing all documents. The collection will not be deleted.
It requires Oracle Client 20 or later, and Oracle Database 18.3 or later.
Callback:
If you are using the callback programming style:
truncate(function(Error error) {});
The parameters of the callback function
function(Error error)
are:Callback Function Parameter
Description
Error
error
If
truncate()
succeeds,error
is NULL. If an error occurs, thenerror
contains the error message.