FirestoreAuthorCloudBrum editorial teamLast reviewed30 Oct 2026Reading time~12 minLevelBeginner to advanced

• Documents in collectionsA document holds fields such as strings, numbers, timestamps, maps and arrays, up to 1 MiB. Collections hold documents, and a document can have its own subcollections, so data can be nested to match how it is read.
• Queries that scale with the resultBecause every query is served from an index, how long it takes depends on how many documents it returns and not on how big the database has grown.
• Indexes, some of them yoursSingle-field indexes are created automatically. A query that combines fields, or filters and sorts on different fields, needs a composite index that you declare. Collection group queries search every collection with the same name.
• Realtime updatesA mobile or web client can attach a listener to a document or a query and receive the current result and then every change. The SDKs also cache data on the device, so an app keeps working offline and syncs later.
• Two ways to control accessSecurity Rules decide what a signed-in end user may read or write from a mobile or web client. Server code uses IAM roles instead, and server libraries don’t pass through the rules.
• Regional or multi-regionPick a regional location, such as Mumbai, or a multi-region one that survives the loss of a region. Reads are strongly consistent, and the location can’t be changed after the database is created.
• Recovery optionsPoint-in-time recovery lets you read or restore the data as it was at a minute in the last seven days. Scheduled backups, managed exports and delete protection cover the other ways to lose data.
• Two editionsStandard bills per document read, write and delete. Enterprise works with MongoDB drivers, allows larger documents, and bills in read units and write units by the number of bytes touched.

Document

A set of named fields, stored under an ID inside a collection. A Native mode document can be up to 1 MiB.

Collection and subcollection

A collection is a container of documents. A document can contain subcollections, which makes paths like customers/c-100/orders/o-0001. Deleting a document doesn’t delete its subcollections.

Reference

A field that points to another document by its path, a bit like a foreign key that the database doesn’t enforce.

Index

A sorted list that lets a query find its documents. Single-field indexes are automatic. A composite index covers several fields in a given order and must be created before the query that needs it.

Collection group query

A query over every collection with a given ID, wherever it sits in the hierarchy. It needs a collection group index.

Native mode and Datastore mode

Native mode has the realtime listeners and the mobile and web SDKs. Datastore mode keeps the older Datastore API for server-only applications.

Edition

Standard or Enterprise, chosen when the database is created. They differ in features, limits and how operations are billed.

Realtime listener

A long-lived connection that pushes a document or query result to the client when it first loads and whenever it changes.

Security Rules

Declarative rules, written in their own language, that decide what a mobile or web client may read or write. Server libraries are controlled by IAM instead.

Transaction

A group of reads and writes that succeeds as a whole. Reads come first, and the function may run again if another writer changed the same documents.

TTL policy

A setting on a timestamp field that tells Firestore to delete documents once that time has passed. Deletion usually follows within a day.

Point-in-time recovery (PITR)

Keeps seven days of document versions, so you can read the data at an earlier minute or restore it into a new database.

Aggregation query

A count, sum or average computed on the server over the index entries, instead of reading every document.

Create a database, an index and safe defaults with the gcloud CLI

1. Shape the data around the queriesList what the application asks: the newest orders of a customer, open orders, one order by ID. Keep together what is read together, and make a subcollection or a separate collection only when the data grows without limit.
2. Create the database in the right placeChoose Native mode, the edition and a location near the users or the rest of the system. The location is permanent.
3. Turn on protection at the startEnable delete protection and point-in-time recovery when you create the database, and add a backup schedule.
4. Declare the composite indexesCreate an index for every query that combines an equality filter with a sort, or filters on several ranges. The error message of a failed query also links to the index it needs.
5. Write with create and server timestampsUse create for inserts so that a retry can’t overwrite, and let the server set createdAt, so clocks on devices don’t matter.
6. Page with cursors, not offsetsUse limit with start_after on the last document. An offset still bills you for every document it skips.
7. Set a TTL policy for temporary dataStore an expiry timestamp on sessions, carts and tokens, and enable the policy for that field.
8. Lock down accessGive server identities a role such as Cloud Datastore User. For clients, write Security Rules that check the signed-in user, and test them in the emulator.
9. Watch usage and costCheck read and write counts in Cloud Monitoring after each release, because one new listener or one wide query can change the bill.

