Document Operations

17 Document Operations

Oracle Backend for Firebase provides a unified document-centric interface for interacting with both relational and document-based data. This section introduces the conceptual foundation for document operations, focusing on how developers can model, write, and read data using Oracle Backend for Firebase.

Document operations in Oracle Backend for Firebase refer to the lifecycle actions developers perform on JSON-based documents stored within collections. These operations include creating, updating, reading, and deleting documents, along with applying field-level modifiers and managing metadata. Oracle Backend for Firebase supports both document and relational models, and these operations apply primarily to the document model.

Information in this section is intended to help developers understand the underlying principles before diving into SDK-specific implementations.

Parent topic: Database

17.1 Prerequisites

Before performing any document read or write operations, ensure the following:

Project Initialization: The Oracle Backend for Firebase project must be created and configured using the Console.
Authentication Setup: The application must be initialized using initializeApp() or equivalent. A valid Auth token must be included in all requests.
Database Configuration:
- For collection model: The collection must be created and indexed if filters are used.
- For relational model: The relational table must be mapped and duality views configured.
Security Rules: Appropriate rules must be published for the target path to allow get, list, create, update, or delete operations.
SDK Installation: The relevant SDK (JS, Android, iOS) must be installed and configured with the correct config.json.
Permissions:
- Write operations require create, update, or delete access.
- Read operations require get or list access.
Indexing:
- Check if a functional index is required
- Compound queries or ordering require indexes to be defined in the Console UI.
Collection Path: Identify the correct collection path where the document will be added.

Parent topic: Document Operations

17.2 Write Operations

Write operations in Oracle Backend for Firebase allow developers to create, update, and delete documents within collections. These operations are designed to support both full document replacements and granular field-level updates.

Parent topic: Document Operations

17.2.1 Supported Document Operations

Developers can perform the following operations on documents. Each of these operations can be invoked using REST or SDK interfaces.

Table 17-1 Write Operations

Operation	Method	Description
Set a Document	`setDoc(path, data, options)`	Create or overwrite a document at the specified path; can also merge document data. If the collection does not exist, it is created automatically.
Add a Document	`addDoc(path, data)`	Inserts a new JSON document into a specified collection or sub-collection with an auto-generated unique identifier (OID).
Update Document	`updateDoc()`	Updates specific fields in an existing document using its OID.
Delete Document	`deleteDoc()`	Removes a document from the collection.

Note:

For multi-step writes, use batch writes (all-or-nothing) or transactions (read + write atomically).

SDK Usage

JavaScript (Modular)
JavaScript (Namespace)
Flutter (Dart)
Java (Android)
Swift (iOS)

Parent topic: Write Operations

17.2.1.1 Set a Document

The setDoc() operation is used to create or overwrite a document at a specified path. Unlike addDoc(), which generates an auto-ID, setDoc() requires you to specify the document path within a collection and provide the document data.

If the document being created already exists, it can be overwritten entirely or updated partially using one of these merge options:

Overwrite Document (merge = false): Overwrite to replace the entire document with the provided data, which implies that all fields are replaced. This option should be used if you want to replace the complete document or when you are not sure if the document exists.
Merge Document (merge = true): Updates only the specified fields, preserving exisitng data of the document.

If the document does not exist, it will be created at the given path. If the collection does not already exist, this operation implicitly creates the collection. The field methods listed in Field-Level Semantics and Data Types can be applied. Relational Model updates operate on duality views created from relational tables.

Merging allows developers to update specific fields within a document without replacing the entire content. This is useful for incremental updates, such as modifying a title or adding new tags.

By default, when you call setDoc() without specifying merge options, the entire document is overwritten with the new data you provide.

Setting a Document Using the Console

Navigate to the Database section in the Console.
Select the Collection where you want the document.
Choose Add Document but manually specify the document ID (For example, Scott, Cookies).

Note:

When you set a document you control the document ID. The Console requires you to type it in.
Enter field values in the document editor.
Optionally, enable merge mode (if supported in the Console UI) to update only specific fields.
Save, and the document is created or overwritten at that exact path.

Example: Set a Document with Merge Options

Parent topic: Supported Document Operations

17.2.1.1.1 Example: Set a Document with Merge Options

Merge and MergeFields options are supported in Oracle Backend for Firebase to allow fine-grained control over document updates.

Overwrite Document (merge = false)

Setting a document with merge = false (which is the default) replaces the entire document with the provided data. Use this when you want to ensure the document is fully reset or when you are not sure if it exists.

{
  "displayName": "Scott",
  "photoURL": null
}

Merge Document (merge = true)

This option tells the system to merge the incoming fields with the existing document rather than replacing the entire document. Therefore, this operation adds new fields or updates specified existing fields. Other fields remain untouched. This option is useful for incremental updates without overwriting the entire document.

The following is an example input:

