11. API: SodaDatabase Class
The SodaDatabase class is the top level object for node-oracledb SODA operations. A ‘SODA database’ is an abstraction, allowing access to SODA collections in that ‘SODA database’, which then allow access to documents in those collections.
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.
A SODA database is equivalent to an Oracle Database user, see Overview of SODA in the Introduction to SODA manual.
A SODA database object is created by calling
connection.getSodaDatabase()
.
See Simple Oracle Document Access (SODA) for more information.
11.1. SodaDatabase Methods
- sodaDatabase.createCollection()
Added in version 3.0.
Promise:
promise = createCollection(String collectionName [, Object options]);
Creates a SODA collection of the given name. If you try to create a collection, and a collection with the same name already exists, then that existing collection is opened without error.
Optional metadata allows collection customization. If metadata is not supplied, a default collection will be created.
By default,
createCollection()
first attempts to create the Oracle Database table used internally to store the collection. If the table exists already, it will attempt to use it as the table underlying the collection. Most users will use this default behavior.If the optional
mode
parameter is oracledb.SODA_COLL_MAP_MODE, SODA will attempt to use a pre-existing table as the table underlying the collection.If
oracledb.autoCommit
is true, andcreateCollection()
succeeds, then any open transaction on the connection is committed. Note SODA operations do not commit an open transaction the way that SQL always does for DDL statements.Performance of repeated
createCollection()
calls can be improved by enabling the SODA metadata cache.The parameters of the
sodaDatabase.createCollection()
method are: Parameter
Data Type
Description
collectionName
String
The name of the collection to be created.
options
Object
The options that specify the collection. See createCollection(): options Parameter Properties for information on the properties that can be set.
The following properties can be set for the
options
parameter. Property
Data Type
Description
metaData
Object
Metadata specifying various details about the collection, such as its database storage, whether it should track version and time stamp document components, how such components are generated, and what document types are.
If undefined or null, then a default collection metadata description will be used. The default metadata specifies that the collection contains only JSON documents, and is recommend for most SODA users.
For more discussion see SODA Client-Assigned Keys and Collection Metadata. Also see SODA Collection Metadata Components.
mode
Number
If
mode
is oracledb.SODA_COLL_MAP_MODE, the collection will be stored in an externally, previously created table. A futuresodaCollection.drop()
will not drop the collection table. It will simply unmap it, making it inaccessible to SODA operations.Most users will leave
mode
undefined.Callback:
If you are using the callback programming style:
createCollection(String collectionName [, Object options], function(Error error, SodaCollection collection){});
See sodaDatabase.createCollection() Parameters for information on the
collectionName
andoptions
parameters.The parameters of the callback function
function(Error error, SodaCollection collection)
are:Callback Function Parameter
Description
Error
error
If
createCollection()
succeeds,error
is NULL. If an error occurs, thenerror
contains the error message.SodaCollection
collection
The SodaCollection containing zero or more SODA documents, depending whether it is a new or existing collection.
- sodaDatabase.createDocument()
Added in version 3.0.
sodaDatabase.createDocument(String content [, Object options]) sodaDatabase.createDocument(Buffer content [, Object options]) sodaDatabase.createDocument(Object content [, Object options])
A synchronous method that constructs a proto SodaDocument object usable for SODA insert and replace methods. SodaDocument attributes like
createdOn
will not be defined, and neither will attributes valid inoptions
but not specified. The document will not be stored in the database until an insert or replace method is called.You only need to call
createDocument()
if your collection requires client-assigned keys or has non-JSON content, otherwise you can pass your JSON content directly to the SODA insert and replace methods.Example
myDoc = soda.createDocument({name: "Chris", city: "Melbourne"}, {key: "123"}); // assuming client-assigned keys newDoc = await collection.insertOneAndGet(myDoc); console.log("The key of the new document is: ", newDoc.key); // 123
The parameters of the
sodaDatabase.createDocument()
method are: Parameter
Data Type
Description
content
String, Buffer, or Object
The document content.
When a Buffer is used, and if the collection
mediaType
is (or will be) ‘application/json’ (which is the default media type), then the JSON must be encoded in UTF-8, UTF-16LE or UTF-16BE otherwise you will get a SODA error on a subsequent write operation.options
Object
See createDocument(): options Parameter Properties for information on the properties that can be set.
The following properties can be set for the
options
parameter. Property
Data Type
Description
key
String
Must be supplied if the document in intended to be inserted into a collection with client-assigned keys. It should be undefined, otherwise.
mediaType
String
If the document has non-JSON content, then
mediaType
should be set to the desired media type. Using a MIME type is recommended.The default is ‘application/json’.
- sodaDatabase.getCollectionNames()
Added in version 3.0.
Promise:
promise = getCollectionNames([Object options]);
Gets an array of collection names in alphabetical order.
If
oracledb.autoCommit
is true, andgetCollectionNames()
succeeds, then any open transaction on the connection is committed.The parameters of the
sodaDatabase.getCollectionNames()
method are: Parameter
Data Type
Description
options
Object
If
options
is undefined, then all collection names will be returned. Otherwise, it can have the attributes listed in getcollectionnames(): options Parameter Attributes. Attribute
Data Type
Description
limit
Number
Limits the number of names returned. If limit is 0 or undefined, then all collection names are returned.
startsWith
String
Returns names that start with the given string, and all subsequent names, in alphabetic order.
For example, if collections with names “cat”, “dog”, and “zebra” exist, then using
startsWith
of “d” will return “dog” and “zebra”. IfstartsWith
is an empty string or undefined, all collection names are returned, subject to the value oflimit
.Callback:
If you are using the callback programming style:
getCollectionNames([Object options,] function(Error error, Array collectionNames){});
See sodaDatabase.getCollectionNames() Parameters for information on the
options
parameter.The parameters of the callback function
function(Error error, Array collectionNames)
are:Callback Function Parameter
Description
Error
error
If
getCollectionNames()
succeeds,error
is NULL. If an error occurs, thenerror
contains the error message.Array
collectionNames
An array of Strings, each containing the name of a SODA collection in this SODA database. The array is in alphabetical order.
- sodaDatabase.openCollection()
Added in version 3.0.
Promise:
promise = openCollection(String collectionName);
Opens an existing SodaCollection of the given name. The collection can then be used to access documents.
If the requested collection does not exist, it is not an error. Instead, the returned collection value will be undefined.
If
oracledb.autoCommit
is true, andopenCollection()
succeeds, then any open transaction on the connection is committed.Performance of repeated
openCollection()
calls can be improved by enabling the SODA metadata cache.The parameters of the
sodaDatabase.openCollection()
method are: Parameter
Data Type
Description
collectionName
String
The name of the collection to open.
Callback:
If you are using the callback programming style:
openCollection(String collectionName, function(Error error, SodaCollection collection){});
See sodaDatabase.openCollection() Parameters for information on the
collectionName
parameter.The parameters of the callback function
function(Error error, SodaCollection collection)
are:Callback Function Parameter
Description
Error
error
If
openCollection()
succeeds,error
is NULL. It is not an error if the requested collection does not exist. If an error occurs, thenerror
contains the error message.SodaCollection
collection
The requested collection, if one is found. Otherwise it will be undefined.