• Index every query shape you use, and wait for new composite indexes to finish building before the release.
• Use limit and cursors (start_after), so each page returns only what the screen shows.
• Ask for only the fields you need with a projection (select) on server-side reads, to cut data transferred.
• Use auto-generated document IDs for write-heavy collections, and ramp traffic up to a new collection gradually.
• Batch writes (up to 500 per batch) or use the bulk writer for imports, instead of one request per document.
• Keep documents small, with the rarely read parts in a subcollection or a separate document.
• Use aggregation queries for counts and sums, instead of reading every matching document.
• Place the database in the same region as the compute that uses it, to remove round-trip time.

FinOps is the habit of managing cloud spend together with engineering. These are the FinOps checks that matter most for Firestore.

• Use limit and narrow filters, because every returned document is a billed read.
• Replace offsets with cursors, since skipped documents are billed too.
• Use aggregation queries (count, sum, average), which bill per 1,000 index entries instead of per document.
• Keep listeners on small, specific queries, and detach them when a screen closes.
• Add single-field index exemptions for big fields that are never queried, to cut storage and write cost.
• Set TTL policies to remove temporary data, and so reduce stored data.
• Compare Standard and Enterprise for your workload, since large reads are billed in 4 KiB units in Enterprise.
• Keep PITR and backups only on databases that need them, and set retention to match your rules.
• Use the free daily quota for development and small apps (one database per project gets it).
• Put a budget alert on the project and review the Firestore usage report weekly.

• Write Security Rules that check request.auth, and test them with the emulator before each release.
• Give server identities IAM roles such as Cloud Datastore User, and use IAM Conditions to limit a role to one database where you need it.
• Use App Check so that only your genuine apps can call Firestore from clients.
• For production databases, switch on delete protection and point-in-time recovery.
• Use customer managed encryption keys (Cloud KMS) if your policy requires them. Data is encrypted at rest by default.
• Reach Firestore from private workloads with Private Google Access or Private Service Connect, and use VPC Service Controls for sensitive projects.
• Enable Data Access audit logs for Firestore where you need to see who read or changed data.
• Keep secrets and card data out of documents, and keep keys in Secret Manager.
• Restrict who may run exports, imports and database deletion, since these move or remove all data.
• Review Security Command Center findings and IAM recommendations for the project.

Cloud Audit Logs record who changed the database and, if enabled, who read data, Cloud Asset Inventory keeps the configuration history, Security Command Center reports posture, and Google’s compliance reports manager holds certifications. Google runs the service, replicates the data and encrypts it at rest. The data model, Security Rules, IAM roles, locations, backup choices and what is stored are yours.

• Query for only what a screen needs, so fewer documents are read, sent and rendered.
• Use TTL for temporary data and index exemptions for large unqueried fields to keep stored data small.
• Keep the database near the compute and users it serves, to avoid long network paths.
• Detach listeners when screens close, so devices and servers stop doing work nobody sees.
• Where data rules and latency allow, choose a location with a lower-carbon grid, which Google marks in its location list.
• Google’s Carbon Footprint report is per project and service group, so quote no Firestore-only figure.

Purchase options

What you actually pay for

• Document reads, writes and deletes in Standard, or read and write units in Enterprise
• Stored data and its index entries
• Point-in-time recovery and backup storage, and restores or clones
• Network egress out of the location
• Managed exports and imports, and TTL deletions as deletes

An orders application: a Native mode database in Mumbai with delete protection and point-in-time recovery, a composite index for the newest orders of a customer, a TTL policy, a daily backup, an export and a role for the API’s service account. The CLI tab builds it; Terraform describes the same resources. The Python tab inserts an order so that a retry is harmless, reads the newest orders, counts on the server and reserves stock in a transaction, and the C# tab does the same inserts, query and transaction. Replace the project, location and names with your own.

# Placeholders: replace the project, the location and the service account with your own.
PROJECT=my-project-id
LOCATION=asia-south1
DB=shop
SA=orders-api@$PROJECT.iam.gserviceaccount.com

gcloud services enable firestore.googleapis.com --project $PROJECT

# 1. A Native mode database in Mumbai. The location can't be changed later.
#    Delete protection and point-in-time recovery (seven days of history) are switched on from the start.
gcloud firestore databases create --project $PROJECT --database $DB --location $LOCATION --type firestore-native \
  --delete-protection --enable-pitr

