Skip to content

Firestore

floci-gcp emulates Google Cloud Firestore over gRPC using the real google.firestore.v1 protocol.

Configuration

Variable Default Description
FLOCI_GCP_SERVICES_FIRESTORE_ENABLED true Enable/disable Firestore

Emulator Variable

export FIRESTORE_EMULATOR_HOST=localhost:4588

The GCP Firestore SDK uses this variable to route requests to floci-gcp instead of firestore.googleapis.com.

Quick Start

FirestoreOptions options = FirestoreOptions.newBuilder()
    .setHost("localhost:4588")
    .setProjectId("floci-local")
    .setCredentials(NoCredentials.getInstance())
    .build();

Firestore db = options.getService();

// Add a document
Map<String, Object> user = new HashMap<>();
user.put("name", "Alice");
user.put("age", 30);

db.collection("users").add(user).get();

// Query documents
ApiFuture<QuerySnapshot> future = db.collection("users")
    .whereEqualTo("name", "Alice")
    .get();

QuerySnapshot snapshot = future.get();
snapshot.getDocuments().forEach(doc ->
    System.out.println(doc.getData()));
import os
os.environ["FIRESTORE_EMULATOR_HOST"] = "localhost:4588"

from google.cloud import firestore

db = firestore.Client(project="floci-local")

# Add a document
db.collection("users").add({"name": "Alice", "age": 30})

# Query documents
docs = db.collection("users").where("name", "==", "Alice").stream()
for doc in docs:
    print(doc.to_dict())

# Set a document
db.collection("users").document("alice").set({"name": "Alice", "age": 30})

# Get a document
doc = db.collection("users").document("alice").get()
print(doc.to_dict())
process.env.FIRESTORE_EMULATOR_HOST = "localhost:4588";

import { Firestore } from "@google-cloud/firestore";

const db = new Firestore({ projectId: "floci-local" });

// Add a document
await db.collection("users").add({ name: "Alice", age: 30 });

// Query documents
const snapshot = await db.collection("users")
    .where("name", "==", "Alice")
    .get();
snapshot.forEach(doc => console.log(doc.data()));

// Set a document
await db.collection("users").doc("alice").set({ name: "Alice", age: 30 });
export FIRESTORE_EMULATOR_HOST=localhost:4588
gcloud config set project floci-local

# Firestore does not have gcloud CLI data commands.
# Use the SDK clients or the Firestore emulator UI instead.

Transactions

db.runTransaction(transaction -> {
    DocumentReference docRef = db.collection("counters").document("visits");
    DocumentSnapshot snapshot = transaction.get(docRef).get();

    long currentCount = snapshot.exists() ? snapshot.getLong("count") : 0;
    transaction.set(docRef, Map.of("count", currentCount + 1));
    return null;
}).get();

Transactions use optimistic concurrency, matching real Firestore: every document read inside a transaction is tracked, and the commit fails with ABORTED if any of those documents changed after being read. SDK clients retry aborted transactions automatically, so concurrent increments like the example above never lose updates.

Preconditions

Write preconditions (currentDocument) are enforced on all write paths:

  • create() fails with ALREADY_EXISTS if the document exists
  • update() fails with NOT_FOUND if the document does not exist
  • Precondition.updatedAt(...) fails with FAILED_PRECONDITION if the document's update time no longer matches

Commit is atomic: if any write's precondition fails, no writes in the request are applied. BatchWrite is non-atomic and reports a per-write status, matching real Firestore.

Batch Writes

WriteBatch batch = db.batch();

DocumentReference ref1 = db.collection("users").document("alice");
DocumentReference ref2 = db.collection("users").document("bob");

batch.set(ref1, Map.of("name", "Alice"));
batch.set(ref2, Map.of("name", "Bob"));

batch.commit().get();

Real-time Listeners

DocumentReference docRef = db.collection("users").document("alice");

ListenerRegistration registration = docRef.addSnapshotListener((snapshot, e) -> {
    if (snapshot != null && snapshot.exists()) {
        System.out.println("Current data: " + snapshot.getData());
    }
});

// Later: stop listening
registration.remove();

Supported Operations

  • GetDocument
  • CreateDocument
  • UpdateDocument
  • DeleteDocument
  • ListDocuments
  • BatchGetDocuments
  • BatchWrite
  • BeginTransaction
  • Commit
  • Rollback
  • RunQuery
  • RunAggregationQuery (COUNT with up_to, SUM, AVG)
  • PartitionQuery
  • Write (streaming)
  • Listen (real-time change streams: query and document targets, several per stream, remove_target)
  • ListCollectionIds

Deviations from real Firestore

  • Transaction conflict detection covers documents actually read. Queries inside a transaction track only the documents they return, so phantom reads (a concurrent write creating a document that would have matched the query) do not abort the transaction.
  • RunAggregationQuery ignores transaction and newTransaction; aggregations read outside the transaction and are not part of its read set.
  • RunAggregationQuery does not reject duplicate aliases, or a request with no aggregations or more than five, although the proto requires unique aliases and one to five aggregations.
  • Queries do not add the implicit trailing __name__ order, so documents with equal order_by values come back in storage order rather than by name.
  • Documents that lack an order_by field are not excluded from the results.
  • ListDocuments ignores order_by, page_size and page_token: it returns every document of the collection in one page, in storage order.
  • Transactions expire after 15 minutes instead of Firestore's shorter server-side deadlines.
  • Transaction state is held in memory; transactions do not survive an emulator restart. A commit against an unknown transaction id is applied without conflict validation.
  • Listen keeps no change history: a target added with a resume_token or read_time is sent a RESET and its full current state, as Google's Firestore emulator does, rather than only the changes since that point. Resume tokens are opaque and only round-trip.
  • Listen ignores once and expected_count, never sends an ExistenceFilter, and sends no periodic NO_CHANGE heartbeats: a snapshot follows only a write that changes a target's results.
  • Listen answers a duplicate or negative target_id, or a target with neither a query nor documents, with INVALID_ARGUMENT and ends the stream. Google's emulator also ends the stream; the status production returns was not verified.
  • Clearing all emulator state through the floci reset endpoint does not notify open Listen streams; the next write in a target's scope reports the documents that disappeared.