Operations on Document Collections

Working with SODA document collections involves create-document, write, and read operations. A create-document operation creates a document object from content that you provide. A write operation, such as insert or replace, stores the document persistently in Oracle Database. A read operation, such as find, fetches the document from Oracle Database, and getter operations provide access to individual document components such as key and content.

The following example uses SODA for Java to illustrate basic operations - equivalent operations exist in all other SODA implementations. In this example, you:

• create a collection
• insert a document
• find the document by filter
• apply JSON Merge Patch to the document
• remove the document

// Open or create a collection
OracleCollection col = db.admin().createCollection("mycol");

// Insert a document
OracleDocument doc =
    db.createDocumentFromString("{\"name\":\"Alice\",\"status\":\"new\"}");
OracleDocument inserted = col.insertAndGet(doc);

// Find the document
OracleDocument found =
    col.find().filter("{\"name\" : \"Alice\"}").getOne();

// Apply JSON Merge Patch to the document
OracleDocument patch =
    db.createDocumentFromString("{\"status\":\"active\"}");
col.find().key(found.getKey()).mergeOne(patch);

// Remove the document
col.find().key(found.getKey()).remove();

The example illustrates the SODA operation builder pattern: find() returns a builder, and you chain further calls on it. Methods like filter() and key() specify which documents to target, while terminal methods like getOne(), mergeOne(), and remove() each define and execute a specific operation. All SODA implementations except REST use this same pattern.

Internally, SODA operations are translated into SQL. In the builder pattern, filter() and key() calls become WHERE clause conditions, and the terminal method determines and executes the final corresponding SQL statement - SELECT, UPDATE, DELETE, and so on.