# 2. The index behind "newest orders of one customer". Without it that query fails, and the error links to this exact index.
gcloud firestore indexes composite create --project $PROJECT --database $DB --collection-group orders \
  --field-config field-path=customerId,order=ascending --field-config field-path=createdAt,order=descending

# 3. Time to live: Firestore deletes an order once the timestamp in its expiresAt field has passed.
gcloud firestore fields ttls update expiresAt --project $PROJECT --database $DB --collection-group orders --enable-ttl

# 4. A daily backup, kept for seven days, as a second line of defence next to point-in-time recovery.
gcloud firestore backups schedules create --project $PROJECT --database $DB --recurrence daily --retention 7d

# 5. Let the API's service account read and write documents, and nothing else.
gcloud projects add-iam-policy-binding $PROJECT --member serviceAccount:$SA --role roles/datastore.user

# 6. Check the settings that matter, then keep a copy of the orders collection outside Firestore.
gcloud firestore databases describe --project $PROJECT --database $DB
gcloud firestore export gs://$PROJECT-firestore-exports/$(date +%F) --project $PROJECT --database $DB --collection-ids orders

# Placeholders: pass in your own values. The ones below are examples.
variable "project" {
  type = string
}

variable "location" {
  type    = string
  default = "asia-south1"
}

variable "api_service_account" {
  type = string # for example orders-api@my-project-id.iam.gserviceaccount.com
}

provider "google" {
  project = var.project
}

resource "google_project_service" "firestore" {
  service            = "firestore.googleapis.com"
  disable_on_destroy = false
}

resource "google_firestore_database" "shop" {
  name                              = "shop"
  location_id                       = var.location
  type                              = "FIRESTORE_NATIVE"
  database_edition                  = "STANDARD"
  point_in_time_recovery_enablement = "POINT_IN_TIME_RECOVERY_ENABLED"
  delete_protection_state           = "DELETE_PROTECTION_ENABLED"

  depends_on = [google_project_service.firestore]
}

# The index behind "newest orders of one customer".
resource "google_firestore_index" "orders_by_customer" {
  database   = google_firestore_database.shop.name
  collection = "orders"

  fields {
    field_path = "customerId"
    order      = "ASCENDING"
  }

  fields {
    field_path = "createdAt"
    order      = "DESCENDING"
  }
}

# Delete an order when the timestamp in expiresAt has passed.
resource "google_firestore_field" "orders_ttl" {
  database   = google_firestore_database.shop.name
  collection = "orders"
  field      = "expiresAt"

  ttl_config {}
}

resource "google_firestore_backup_schedule" "daily" {
  database  = google_firestore_database.shop.name
  retention = "604800s" # seven days

  daily_recurrence {}
}

resource "google_project_iam_member" "api" {
  project = var.project
  role    = "roles/datastore.user"
  member  = "serviceAccount:${var.api_service_account}"
}

# pip install google-cloud-firestore
# An insert that is safe to retry, the newest orders of a customer, a server-side count and an order plus a stock reduction in one transaction.
import datetime as dt

from google.api_core import exceptions
from google.cloud import firestore
from google.cloud.firestore_v1.base_query import FieldFilter

db = firestore.Client(database="shop")  # the project and the credentials come from the environment


def place_order(order_id, customer_id, total):
    """create() fails when the document already exists, so a retried request can't overwrite an order. Returns False in that case."""
    try:
        db.collection("orders").document(order_id).create({
            "customerId": customer_id, "status": "PLACED", "total": total,
            "createdAt": firestore.SERVER_TIMESTAMP,
            "expiresAt": dt.datetime.now(dt.timezone.utc) + dt.timedelta(days=90),  # the TTL policy deletes the order after this time
        })
        return True
    except exceptions.AlreadyExists:
        return False


def latest_orders(customer_id, limit=10):
    """Needs the composite index on customerId (ascending) and createdAt (descending). Without it the call fails with a link to the index."""
    query = (db.collection("orders")
             .where(filter=FieldFilter("customerId", "==", customer_id))
             .order_by("createdAt", direction=firestore.Query.DESCENDING)
             .limit(limit))
    return [{"id": doc.id, **doc.to_dict()} for doc in query.stream()]


def count_placed(customer_id):
    """The count runs on the server and is billed as one read per 1,000 index entries, not one read per document."""
    query = (db.collection("orders")
             .where(filter=FieldFilter("customerId", "==", customer_id))
             .where(filter=FieldFilter("status", "==", "PLACED")))
    return query.count().get()[0][0].value


