Fluent API support and example update

README.md

@@ -14,6 +14,7 @@ Library provides a simple API for Google Firestore based on the official gRPC AP
     - Transactions;
     - Aggregated Queries;
     - Streaming batch writes with automatic throttling to avoid time limits from Firestore;
+    - K-nearest neighbor (KNN) vector search;
     - Explaining queries;
 - Fluent high-level and strongly typed API;
 - Full async based on Tokio runtime;
@@ -36,7 +37,7 @@ Cargo.toml:
 
 ```toml
 [dependencies]
-firestore = "0.40"
+firestore = "0.41"
 ```
 
 ## Examples

examples/nearest-vector-query.rs

@@ -42,7 +42,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
             let my_struct = MyTestStructure {
                 some_id: format!("test-{}", i),
                 some_string: "Test".to_string(),
-                some_vec: FirestoreVector::new(vec![i as f64, (i * 1000) as f64]),
+                some_vec: vec![i as f64, (i * 10) as f64, (i * 20) as f64].into(),
             };
 
             // Let's insert some data
@@ -56,12 +56,30 @@ async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
         current_batch.write().await?;
     }
 
-    println!("Search for a test collection with a vector closest to [100.0, 100000.0]");
+    println!("Show sample documents in the test collection");
+    let as_vec: Vec<MyTestStructure> = db
+        .fluent()
+        .select()
+        .from(TEST_COLLECTION_NAME)
+        .limit(3)
+        .obj()
+        .query()
+        .await?;
+
+    println!("Examples: {:?}", as_vec);
+
+    println!("Search for a test collection with a vector closest");
 
     let as_vec: Vec<MyTestStructure> = db
         .fluent()
         .select()
         .from(TEST_COLLECTION_NAME)
+        .find_nearest(
+            path!(MyTestStructure::some_vec),
+            vec![0.0_f64, 0.0_f64, 0.0_f64].into(),
+            FirestoreFindNearestDistanceMeasure::Euclidean,
+            5,
+        )
         .obj()
         .query()
         .await?;

src/fluent_api/select_builder.rs

@@ -3,12 +3,13 @@ use crate::select_aggregation_builder::FirestoreAggregationBuilder;
 use crate::select_filter_builder::FirestoreQueryFilterBuilder;
 use crate::{
     FirestoreAggregatedQueryParams, FirestoreAggregatedQuerySupport, FirestoreAggregation,
-    FirestoreCollectionDocuments, FirestoreExplainOptions, FirestoreGetByIdSupport,
-    FirestoreListenSupport, FirestoreListener, FirestoreListenerParams, FirestoreListenerTarget,
+    FirestoreCollectionDocuments, FirestoreExplainOptions, FirestoreFindNearestDistanceMeasure,
+    FirestoreFindNearestOptions, FirestoreGetByIdSupport, FirestoreListenSupport,
+    FirestoreListener, FirestoreListenerParams, FirestoreListenerTarget,
     FirestoreListenerTargetParams, FirestorePartition, FirestorePartitionQueryParams,
     FirestoreQueryCollection, FirestoreQueryCursor, FirestoreQueryFilter, FirestoreQueryOrder,
     FirestoreQueryParams, FirestoreQuerySupport, FirestoreResult, FirestoreResumeStateStorage,
-    FirestoreTargetType, FirestoreWithMetadata,
+    FirestoreTargetType, FirestoreVector, FirestoreWithMetadata,
 };
 use futures::stream::BoxStream;
 use gcloud_sdk::google::firestore::v1::Document;
@@ -189,6 +190,7 @@ where
         }
     }
 
+    #[inline]
     pub fn explain(self) -> FirestoreSelectDocBuilder<'a, D> {
         Self {
             params: self
@@ -198,6 +200,40 @@ where
         }
     }
 
+    #[inline]
+    pub fn find_nearest<F>(
+        self,
+        field_name: F,
+        vector: FirestoreVector,
+        measure: FirestoreFindNearestDistanceMeasure,
+        neighbors_limit: u32,
+    ) -> FirestoreSelectDocBuilder<'a, D>
+    where
+        F: AsRef<str>,
+    {
+        self.find_nearest_with_options::<F>(FirestoreFindNearestOptions::new(
+            field_name.as_ref().to_string(),
+            vector,
+            measure,
+            neighbors_limit,
+        ))
+    }
+
+    #[inline]
+    pub fn find_nearest_with_options<F>(
+        self,
+        options: FirestoreFindNearestOptions,
+    ) -> FirestoreSelectDocBuilder<'a, D>
+    where
+        F: AsRef<str>,
+    {
+        Self {
+            params: self.params.with_find_nearest(options),
+            ..self
+        }
+    }
+
+    #[inline]
     pub fn explain_with_options(
         self,
         options: FirestoreExplainOptions,