Crate firestore

Expand description

§Firestore for Rust

A client for Google Firestore built on the official gRPC API, with a fluent, strongly typed query builder and its own Serde serializer for Firestore’s protobuf values.

Full documentation, with a chapter per topic: https://firestore-rust.abdolence.dev

§Example

use firestore::*;
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Deserialize, Serialize)]
struct MyTestStructure {
    some_id: FirestoreDocumentId,
    some_string: String,
    some_num: u64,
}

let db = FirestoreDb::new("my-project-id").await?;

const TEST_COLLECTION_NAME: FirestoreCollectionId =
    FirestoreCollectionId::from_static("test");

let my_struct = MyTestStructure {
    some_id: FirestoreDocumentId::from_static("test-1"),
    some_string: "Test".to_string(),
    some_num: 42,
};

// Create a document from a Rust structure
let created: MyTestStructure = db.fluent()
    .insert()
    .into(TEST_COLLECTION_NAME)
    .document_id(&my_struct.some_id)
    .object(&my_struct)
    .execute()
    .await?;

// Query, selecting fields by compile-time checked paths
let as_vec: Vec<MyTestStructure> = db.fluent()
    .select()
    .fields(paths!(MyTestStructure::{some_id, some_num, some_string}))
    .from(TEST_COLLECTION_NAME)
    .filter(|q| q.for_all([
        q.field(path!(MyTestStructure::some_num)).is_not_null(),
        q.field(path!(MyTestStructure::some_string)).eq("Test"),
    ]))
    .order(|o| o.fields([o.field(path!(MyTestStructure::some_num)).desc()]))
    .obj()
    .query()
    .await?;

db.fluent()
    .delete()
    .from(TEST_COLLECTION_NAME)
    .document_id(&my_struct.some_id)
    .execute()
    .await?;

§Where to look

For	Start at
Creating a client	`FirestoreDb::new`, `FirestoreDb::with_options`, `FirestoreDb::with_options_auth`
Every read and write	`FirestoreDb::fluent`
Document and collection IDs	`FirestoreDocumentId`, `FirestoreCollectionId`, `ParentPathBuilder`
Field paths in queries and updates	`path!`, `paths!`
Transactions	`FirestoreDb::run_transaction`, `FirestoreTransaction`
Batch writes	`FirestoreDb::create_simple_batch_writer`, `FirestoreDb::create_streaming_batch_writer`
Realtime changes	`FirestoreDb::create_listener`, `FirestoreListener`
Timestamps	`FirestoreTimestamp`, `FirestoreInstant`, `serialize_as_timestamp`
Schemaless documents	`FirestoreDb::serialize_map_to_doc`, `FirestoreValue`
Errors	`errors`

Caching is enabled in this build: see FirestoreCache.

§Cargo features

Feature	Effect
`tls-roots` (default)	TLS trust anchors from the platform’s native root store
`tls-webpki-roots`	TLS trust anchors bundled from the `webpki-roots` crate instead
`auth-default-crypto` (default)	The aws-lc-rs rustls crypto provider service account keys sign their tokens with; without it, install a rustls `CryptoProvider` before creating a client
`caching-memory`	In-memory collection and document cache, kept current by a listener
`caching-persistent`	The same cache backed by an on-disk database
`admin`	Declarative index management and bulk delete: composite indexes, vector indexes, single-field overrides, TTL policy, and `BulkDeleteDocuments`

Runnable examples for every topic: https://github.com/abdolence/firestore-rs/tree/master/examples

Re-exports§

pub extern crate struct_path;

Re-exports§

pub use gcloud_sdk;
pub use jiff;

Modules§

