Migrate search documentation/references/examples to query (#261)

* Migrate search example in docs to query

* Link from search to query API in other places

* Migrate search example to query

* Fix invalid documentation link

* Reformat

* Update examples/query.rs

Co-authored-by: Kumar Shivendu <kshivendu1@gmail.com>

---------

Co-authored-by: Kumar Shivendu <kshivendu1@gmail.com>

Author: timvisee

Cargo.toml

@@ -40,7 +40,7 @@ generate-snippets = []
 uuid = ["dep:uuid"]
 
 [[example]]
-name = "search"
+name = "query"
 required-features = ["serde"]
 
 [[example]]

README.md

@@ -71,12 +71,12 @@ Add necessary dependencies:
 cargo add qdrant-client anyhow tonic tokio serde-json --features tokio/rt-multi-thread
 ```
 
-Add search example from [`examples/search.rs`](./examples/search.rs) to your `src/main.rs`:
+Add query example from [`examples/query.rs`](./examples/query.rs) to your `src/main.rs`:
 
 ```rust
 use qdrant_client::qdrant::{
-    Condition, CreateCollectionBuilder, Distance, Filter, PointStruct, ScalarQuantizationBuilder,
-    SearchParamsBuilder, SearchPointsBuilder, UpsertPointsBuilder, VectorParamsBuilder,
+    Condition, CreateCollectionBuilder, Distance, Filter, PointStruct, QueryPointsBuilder,
+    ScalarQuantizationBuilder, SearchParamsBuilder, UpsertPointsBuilder, VectorParamsBuilder,
 };
 use qdrant_client::{Payload, Qdrant, QdrantError};
 
@@ -127,16 +127,18 @@ async fn main() -> Result<(), QdrantError> {
         .upsert_points(UpsertPointsBuilder::new(collection_name, points))
         .await?;
 
-    let search_result = client
-        .search_points(
-            SearchPointsBuilder::new(collection_name, [11.; 10], 10)
+    let query_result = client
+        .query(
+            QueryPointsBuilder::new(collection_name)
+                .query(vec![11.0; 10])
+                .limit(10)
                 .filter(Filter::all([Condition::matches("bar", 12)]))
                 .with_payload(true)
                 .params(SearchParamsBuilder::default().exact(true)),
         )
         .await?;
-    dbg!(&search_result);
-    // search_result = [
+    dbg!(&query_result);
+    // query_result = [
     //   {
     //     "id": 0,
     //     "version": 0,
@@ -151,10 +153,10 @@ async fn main() -> Result<(), QdrantError> {
     //   }
     // ]
 
-    let found_point = search_result.result.into_iter().next().unwrap();
+    let found_point = query_result.result.into_iter().next().unwrap();
     let mut payload = found_point.payload;
     let baz_payload = payload.remove("baz").unwrap().into_json();
-    println!("baz: {}", baz_payload);
+    println!("baz: {baz_payload}");
     // baz: {"qux":"quux"}
 
     Ok(())

examples/search.rs examples/query.rsexamples/search.rs renamed to examples/query.rs

@@ -1,6 +1,6 @@
 use qdrant_client::qdrant::{
-    Condition, CreateCollectionBuilder, Distance, Filter, PointStruct, ScalarQuantizationBuilder,
-    SearchParamsBuilder, SearchPointsBuilder, UpsertPointsBuilder, VectorParamsBuilder,
+    Condition, CreateCollectionBuilder, Distance, Filter, PointStruct, QueryPointsBuilder,
+    ScalarQuantizationBuilder, SearchParamsBuilder, UpsertPointsBuilder, VectorParamsBuilder,
 };
 use qdrant_client::{Payload, Qdrant, QdrantError};
 
@@ -51,16 +51,18 @@ async fn main() -> Result<(), QdrantError> {
         .upsert_points(UpsertPointsBuilder::new(collection_name, points))
         .await?;
 
-    let search_result = client
-        .search_points(
-            SearchPointsBuilder::new(collection_name, [11.; 10], 10)
+    let query_result = client
+        .query(
+            QueryPointsBuilder::new(collection_name)
+                .query(vec![1.0; 10])
+                .limit(10)
                 .filter(Filter::all([Condition::matches("bar", 12)]))
                 .with_payload(true)
                 .params(SearchParamsBuilder::default().exact(true)),
         )
         .await?;
-    dbg!(&search_result);
-    // search_result = [
+    dbg!(&query_result);
+    // query_result = [
     //   {
     //     "id": 0,
     //     "version": 0,
@@ -75,7 +77,7 @@ async fn main() -> Result<(), QdrantError> {
     //   }
     // ]
 
-    let found_point = search_result.result.into_iter().next().unwrap();
+    let found_point = query_result.result.into_iter().next().unwrap();
     let mut payload = found_point.payload;
     let baz_payload = payload.remove("baz").unwrap().into_json();
     println!("baz: {baz_payload}");

src/lib.rs

@@ -86,37 +86,41 @@
 //!
 //! Documentation: <https://qdrant.tech/documentation/concepts/points/#upload-points>
 //!
-//! # Search
+//! # Query (search)
 //!
 //! Finally, we can retrieve points in various ways, the common one being a plain similarity
 //! search:
 //!
 //! ```no_run
 //!# use qdrant_client::{Qdrant, QdrantError};
-//! use qdrant_client::qdrant::SearchPointsBuilder;
+//! use qdrant_client::qdrant::QueryPointsBuilder;
 //!
-//!# async fn search(client: &Qdrant)
+//!# async fn query(client: &Qdrant)
 //!# -> Result<(), QdrantError> {
-//! let search_request = SearchPointsBuilder::new(
-//!     "my_collection",    // Collection name
-//!     vec![0.0_f32; 512], // Search vector
-//!     4,                  // Search limit, number of results to return
-//! ).with_payload(true);
+//! let query_request = QueryPointsBuilder::new("my_collection") // Collection name
+//!     .query(vec![0.0_f32; 512])                               // Query vector
+//!     .limit(4)                                                // Search limit, number of results to return
+//!     .with_payload(true);                                     // Include full payload in the result
 //!
-//! let response = client.search_points(search_request).await?;
+//! let response = client.query(query_request).await?;
 //!# Ok(())
 //!# }
 //! ```
 //!
-//! The parameter for [`SearchPointsBuilder::new()`](qdrant::SearchPointsBuilder::new) constructor
-//! are pretty straightforward: name of the collection, the vector and how many top-k results to
-//! return. The [`with_payload(true)`](qdrant::SearchPointsBuilder::with_payload) call tells qdrant
-//! to also return the (full) payload data for each point. You can also add a
-//! [`filter()`](qdrant::SearchPointsBuilder::filter) call to the
-//! [`SearchPointsBuilder`](qdrant::SearchPointsBuilder) to filter the result. See the
-//! [`Filter`](qdrant::Filter) documentation for details.
+//! The parameter for [`QueryPointsBuilder::new()`](qdrant::QueryPointsBuilder::new) is pretty
+//! straightforward: the name of the collection to query in. It is combined with other
+//! [functions](qdrant::QueryPointsBuilder#implementations) to further specialize your query to
+//! cover all query flavors.
 //!
-//! Documentation: <https://qdrant.tech/documentation/concepts/search/>
+//! In this example [`query(...)`](qdrant::QueryPointsBuilder::query) is used to enable vector
+//! similarity search on the given vector. [`limit(4)`](qdrant::QueryPointsBuilder::limit)
+//! specifies we only want up to 4 top-k results. And
+//! [`with_payload(true)`](qdrant::QueryPointsBuilder::with_payload) tells Qdrant to also return
+//! the (full) payload data for each point. [`filter()`](qdrant::QueryPointsBuilder::filter) is
+//! also commonly used to apply payload based filtering. See the [`Filter`](qdrant::Filter)
+//! documentation for details.
+//!
+//! Documentation: <https://qdrant.tech/documentation/concepts/search/#query-api>
 
 #![doc(html_logo_url = "https://qdrant.tech/favicon/android-chrome-192x192.png")]
 #![doc(issue_tracker_base_url = "https://github.com/qdrant/rust-client/issues/")]

src/qdrant_client/mod.rs

@@ -72,8 +72,7 @@ pub type QdrantBuilder = QdrantConfig;
 /// - [Collection operations](Self#collection-operations) - manage collections, aliases and cluster configuration
 /// - [Point operations](Self#point-operations) - manage points and vectors
 /// - [Payload operations](Self#payload-operations) - manage point payloads
-/// - [Search operations](Self#search-operations) - search and explore points
-/// - [Query operations](Self#query-operations) - query points using universal search
+/// - [Query operations](Self#query-operations) - query (search) points using universal search
 /// - [Index operations](Self#index-operations) - manage field and payload indices
 /// - [Snapshot operations](Self#snapshot-operations) - manage instance or collection snapshots
 /// - [Shard key operations](Self#sharding-key-operations) - manage shard keys
@@ -82,7 +81,7 @@ pub type QdrantBuilder = QdrantConfig;
 ///
 /// - [`create_collection`](Self::create_collection) - create a new collection
 /// - [`upsert_points`](Self::upsert_points) - insert or update points
-/// - [`search_points`](Self::search_points) - search points with similarity search
+/// - [`query`](Self::query) - query points with similarity search
 #[derive(Clone)]
 pub struct Qdrant {
     /// Client configuration

src/qdrant_client/search.rs

@@ -8,6 +8,10 @@ use crate::qdrant_client::{Qdrant, QdrantResult};
 
 /// # Search operations
 ///
+/// <div class="warning">
+/// For searching, please switch to the more fully featured <a href="#query-operations">Query API</a> instead. The search API will be removed in the future.
+/// </div>
+///
 /// Search and explore points.
 ///
 /// Documentation: <https://qdrant.tech/documentation/concepts/search/>