@firestore.transactional
def _reserve(transaction, stock_ref, order_ref, order):
    stock = stock_ref.get(transaction=transaction)  # reads come before writes in a transaction
    if not stock.exists or stock.get("onHand") < 1:
        return False
    transaction.update(stock_ref, {"onHand": firestore.Increment(-1)})
    transaction.create(order_ref, order)
    return True


def order_and_reserve(order_id, customer_id, sku, total):
    """Creates the order and takes one unit out of stock, or does neither. The function can run again if another writer
    touches the same documents, so keep side effects such as emails out of it."""
    order = {"customerId": customer_id, "status": "PLACED", "total": total, "createdAt": firestore.SERVER_TIMESTAMP}
    return _reserve(db.transaction(), db.collection("stock").document(sku), db.collection("orders").document(order_id), order)


if __name__ == "__main__":
    print("created:", place_order("o-0001", "c-100", 2499))
    print("created again:", place_order("o-0001", "c-100", 2499))
    print("newest orders:", [order["id"] for order in latest_orders("c-100")])
    print("placed orders:", count_placed("c-100"))
    db.collection("stock").document("sku-9").set({"onHand": 5})
    print("reserved:", order_and_reserve("o-0002", "c-100", "sku-9", 999))

// dotnet add package Google.Cloud.Firestore
// An insert that is safe to retry, the newest orders of a customer, and an order plus a stock reduction in one transaction.
using Google.Cloud.Firestore;
using Grpc.Core;

string project = Environment.GetEnvironmentVariable("GOOGLE_CLOUD_PROJECT") ?? throw new InvalidOperationException("Set GOOGLE_CLOUD_PROJECT first.");
FirestoreDb db = new FirestoreDbBuilder { ProjectId = project, DatabaseId = "shop" }.Build();

Console.WriteLine($"created: {await PlaceOrder("o-0001", "c-100", 2499)}");
Console.WriteLine($"created again: {await PlaceOrder("o-0001", "c-100", 2499)}");

// Needs the composite index on customerId (ascending) and createdAt (descending).
QuerySnapshot newest = await db.Collection("orders").WhereEqualTo("customerId", "c-100").OrderByDescending("createdAt").Limit(10).GetSnapshotAsync();
foreach (DocumentSnapshot doc in newest.Documents)
    Console.WriteLine($"{doc.Id}: {doc.GetValue<string>("status")}");

// One transaction: take a unit out of stock and create the order, or do neither.
DocumentReference stock = db.Collection("stock").Document("sku-9");
DocumentReference order = db.Collection("orders").Document("o-0002");
bool reserved = await db.RunTransactionAsync(async transaction =>
{
    DocumentSnapshot snapshot = await transaction.GetSnapshotAsync(stock);   // reads come before writes
    if (!snapshot.Exists || snapshot.GetValue<long>("onHand") < 1) return false;
    transaction.Update(stock, "onHand", FieldValue.Increment(-1));
    transaction.Create(order, new Dictionary<string, object> { ["customerId"] = "c-100", ["status"] = "PLACED", ["total"] = 999, ["createdAt"] = FieldValue.ServerTimestamp });
    return true;
});
Console.WriteLine($"reserved: {reserved}");

async Task<bool> PlaceOrder(string orderId, string customerId, int total)
{
    try
    {
        await db.Collection("orders").Document(orderId).CreateAsync(new Dictionary<string, object>
        {
            ["customerId"] = customerId, ["status"] = "PLACED", ["total"] = total,
            ["createdAt"] = FieldValue.ServerTimestamp, ["expiresAt"] = Timestamp.FromDateTime(DateTime.UtcNow.AddDays(90))
        });
        return true;
    }
    catch (RpcException ex) when (ex.StatusCode == StatusCode.AlreadyExists)
    {
        return false;   // the order exists already, so a retry does no harm
    }
}

Videos picked for this service. Each one is labelled with its source, opens on YouTube if you prefer, and loads only when you press play.

Document changes can start code through Eventarc triggers on Cloud Run or Cloud Run functions. Customer managed keys come from Cloud KMS, usage metrics and alerts live in Cloud Monitoring, and an export can be loaded into BigQuery for analysis.