delete_builder: Deletes a document, or queues the delete on a batch or transaction.
document_transform_builder: Builds server-side field transformations (increment, array append/remove, server timestamp) for an update.
errors: Defines the error types used throughout the firestore-rs crate.
index_builder: Declares and syncs one collection group’s composite indexes, single-field overrides and TTL policy. Requires the admin feature.
insert_builder: Inserts a document from a raw Document or a serializable Rust object.
listing_builder: Lists the documents in a collection, or the collection IDs under a path, with pagination.
select_aggregation_builder: Builds COUNT, SUM and AVG aggregations for a query.
select_builder: Runs queries and document/collection-group reads, including filtering, ordering, cursors, vector search, partitioned queries and listeners.
select_filter_builder: Builds comparison, unary and composite (AND/OR) filters for a query.
select_order_builder: Builds the per-field sort direction for a query or listing’s result ordering.
serialize_as_null: Stores an Option<T> field as T’s ordinary Firestore value when present, or an explicit Firestore null when None.
serialize_as_null_timestamp: Stores an Option<FirestoreInstant> field as a native Firestore timestamp when present, or an explicit Firestore null when None.
serialize_as_optional_timestamp: Stores an Option<FirestoreInstant> field as a native Firestore timestamp when present.
serialize_as_reference: Stores a String field as a native Firestore document reference instead of a plain string value.
serialize_as_timestamp: Stores a FirestoreInstant field as a native Firestore timestamp instead of a string.
timestamp_utils: Provides utility functions for working with Firestore timestamps.
update_builder: Updates a document from a raw Document, a serializable Rust object, or transformations only, and queues updates on a batch or transaction.

Macros§

path: Builds the Firestore field path for one field of Struct as a String.
path_camel_case: Builds the Firestore field path for one field of Struct, converting it to camelCase.
paths: Builds the Firestore field paths for several fields of Struct as a Vec<String>.
paths_camel_case: Builds the Firestore field paths for several fields of Struct, converting each to camelCase.

Structs§