{
  "title": "Rich Chocolate Chip Cookies",
  "ingredients": "2 cups flour,1 cup sugar,2 cup chocolate chips"
}

The following is the resulting document, after it is merged into the existing document:

{
  "uuid": "Scott",
  "title": "Rich Chocolate Chip Cookies",
  "ingredients": "2 cups flour,1 cup sugar,2 cup chocolate chips",
  "avgRating": 0,
  "tags": ["sweet", "baking"]
}

Example 17-1 merge: true

The following updates only views and notes fields, leaving other fields untouched.

{
  "title": "Chocolate Chip Cookies",
  "ingredients": "2 cups flour,1 cup sugar,2 cups chocolate chips",
  "tags": { "arrayUnion": ["dessert"] },
  "createdAt": "serverTimestamp",
  "updatedAt": "serverTimestamp",
  "views": { "increment": 1 },
  "notes": "deleteField"
}

The following is the resulting document:

{
  "title": "Chocolate Chip Cookies",
  "ingredients": "2 cups flour,1 cup sugar,2 cups chocolate chips",
  "tags": ["sweet", "baking", "dessert"],
  "createdAt": "2025-12-22T12:53:00Z",
  "updatedAt": "2025-12-22T12:53:00Z",
  "views": 101,   // incremented from 100
  // "notes" field removed
}

mergeFields: ["field1", "field2"]

This option is more selective because it allows you to merge only specific fields from the payload, ignoring others even if they are present. This is different from a full merge (merge = true), which merges all provided fields. With merge fields, you can explicitly list which fields should be merged.

Only the fields listed in mergeFields are updated.
Other fields in the data payload are ignored.
Useful for partial updates when you want to avoid accidental overwrites.

Example 17-2 mergeFields: ["field1", "field2"]

Only field1 and field2 are updated. field3 is ignored even though it is present in the payload.

Suppose that the target document path is /users/Scott/recipes/Cookies and the content to be updated is:

{
  "title": "Rich Chocolate Chip Cookies",
  "ingredients": "2 cups flour,1 cup sugar,2 cup chocolate chips",
  "avgRating": 5
}

Suppose that the following merge fields option are used:

{
  "mergeFields": ["title", "ingredients"]
}

After applying the merge with mergeFields, the resulting document is as follows:

{
  "uuid": "Scott",
  "title": "Rich Chocolate Chip Cookies",
  "ingredients": "2 cups flour,1 cup sugar,2 cup chocolate chips",
  "avgRating": 0,              // unchanged because not listed in mergeFields
  "tags": ["sweet", "baking"]  // untouched
}

Parent topic: Set a Document

17.2.1.2 Add a Document

This operation adds a new document to a collection or a relational model with an auto-generated identifier. It is typically used when the document ID is not predetermined and allows for rapid creation of new entries. This operation is distinct from setDoc() (which overwrites or merges existing documents) because addDoc() always generates a new document with a system‑assigned identifier.

The add data operation is supported in both collection model (JSON) and relational model (duality view). When invoked:

A new document is created inside the specified collection.
If the collection does not exist, Oracle Backend for Firebase automatically creates it.
In relational setups, a hybrid collection is created as an extension to the relational table.

The modifier serverTimestamp stores the current server time, which is useful for createdAt fields.

Adding Data Using the Console

Developers can add data directly through the Console without writing SDK code.

Navigate to the Database section of your project.
Select the mapped relational table or document collection.

For relational tables, ensure relational tables are mapped in the Console. Oracle Backend for Firebase automatically creates duality views for each mapping.

For document collection, select the target collection path: users/{userid}/recipes/{recipeId}/notes.
Click Add Document.
Enter the JSON structure above into the document editor.
Save the document.
- The system generates a unique ID for the new note.
- Metadata (OID, parent_oid, _metadata) is automatically generated.
- The createdAt field is automatically populated with the server time.

Example: Adding Data in Document Model

When adding a new document into a subcollection (for example, notes under a recipe), the structure of the data can be represented as follows:

{
  "uuid": "Scott",
  "content": {
    "step1": "Try adding a pinch of sea salt for balance.",
    "step2": "Add extra chocolate chips"
  },
  "createdAt": "serverTimestamp"
}

uuid: Identifies the owner of the document (in this case "Scott").
content: Nested object containing the note details. Each step is stored as a key‑value pair.
createdAt: Uses the serverTimestamp attribute to automatically store the current server time when the document is created.

Adding Data in Relational Model

When using Oracle Backend for Firebase with relational tables, adding data creates a hybrid collection that extends the relational schema. Each relational table is converted into a duality view with metadata fields such as oid and parent_oid.

A new document added to such a hybrid collection can be represented in JSON as follows:

{
  "osons": {
    "name": "Scott",
    "age": 30,
    "about": "Application developer working with Oracle Backend for Firebase",
    "OID": "FB03C10200",
    "_id": 1,
    "parent_oid": "_docId",
    "_metadata": {
      "etag": "943EEC508908213D2D00FF375854BB48",
      "asof": "00000000000001234"
    }
  }
}

