Crate firestore

Firestore for Rust

Library provides a simple API for Google Firestore:

• Create or update documents using Rust structures and Serde;
• Support for querying / streaming / listing / listening changes / aggregated queries of documents from Firestore;
• Fluent high-level and strongly typed API;
• Full async based on Tokio runtime;
• Macro that helps you use JSON paths as references to your structure fields;
• Implements own Serde serializer to Firestore gRPC values;
• Supports for Firestore timestamp with #[serde(with)];
• Transactions support;
• Streaming batch writes with automatic throttling to avoid time limits from Firestore;
• Aggregated Queries;
• Google client based on gcloud-sdk library that automatically detects GKE environment or application default accounts for local development;

Example using the Fluent API:

use firestore::*;
use serde::{Deserialize, Serialize};
use futures::stream::BoxStream;
use futures::StreamExt;

pub fn config_env_var(name: &str) -> Result<String, String> {
   std::env::var(name).map_err(|e| format!("{}: {}", name, e))
}

// Example structure to play with
#[derive(Debug, Clone, Deserialize, Serialize)]
struct MyTestStructure {
   some_id: String,
   some_string: String,
   one_more_string: String,
   some_num: u64,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {//!
  // Create an instance
  let db = FirestoreDb::new(&config_env_var("PROJECT_ID")?).await?;

  const TEST_COLLECTION_NAME: &'static str = "test";

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

  // Create documents
  let object_returned: MyTestStructure = db.fluent()
      .insert()
      .into(TEST_COLLECTION_NAME)
      .document_id(&my_struct.some_id)
      .object(&my_struct)
      .execute()
      .await?;

  // Update documents
  let object_updated: MyTestStructure = db.fluent()
      .update()
      .fields(paths!(MyTestStructure::{some_num, one_more_string})) // Update only specified fields
      .in_col(TEST_COLLECTION_NAME)
      .document_id(&my_struct.some_id)
      .object(&MyTestStructure {
          some_num: my_struct.some_num + 1,
         one_more_string: "updated-value".to_string(),
          ..my_struct.clone()
      })
      .execute()
     .await?;
 
  // Get a document as an object by id
  let find_it_again: Option<MyTestStructure> = db.fluent()
        .select()
        .by_id_in(TEST_COLLECTION_NAME)
        .obj()
        .one(&my_struct.some_id)
        .await?;

  // Query and read stream of objects
  let object_stream: BoxStream<MyTestStructure> = db.fluent()
    .select()
    .fields(paths!(MyTestStructure::{some_id, some_num, some_string, one_more_string})) // Optionally select the fields needed
    .from(TEST_COLLECTION_NAME)
    .filter(|q| { // Fluent filter API example
        q.for_all([
            q.field(path!(MyTestStructure::some_num)).is_not_null(),
            q.field(path!(MyTestStructure::some_string)).eq("Test"),
            // Sometimes you have optional filters
            Some("Test2")
                .and_then(|value| q.field(path!(MyTestStructure::one_more_string)).eq(value)),
        ])
    })
    .order_by([(
        path!(MyTestStructure::some_num),
        FirestoreQueryDirection::Descending,
    )])
    .obj() // Reading documents as structures using Serde gRPC deserializer
    .stream_query()
    .await?;

    let as_vec: Vec<MyTestStructure> = object_stream.collect().await;
    println!("{:?}", as_vec);

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

    Ok(())
}

All examples and more docs available at: github

Re-exports

pub extern crate struct_path;

Modules

delete_builder

Re-exports all public items from the fluent_api module.

document_transform_builder

Re-exports all public items from the fluent_api module.

errors

Defines the error types used throughout the firestore-rs crate.

insert_builder

Re-exports all public items from the fluent_api module.

listing_builder

Re-exports all public items from the fluent_api module.

select_aggregation_builder

Re-exports all public items from the fluent_api module.

select_builder

Re-exports all public items from the fluent_api module.

select_filter_builder

Re-exports all public items from the fluent_api module.

serialize_as_null

serialize_as_null_timestamp

serialize_as_optional_timestamp

serialize_as_reference

serialize_as_timestamp

timestamp_utils

Provides utility functions for working with Firestore timestamps.

update_builder

Re-exports all public items from the fluent_api module.

Macros

path

path_camel_case

paths

paths_camel_case

Structs

FirestoreAggregatedQueryParams

FirestoreAggregatedQueryParamsInit

FirestoreAggregation

FirestoreAggregationInit

FirestoreAggregationOperatorAvg

FirestoreAggregationOperatorAvgInit

FirestoreAggregationOperatorCount

FirestoreAggregationOperatorCountInit

FirestoreAggregationOperatorSum

FirestoreAggregationOperatorSumInit

FirestoreBatch

FirestoreBatchWriteResponse

FirestoreBatchWriteResponseInit

FirestoreCollectionDocuments

FirestoreCollectionDocumentsInit

FirestoreDb

Re-exports all public items from the db module.

FirestoreDbOptions

Configuration options for the FirestoreDb client.

FirestoreDbOptionsInit

FirestoreDbSessionParams

Parameters that define the behavior of a Firestore session or a specific set of operations.

FirestoreDbSessionParamsInit

FirestoreDocumentMetadata

Re-exports all public items from the firestore_meta module.

FirestoreDocumentMetadataInit

Re-exports all public items from the firestore_meta module.

FirestoreDynamicStruct

Re-exports all public items from the firestore_meta module.

FirestoreDynamicStructInit

Re-exports all public items from the firestore_meta module.

FirestoreExecutionStats

Re-exports all public items from the firestore_meta module.

FirestoreExecutionStatsInit

Re-exports all public items from the firestore_meta module.

FirestoreExplainMetrics

Re-exports all public items from the firestore_meta module.

FirestoreExplainMetricsInit

Re-exports all public items from the firestore_meta module.

FirestoreExplainOptions

Options for requesting query execution analysis from Firestore.

FirestoreExplainOptionsInit

FirestoreExprBuilder

Re-exports all public items from the fluent_api module.

FirestoreFieldTransform

Represents a transformation to apply to a specific field within a document.

FirestoreFieldTransformInit

FirestoreFindNearestOptions

Options for performing a vector similarity search (find nearest neighbors).

FirestoreFindNearestOptionsInit

FirestoreGeoPoint

FirestoreLatLng

FirestoreListCollectionIdsParams

FirestoreListCollectionIdsParamsInit

FirestoreListCollectionIdsResult

FirestoreListCollectionIdsResultInit

FirestoreListDocParams

FirestoreListDocParamsInit

FirestoreListDocResult

FirestoreListDocResultInit

FirestoreListener

FirestoreListenerParams

FirestoreListenerParamsInit

FirestoreListenerTarget

FirestoreListenerTargetParams

FirestoreListenerTargetParamsInit

FirestoreListenerToken

FirestoreMemListenStateStorage

FirestorePartition

Represents a single partition of a query.

FirestorePartitionInit

FirestorePartitionQueryParams

Parameters for a partitioned query.

FirestorePartitionQueryParamsInit

FirestorePlanSummary

Re-exports all public items from the firestore_meta module.

FirestorePlanSummaryInit

Re-exports all public items from the firestore_meta module.

FirestoreQueryFilterComposite

A composite filter that combines multiple FirestoreQueryFilters.

FirestoreQueryFilterCompositeInit

FirestoreQueryOrder

Specifies an ordering for query results based on a field.

FirestoreQueryOrderInit

FirestoreQueryParams

Parameters for constructing and executing a Firestore query.

FirestoreQueryParamsInit

FirestoreReference

FirestoreSimpleBatchWriteOptions

FirestoreSimpleBatchWriteOptionsInit

FirestoreSimpleBatchWriter

FirestoreStreamingBatchWriteOptions

FirestoreStreamingBatchWriteOptionsInit

FirestoreStreamingBatchWriter

FirestoreTempFilesListenStateStorage

FirestoreTimestamp

FirestoreTransaction

FirestoreTransactionOptions

Options for configuring a Firestore transaction.

FirestoreTransactionOptionsInit

FirestoreTransactionResponse

Represents the response from committing a Firestore transaction.

FirestoreTransactionResponseInit

FirestoreValue

Re-exports all public items from the firestore_value module.

FirestoreVector

FirestoreWithMetadata

Re-exports all public items from the firestore_meta module.

FirestoreWriteResult

The result of a Firestore write operation (create, update, delete).

FirestoreWriteResultInit

ParentPathBuilder

A builder for constructing Firestore document paths, typically for parent documents when dealing with sub-collections.

Enums

FirestoreAggregationOperator

FirestoreConsistencySelector

Specifies the consistency guarantee for Firestore read operations.

FirestoreDbSessionCacheMode

Defines the caching mode for Firestore operations within a session.

FirestoreFieldTransformType

Defines the specific type of transformation to apply to a field.

FirestoreFindNearestDistanceMeasure

Specifies the distance measure for vector similarity searches.

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)".

Traits

FirestoreAggregatedQuerySupport

FirestoreBatchWriter

FirestoreCreateSupport

FirestoreDeleteSupport

FirestoreGetByIdSupport

FirestoreListenSupport

FirestoreListingSupport

FirestoreQuerySupport

FirestoreResumeStateStorage

FirestoreUpdateSupport

ValueStruct

Functions

firestore_doc_get_field_by_path

Re-exports helper functions for working with FirestoreDocuments.

firestore_document_from_map

firestore_document_from_serializable

firestore_document_to_serializable

serialize_latlng_for_firestore

serialize_reference_for_firestore

serialize_timestamp_for_firestore

serialize_vector_for_firestore

Type Aliases

FirestoreDocument

A type alias for the raw Firestore document representation.

FirestoreListenEvent

FirestoreResult

A type alias for std::result::Result<T, FirestoreError>.

FirestoreTransactionId

A type alias for Firestore transaction IDs. Transaction IDs are represented as a vector of bytes.

PeekableBoxStream

Attribute Macros

async_trait

Derive Macros

ValueStruct