Crate firestore

Source
Expand description

§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