Using SODA for In-Database JavaScript

How to access SODA for In-Database JavaScript is described, as well as how to use it to perform create, read (retrieve), update, and delete (CRUD) operations on collections.

This section describes SODA for MLE JavaScript. Code snippets in this section are sometimes abridged for readability. Care has been taken to ensure that JavaScript functions are listed in their entirety, but they aren’t runnable on their own. Embedding the function definition into a JavaScript module and importing the MLE JavaScript SQL driver will convert these code examples to valid JavaScript code for Oracle Database 23ai.

Topics

• Getting Started with SODA for In-Database JavaScript
  How to access SODA for In-Database JavaScript is described, as well as how to use it to create a database collection, insert a document into a collection, and retrieve a document from a collection.
• Creating a Document Collection with SODA for In-Database JavaScript
  How to use SODA for In-Database JavaScript to create a new document collection is explained.
• Opening an Existing Document Collection with SODA for In-Database JavaScript
  You can use the method SodaDatabase.openCollection() to open an existing document collection or to test whether a given name names an existing collection.
• Checking Whether a Given Collection Exists with SODA for In-Database JavaScript
  You can use SodaDatabase.openCollection() to check for the existence of a given collection. It returns null if the collection argument does not name an existing collection; otherwise, it opens the collection having that name.
• Discovering Existing Collections with SODA for In-Database JavaScript
  You can use SodaDatabase.getCollectionNames() to fetch the names of all existing collections for a given SodaDatabase object.
• Dropping a Document Collection with SODA for In-Database JavaScript
  You use SodaCollection.drop() to drop an existing collection.
• Creating Documents with SODA for In-Database JavaScript
  Creation of documents by SODA for In-Database JavaScript is described.
• Inserting Documents into Collections with SODA for In-Database JavaScript
  SodaCollection.insertOne() or a related call such as sodaCollection.insertOneAndGet() offers convenient ways to add documents to a collection. These methods create document keys automatically, unless the collection is configured with client-assigned keys and the input document provides the key, which is not recommended for most users.
• Saving Documents into Collections with SODA for In-Database JavaScript
  You use SodaCollection.save() and saveAndGet() to save documents into collections.
• SODA for In-Database JavaScript Read and Write Operations
  The primary way you specify read and write operations (other than insert and save) is to use methods provided by the SodaOperation class. You can chain together SodaOperation methods to specify read or write operations against a collection.
• Finding Documents in Collections with SODA for In-Database JavaScript
  To find documents in a collection, you invoke SodaCollection.find(). It creates and returns a SodaOperation object which is used via method chaining with nonterminal and terminal methods.
• Replacing Documents in a Collection with SODA for In-Database JavaScript
  To replace the content of one document in a collection with the content of another, you start by looking up the document to be modified using its key. Because SodaOperation.key() is a nonterminal operation, the easiest way to replace the contents is to chain SodaOperation.key() to SodaOperation.replaceOne() or SodaOperation.replaceOneAndGet().
• Removing Documents from a Collection with SODA for In-Database JavaScript
  Removing documents from a collection is similar to replacing. The first step is to perform a lookup operation, usually based on the document's key or by using a search expression in SodaOperation.filter(). The call to SodaOperation.remove() is a terminal operation, in other words the last operation in the chain.
• Indexing the Documents in a Collection with SODA for In-Database JavaScript
  Indexes can speed up data access, regardless of whether you use the NoSQL style SODA API or a relational approach. You index documents in a SODA collection using SodaCollection.createIndex(). Its IndexSpec parameter is a textual JSON index specification.
• Getting a Data Guide for a Collection with SODA for In-Database JavaScript
  A data guide is a summary of the structural and type information contained in a set of JSON documents. It records metadata about the fields used in those documents. They provide great insights into JSON documents and are invaluable for getting an overview of a data set.
• Handling Transactions with SODA for In-Database JavaScript
  Unlike the client-side JavaScript SQL driver, the MLE JavaScript SQL driver does not provide an autoCommit feature. You need to commit or roll your transactions back, either in the PL/SQL layer in case of module calls, or directly in the JavaScript code by calling connection.commit() or connection.rollback().
• Creating Call Specifications Involving the SODA API
  Earlier in this chapter, in the section Getting Started with SODA for In-Database JavaScript, an example showing how to invoke the MLE SODA API using an inline call specification is included. The following short example demonstrates how to use SODA in MLE modules.