name / age / about: Standard relational fields mapped into the hybrid collection.
OID: Unique identifier for the document within the duality view.
_id: Internal system‑generated ID.
parent_oid: Reference to the parent document in the hierarchy.
_metadata: Contains system metadata such as etag (for versioning) and asof (snapshot reference).

Parent topic: Supported Document Operations

17.2.1.3 Update a Document

Updating a document allows you to change only specific fields in an existing document. Unlike setDoc(), which overwrites or merges entire documents, the update operation is designed for partial modifications.

If the document does not already exist, the update operation fails. This ensures that updates are only applied to valid, existing records. Also, the update operation supports bulk updates using the filter clause, which iterate through each document that is part of the clause and updates the documents. In case of security issue with any of the document, the complete operation is rolled back.

When updating, the field methods listed in Field-Level Semantics and Data Types can be applied. Relational Model updates operate on duality views created from relational tables.

Updating a Document Using the Console

Navigate to the Database section in the Console.
Select the collection or relational duality view where you want to update the document.

Example path: /users/{userid}/recipes/{recipeid}/notes/{noteid}
Click the document ID to open its details.
Enter field values in the document editor.
Complete the following tasks:
- In the document editor, specify the fields to be updated.
- Use dot notation for nested fields (for example, content.step2).
- Example update content:
```
{
  "content.step2": "Add a handful of chopped nuts instead of chocolate chips",
  "content.step3": "Add some coffee as well"
}
```
Choose Update Document from the available actions and confirm the operation.

Example: Updating data in Document Model

In the earlier example for adding data, suppose you want to:

Modify step2 to suggest adding nuts instead of extra chocolate chips.
Add a new step3 with an additional instruction.

The update request would look like this:

{
  "content.step2": "Add a handful of chopped nuts instead of chocolate chips",
  "content.step3": "Add some coffee as well"
}

After the update, the document will contain:

{
  "uuid": "Scott",
  "content": {
    "step1": "Try adding a pinch of sea salt for balance.",
    "step2": "Add a handful of chopped nuts instead of chocolate chips",
    "step3": "Add some coffee as well"
  },
  "createdAt": "serverTimestamp"
}

Example: Updating Data in Relational Model

In the earlier example for adding data, suppose you want to:

Change the age field from 30 to 31.
Update the about field with new information.

The update request would look like:

{
  "age": 31,
  "about": "Updated profile information"
}

After the update, the duality view reflects the following:

{
  "osons": {
    "name": "Scott",
    "age": 31,
    "about": "Updated profile information",
    "OID": "FB03C10200",
    "_id": 1,
    "parent_oid": "_docId",
    "_metadata": {
      "etag": "NEW_ETAG_VALUE",
      "asof": "NEW_ASOF_VALUE"
    }
  }
}

Metadata (etag, asof) is automatically updated to reflect the new version.

Parent topic: Supported Document Operations

17.2.1.4 Delete a Document

The delete operation removes an entire document from a collection or relational duality view.

When a document is deleted, all of its fields are removed.
Important: Subcollections are not automatically deleted. They remain in the database unless explicitly removed.

Caution:

This operation is irreversible and should be used with caution, especially in production environments.

Deleting Data Using the Console

Navigate to the Database section of your project.
Use the project hierarchy to browse to the correct collection or relational duality view.

For document collection, select the target collection path: /users/{userid}/recipes/{recipeid}/notes/{noteid}.
Search or filter to find the document you want to delete and click the document ID to open its details.
Click Delete Document.
Confirm the deletion when prompted.

Example: Deleting a Document

Suppose that the target document path: /users/Scott/recipes/Cookies/notes/note1 and the delete request is:

{
  "operation": "deleteDoc",
  "path": "/users/Scott/recipes/Cookies/notes/note1"
}

The document note1 is removed from the notes subcollection. Any subcollections under note1 (For example, attachments, comments) remain unless explicitly deleted.

Parent topic: Supported Document Operations

17.2.2 Field-Level Semantics and Data Types

Oracle Backend for Firebase supports advanced field-level operations using built-in field modifiers that enhance document write operations. These modifiers are applied to manage dynamic data during document creation or update (set and update operations):

serverTimestamp: Stores the current server time (not client time), typically used for createdAt and updatedAt fields.
increment: Atomically increases or decreases (if in negative) a numeric field.
arrayUnion (values): Adds values to an array only if they do not already exist.
arrayRemove (values): Removes specified matching values or elements from an array.
deleteField: Deletes a field from a document.

These operations allow developers to perform complex updates without needing to read and rewrite entire documents.

serverTimestamp

Stores the current server time in the field.
Useful for tracking creation and update times consistently across distributed clients.