FirestoreAggregatedQueryParams
FirestoreAggregatedQueryParamsInit: Required fields of FirestoreAggregatedQueryParams; convert with FirestoreAggregatedQueryParams::from or .into().
FirestoreAggregation
FirestoreAggregationInit: Required fields of FirestoreAggregation; convert with FirestoreAggregation::from or .into().
FirestoreAggregationOperatorAvg
FirestoreAggregationOperatorAvgInit: Required fields of FirestoreAggregationOperatorAvg; convert with FirestoreAggregationOperatorAvg::from or .into().
FirestoreAggregationOperatorCount
FirestoreAggregationOperatorCountInit: Required fields of FirestoreAggregationOperatorCount; convert with FirestoreAggregationOperatorCount::from or .into().
FirestoreAggregationOperatorSum
FirestoreAggregationOperatorSumInit: Required fields of FirestoreAggregationOperatorSum; convert with FirestoreAggregationOperatorSum::from or .into().
FirestoreBatch
FirestoreBatchWriteResponse
FirestoreBatchWriteResponseInit: Required fields of FirestoreBatchWriteResponse; convert with FirestoreBatchWriteResponse::from or .into().
FirestoreBulkDeleteParams: A declared bulk delete: the collection groups to remove, at any depth across the whole database, and whether to wait for Firestore to finish.
FirestoreBulkDeleteParamsInit: Required fields of FirestoreBulkDeleteParams; convert with FirestoreBulkDeleteParams::from or .into().
FirestoreBulkDeleteProgress: One collection group’s document- or byte-deletion progress, as Firestore reports it in BulkDeleteDocumentsMetadata.
FirestoreBulkDeleteResult: The outcome of a bulk delete: what was requested, and - when FirestoreBulkDeleteParams::wait was set - what Firestore reported once the operation reached a terminal state.
FirestoreCache: Manages a cache of Firestore data.
FirestoreCacheBuilder: Builds a FirestoreCache.
FirestoreCacheCollection: One collection to cache, as described to FirestoreCacheBuilder.
FirestoreCacheCollectionConfiguration: Configuration for a single cached collection.
FirestoreCacheConfiguration: Describes which collections a FirestoreCache holds and how each of them is loaded.
FirestoreCacheName: A name identifying a cache instance.
FirestoreCacheOptions: Options for a FirestoreCache.
FirestoreCacheOptionsInit: Required fields of FirestoreCacheOptions; convert with FirestoreCacheOptions::from or .into().
FirestoreCollectionDocuments
FirestoreCollectionDocumentsInit: Required fields of FirestoreCollectionDocuments; convert with FirestoreCollectionDocuments::from or .into().
FirestoreCollectionId: A Firestore collection ID that has been checked against Firestore’s ID rules.
FirestoreCompositeIndex: A declared composite index: an ordered list of fields plus the scope it serves.
FirestoreDb: The main entry point for interacting with a Google Firestore database.
FirestoreDbOptions: Configuration options for the FirestoreDb client.
FirestoreDbOptionsInit: Required fields of FirestoreDbOptions; convert with FirestoreDbOptions::from or .into().
FirestoreDbSessionParams: Parameters that define the behavior of a Firestore session or a specific set of operations.
FirestoreDbSessionParamsInit: Required fields of FirestoreDbSessionParams; convert with FirestoreDbSessionParams::from or .into().
FirestoreDocumentId: A Firestore document ID that has been checked against Firestore’s ID rules.
FirestoreDocumentMetadata: Metadata associated with a Firestore document or a query operation.
FirestoreDocumentMetadataInit: Required fields of FirestoreDocumentMetadata; convert with FirestoreDocumentMetadata::from or .into().
FirestoreDynamicStruct: A dynamically-typed structure used to represent complex, nested data often found in Firestore’s explain metrics or other metadata.
FirestoreDynamicStructInit: Required fields of FirestoreDynamicStruct; convert with FirestoreDynamicStruct::from or .into().
FirestoreExecutionStats: Statistics related to the execution of a Firestore query.
FirestoreExecutionStatsInit: Required fields of FirestoreExecutionStats; convert with FirestoreExecutionStats::from or .into().
FirestoreExplainMetrics: Detailed metrics about query execution, if requested via FirestoreExplainOptions.
FirestoreExplainMetricsInit: Required fields of FirestoreExplainMetrics; convert with FirestoreExplainMetrics::from or .into().
FirestoreExplainOptions: Options for requesting query execution analysis from Firestore.
FirestoreExplainOptionsInit: Required fields of FirestoreExplainOptions; convert with FirestoreExplainOptions::from or .into().
FirestoreExplicitFieldOverride: An explicit, non-inherited single-field index override, as listed for one field resource.
FirestoreExprBuilder: The entry point for building fluent Firestore expressions.
FirestoreFieldOverride: A single-field index override: the automatic indexes Firestore would otherwise build for target, replaced by exactly the indexes listed here.
FirestoreFieldOverrideIndex: One single-field index a FirestoreFieldOverride declares explicitly.
FirestoreFieldTransform: Represents a transformation to apply to a specific field within a document.
FirestoreFieldTransformInit: Required fields of FirestoreFieldTransform; convert with FirestoreFieldTransform::from or .into().
FirestoreFindNearestOptions: Options for performing a vector similarity search (find nearest neighbors).
FirestoreFindNearestOptionsInit: Required fields of FirestoreFindNearestOptions; convert with FirestoreFindNearestOptions::from or .into().
FirestoreGeoPoint
FirestoreIndexDeletesWithheld: Undeclared composite indexes a pruning .sync() planned to delete but left in place, because deleting them could have left queries without an index.
FirestoreIndexField: One field of a composite index: its path and how it participates.
FirestoreIndexParams: One collection group’s declared composite indexes, single-field overrides and TTL policy.
FirestoreIndexParamsInit: Required fields of FirestoreIndexParams; convert with FirestoreIndexParams::from or .into().
FirestoreIndexPlan: The outcome of comparing a declared FirestoreIndexParams against one collection group’s existing indexes, field overrides and TTL configuration, under the given FirestoreIndexSyncOptions::prune setting.
FirestoreIndexSyncOptions: Options controlling how .sync() reconciles a declared FirestoreIndexParams with Firestore.
FirestoreIndexSyncOptionsInit: Required fields of FirestoreIndexSyncOptions; convert with FirestoreIndexSyncOptions::from or .into().
FirestoreIndexSyncReport: The result of .sync(): what it changed, what it left alone, and what it found undeclared.
FirestoreIndexSyncTimings: How long a .sync() took, in total and per phase. A phase is None when it did not run: all of them for a skipped sync, and wait when the caller did not ask to wait.
FirestoreLatLng
FirestoreListCollectionIdsParams
FirestoreListCollectionIdsParamsInit: Required fields of FirestoreListCollectionIdsParams; convert with FirestoreListCollectionIdsParams::from or .into().
FirestoreListCollectionIdsResult
FirestoreListCollectionIdsResultInit: Required fields of FirestoreListCollectionIdsResult; convert with FirestoreListCollectionIdsResult::from or .into().
FirestoreListDocParams
FirestoreListDocParamsInit: Required fields of FirestoreListDocParams; convert with FirestoreListDocParams::from or .into().
FirestoreListDocResult
FirestoreListDocResultInit: Required fields of FirestoreListDocResult; convert with FirestoreListDocResult::from or .into().
FirestoreListedCompositeIndex: One composite index Firestore has listed for the owned collection group.
FirestoreListedField: One field resource Firestore has listed for the owned collection group, because it carries an explicit single-field index override, a TTL configuration, or both.
FirestoreListener
FirestoreListenerControlHandle: A cheap, cloneable handle for asking a listener whether it listens on a target, and for removing or resynchronising one while it runs.
FirestoreListenerParams
FirestoreListenerParamsInit: Required fields of FirestoreListenerParams; convert with FirestoreListenerParams::from or .into().
FirestoreListenerTarget
FirestoreListenerTargetParams
FirestoreListenerTargetParamsInit: Required fields of FirestoreListenerTargetParams; convert with FirestoreListenerTargetParams::from or .into().
FirestoreListenerToken
FirestoreMemListenStateStorage
FirestoreMemoryCacheBackend: An in-memory cache backend, backed by the moka cache.
FirestoreMemoryCacheKind: The in-memory backend flavour. See FirestoreCache::memory.
FirestoreMemoryCacheOptions: Tuning options for FirestoreMemoryCacheBackend.
FirestoreOperationWaitOptions: How long long-running Firestore operations are polled for before giving up, shared by index sync and bulk delete.
FirestoreOperationWaitOptionsInit: Required fields of FirestoreOperationWaitOptions; convert with FirestoreOperationWaitOptions::from or .into().
FirestoreParsedReference
FirestorePartition: Represents a single partition of a query.
FirestorePartitionInit: Required fields of FirestorePartition; convert with FirestorePartition::from or .into().
FirestorePartitionQueryParams: Parameters for a partitioned query.
FirestorePartitionQueryParamsInit: Required fields of FirestorePartitionQueryParams; convert with FirestorePartitionQueryParams::from or .into().
FirestorePersistentCacheBackend: A disk-backed cache, storing documents as protobuf in a redb database with one table per collection.
FirestorePersistentCacheKind: The persistent backend flavour. See FirestoreCache::persistent.
FirestorePersistentCacheOptions: Tuning options for FirestorePersistentCacheBackend.
FirestorePlanSummary: A summary of the query plan used by Firestore to execute a query.
FirestorePlanSummaryInit: Required fields of FirestorePlanSummary; convert with FirestorePlanSummary::from or .into().
FirestoreQueryFilterComposite: A composite filter that combines multiple FirestoreQueryFilters.
FirestoreQueryFilterCompositeInit: Required fields of FirestoreQueryFilterComposite; convert with FirestoreQueryFilterComposite::from or .into().
FirestoreQueryOrder: Specifies an ordering for query results based on a field.
FirestoreQueryOrderInit: Required fields of FirestoreQueryOrder; convert with FirestoreQueryOrder::from or .into().
FirestoreQueryParams: Parameters for constructing and executing a Firestore query.
FirestoreQueryParamsInit: Required fields of FirestoreQueryParams; convert with FirestoreQueryParams::from or .into().
FirestoreReference
FirestoreRequestOptions: Options attached to an individual Firestore server request.
FirestoreRequestOptionsInit: Required fields of FirestoreRequestOptions; convert with FirestoreRequestOptions::from or .into().
FirestoreRequestTag: A single request tag attached to a Firestore request.
FirestoreSimpleBatchWriteOptions
FirestoreSimpleBatchWriteOptionsInit: Required fields of FirestoreSimpleBatchWriteOptions; convert with FirestoreSimpleBatchWriteOptions::from or .into().
FirestoreSimpleBatchWriter
FirestoreStreamingBatchWriteOptions
FirestoreStreamingBatchWriteOptionsInit: Required fields of FirestoreStreamingBatchWriteOptions; convert with FirestoreStreamingBatchWriteOptions::from or .into().
FirestoreStreamingBatchWriter
FirestoreTempFilesListenStateStorage
FirestoreTimestamp: A wrapper around FirestoreInstant that is always serialized as a Firestore timestamp value, without needing a #[serde(with)] attribute.
FirestoreTransaction
FirestoreTransactionData
FirestoreTransactionOptions: Options for configuring a Firestore transaction.
FirestoreTransactionOptionsInit: Required fields of FirestoreTransactionOptions; convert with FirestoreTransactionOptions::from or .into().
FirestoreTransactionResponse: Represents the response from committing a Firestore transaction.
FirestoreTransactionResponseInit: Required fields of FirestoreTransactionResponse; convert with FirestoreTransactionResponse::from or .into().
FirestoreUnrecognisedIndexItem: One listed index or field resource this crate’s domain model cannot represent, kept for visibility instead of being silently dropped.
FirestoreValue: Represents a Firestore value, wrapping the underlying gRPC Value type.
FirestoreVector
FirestoreVectorIndexConfig: A flat vector index’s configuration, for nearest-neighbor search.
FirestoreVectorIndexConfigInit: Required fields of FirestoreVectorIndexConfig; convert with FirestoreVectorIndexConfig::from or .into().
FirestoreWithMetadata: A container that pairs a document (or other data T) with its associated Firestore metadata.
FirestoreWriteResult: The result of a Firestore write operation (create, update, delete).
FirestoreWriteResultInit: Required fields of FirestoreWriteResult; convert with FirestoreWriteResult::from or .into().
ParentPathBuilder: A builder for constructing Firestore document paths, typically for parent documents when dealing with sub-collections.

