Firestore Adapter Integration Documentation

Overview

The firestore.adapter is an integration component designed to facilitate interactions with Google Cloud Firestore. This adapter allows users to execute read and write operations on Firestore collections seamlessly within the Vantage analytics and data platform. It provides essential features such as schema introspection, real-time read and write capabilities, and the ability to manage collections effectively.

Settings

The firestore.adapter contains several configuration settings that dictate its behavior. Below are the detailed explanations for each setting:

1. databaseName

• Input Type: String
• Description: The project ID of the Google Cloud Firestore database to which the adapter will connect. This ID is crucial as it identifies the database within Google Cloud.
• Default Value: None (must be provided).

2. keyFilePath

• Input Type: String
• Description: The file path to the service account key file in JSON format, which contains the necessary credentials to authenticate access to Firestore. This file should be securely managed to prevent unauthorized access.
• Default Value: None (must be provided).

3. operation

• Input Type: String
• Description: Specifies the type of write operation to perform, including options such as 'add', 'set', 'update', 'delete', and 'batchWrite'. Changing this value determines the action executed on the Firestore collection.
• Default Value: None (must be provided based on the use-case).

4. collection

• Input Type: String
• Description: The name of the Firestore collection where the operations will be executed. This determines the target of the read/write queries.
• Default Value: None (must be provided).

5. documentId

• Input Type: String
• Description: The unique document ID within the specified collection. Relevant for operations targeting specific documents such as 'read', 'set', 'update', and 'delete'.
• Default Value: None (optional based on the operation).

6. data

• Input Type: Object
• Description: Contains the data to be written to the specified document during 'add', 'set', or 'update' operations. The contents of this object dictate what data is stored in Firestore.
• Default Value: None (must be provided for write operations).

7. merge

• Input Type: Boolean
• Description: When set to true, the data will be merged with the existing document instead of overwriting it entirely. This setting is particularly relevant for 'set' operations to maintain existing document data.
• Default Value: False.

8. filters

• Input Type: Array
• Description: An array of filter conditions applied to the collection during read operations. Each filter consists of an array containing the field, operator, and value to filter results.
• Default Value: Empty array.

9. orderBy

• Input Type: Object
• Description: An object specifying the field to order results by and the direction of sorting (ascending or descending). This influences how results are returned in collection queries.
• Default Value: Undefined.

10. limit

• Input Type: Numeric
• Description: Limits the number of documents returned during read operations. This is useful for pagination or reducing data transfer.
• Default Value: Undefined.

11. updates

• Input Type: Object
• Description: Defines the fields and values to be updated in the document. Similar to data, but specifically for updates and can include field value transforms.
• Default Value: Empty object.

12. documents

• Input Type: Array
• Description: For batch operations, this array contains objects that specify each document operation (set, update, delete, add) to be performed in a single API call.
• Default Value: Empty array.

How It Works

Upon initialization, the FirestoreAdapter connects to Firestore using the provided databaseName and keyFilePath. It then offers methods for testing the connection, listing collections, reading documents, writing data, and managing collections.

Connection Testing

The testConnection method verifies if the connection to Firestore is successful by attempting to list collections. On failure, it logs an error message.

Schema Introspection

The adapter supports schema introspection, allowing users to list collections through listCollections and to retrieve field names and types of a document using sampleDocument.

Read and Write Operations

• Read: The executeReadOnly method supports fetching either a specific document or a collection of documents based on specified filters, ordering, and limits.
• Write: The executeWrite method allows for various operations such as adding documents, setting data, updating existing fields, and executing batch writes.

Cleanup

The close method cleanly terminates the Firestore connection upon completion of operations, ensuring there are no dangling connections.

Use Cases & Examples

Use Case 1: Real-time Data Feeding

A company wants to feed real-time analytics data into their dashboard from user interactions stored in Firestore. The firestore.adapter can be configured to read user behavior data and update metrics in real-time for analysis.

Use Case 2: Data Synchronization

An application needs to synchronize user profiles between a Firestore database and local storage. This can be effectively managed through the executeReadOnly method to fetch user data while using executeWrite for updates.

Concrete Example

Scenario: Real-time Analytics Dashboard

Configuration Example:

{
  "databaseName": "analytics-project",
  "keyFilePath": "/path/to/service-account-key.json",
  "operation": "add",
  "collection": "user_interactions",
  "data": {
    "userId": "12345",
    "action": "click",
    "timestamp": {
      "_transform": "serverTimestamp"
    }
  }
}

Description: In this configuration, a new document representing a user interaction is being added to the user_interactions collection whenever a user clicks on the dashboard. The timestamp field will be populated with the server's current time at the moment of insertion, ensuring accurate recording of the interaction time.

AI Integrations and Billing Impacts

While the firestore.adapter itself does not directly integrate with AI features, data extracted from Firestore can be utilized in downstream AI applications for predictive analytics or machine learning model training.

As for billing, Firestore charges based on the number of reads, writes, and deletes performed. Therefore, understanding the usage of the firestore.adapter—such as frequent data writes or numerous read operations—can help in estimating costs associated with using Firestore through the Vantage platform.