Enums§

FirestoreAggregationOperator
FirestoreCacheCollectionLoadMode: Determines how a cached collection is populated when the cache starts.
FirestoreCacheCollectionWatch: Which documents of a collection the cache holds and listens to.
FirestoreCacheIncompleteCollectionPolicy: Controls whether collections that are not fully preloaded may serve list/query requests from the cache.
FirestoreCacheInvalidation: What one target change asks the backend to drop.
FirestoreCacheTargetChangeAction: What a backend should do with the collections a Firestore target change affects.
FirestoreCachedValue: Represents a value that might be retrieved from the cache.
FirestoreConsistencySelector: Specifies the consistency guarantee for Firestore read operations.
FirestoreDbSessionCacheMode: Defines the caching mode for Firestore operations within a session.
FirestoreFieldOverrideOutcome: A field resource’s single-field index configuration, as read from a listed ProtoField (gcloud_sdk::google::firestore::admin::v1::Field).
FirestoreFieldOverrideTarget: What a FirestoreFieldOverride applies to: one named field, or every field in the owned collection group.
FirestoreFieldTransformType: Defines the specific type of transformation to apply to a field.
FirestoreFieldTtlOutcome: A field resource’s TTL configuration, as read from a listed ProtoField that carries one.
FirestoreFieldTtlState: The lifecycle state Firestore reports for a listed field’s TTL configuration.
FirestoreFindNearestDistanceMeasure: Specifies the distance measure for vector similarity searches.
FirestoreIndexDeletesWithheldReason: Why a pruning .sync() sent none of its planned index deletes.
FirestoreIndexFieldMode: How a single field participates in an index.
FirestoreIndexQueryScope: Whether an index serves queries against one collection or a collection-group query across every collection with the same ID anywhere under the database.
FirestoreIndexState: The lifecycle state Firestore reports for a listed composite index.
FirestoreIndexSyncSkipReason: Why a .sync() returned without contacting Firestore.
FirestoreListenerTargetResumeType
FirestoreQueryCollection: Specifies the target collection(s) for a Firestore query.
FirestoreQueryCursor: Represents a cursor for paginating query results.
FirestoreQueryDirection: The direction for ordering query results.
FirestoreQueryFilter: Represents a filter condition for a Firestore query.
FirestoreQueryFilterCompare: A field filter that compares a field to a value using a specific operator. The first String argument in each variant is the field path. The FirestoreValue is the value to compare against.
FirestoreQueryFilterCompositeOperator: The operator for combining filters in a FirestoreQueryFilterComposite.
FirestoreQueryFilterUnary: A unary filter that applies an operation to a single field.
FirestoreTargetType
FirestoreTransactionMode: Defines the mode of a Firestore transaction.
FirestoreTransformServerValue: Specifies a server-generated value for a field transformation.
FirestoreWritePrecondition: A precondition on a document, used for conditional write operations in Firestore.

Constants§

FIREBASE_DEFAULT_DATABASE_ID: The default database ID for Firestore, which is "(default)".
FIRESTORE_CACHE_DEFAULT_LISTENER_TARGET_BASE: The first Firestore listener target ID assigned to cached collections.
FIRESTORE_CACHE_DEFAULT_NAME: The cache name used when none is given.

Traits§

FirestoreBatchWriter: Sends a queued batch of writes to Firestore. Implemented by FirestoreSimpleBatchWriter and FirestoreStreamingBatchWriter, which differ in how they send the writes and what WriteResult they return; see FirestoreBatch::write for the call callers actually make.
FirestoreCacheBackend: Defines the contract for a Firestore cache backend.
FirestoreCacheBackendKind: Describes a cache backend flavour - in-memory or persistent - for FirestoreCacheBuilder.
FirestoreCacheDocsByPathSupport: Defines support for retrieving and updating cached documents by their full path.
FirestoreResumeStateStorage: Stores where each listener target should resume from, so a listener picks up where it left off rather than replaying everything.
FirestoreTransactionOps: Queues writes on a FirestoreTransaction or on FirestoreTransactionData - both stage writes the same way, which is why this is a trait rather than inherent methods on either type. Nothing here talks to Firestore: writes are only sent once the transaction is committed.
ValueStruct: Re-export of rvstruct::ValueStruct.

Functions§

firestore_doc_get_field_by_path: Retrieves a field’s value from a Firestore document using a dot-separated path.
firestore_document_from_map: Builds a Firestore document named document_path directly from a (field name, value) iterator, bypassing Serialize.
firestore_document_from_serializable: Serializes object into a Firestore document named document_path.
firestore_document_to_serializable: Deserializes a Firestore document into T.
serialize_latlng_for_firestore: Serializes a struct with latitude and longitude fields as a native Firestore LatLng.
serialize_reference_for_firestore: Serializes value as a Firestore reference value, writing an explicit null for None when none_as_null is set.
serialize_timestamp_for_firestore: Serializes value as a Firestore timestamp value, writing an explicit null for None when none_as_null is set.
serialize_vector_for_firestore: Serializes value as a Firestore vector value, the shape Firestore’s nearest-neighbour queries expect.

Type Aliases§

FirestoreDocument: A type alias for the raw Firestore document representation.
FirestoreDuration: The type of durations that Firestore reports.
FirestoreInstant: An exact instant in time, used by this library for Firestore timestamps.
FirestoreListenEvent
FirestoreListenerTargetChangeType: The kind of change a listener reports for one of its targets.
FirestoreMemCache: Exposes the underlying moka cache type. Not part of the supported API surface: the moka version is not covered by this crate’s semver contract.
FirestoreMemCacheOptions: Exposes the underlying moka cache builder. Not part of the supported API surface: the moka version is not covered by this crate’s semver contract.
FirestoreMemoryCache: A ready-to-use in-memory cache.
FirestorePersistentCache: A ready-to-use persistent cache. See FirestoreMemoryCache for how to use the alias.
FirestoreResult: A type alias for std::result::Result<T, FirestoreError>.
FirestoreSharedCacheBackend: A type alias for a thread-safe, shareable Firestore cache backend.
FirestoreTransactionId: A type alias for Firestore transaction IDs. Transaction IDs are represented as a vector of bytes.

Attribute Macros§

async_trait: Re-export of the async_trait macro.

Derive Macros§

ValueStruct: Re-export of rvstruct::ValueStruct.

Crate firestore

Crate firestore Copy item path

§Firestore for Rust

§Example

§Where to look

§Cargo features

Re-exports§

Re-exports§

Modules§

Macros§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Attribute Macros§

Derive Macros§

Crate firestore