feat: helper method to parse federated search results; added support for union search

Author: haydenhoang

typesense/src/client/mod.rs

@@ -733,7 +733,7 @@ impl Client {
     /// #     ..Default::default()
     /// # };
     /// # let common_params = models::MultiSearchParameters::default();
-    /// let results = client.multi_search().perform(search_requests, common_params).await.unwrap();
+    /// let results = client.multi_search().perform(&search_requests, &common_params).await.unwrap();
     /// # Ok(())
     /// # }
     /// ```

typesense/src/client/multi_search.rs

@@ -52,3 +52,56 @@ where
     #[error("Failed to deserialize the API response into the target struct: {0}")]
     Deserialization(#[from] serde_json::Error),
 }
+
+/// Represents the possible errors that can occur when parsing a `multi_search` response.
+///
+/// This error enum is returned by the `MultiSearchResultExt::parse_at` method when it
+/// fails to convert a raw search result into a strongly-typed `SearchResult<T>`.
+#[derive(Debug, Error)]
+pub enum MultiSearchParseError {
+    /// Indicates that the requested index was outside the bounds of the results vector.
+    ///
+    /// For a `multi_search` request with `n` search queries, the valid indices for the
+    /// results are `0` through `n-1`. This error occurs if the provided index is `n` or greater.
+    ///
+    /// # Fields
+    /// * `0` - The invalid index that was requested.
+    #[error("Search result index {0} is out of bounds.")]
+    IndexOutOfBounds(usize),
+
+    /// Indicates that the Typesense server returned an error for the specific search query at this index.
+    ///
+    // It's possible for a `multi_search` request to succeed overall, but for one or more
+    // individual searches within it to fail (e.g., due to a typo in a collection name).
+    ///
+    /// # Fields
+    /// * `index` - The index of the search query that failed.
+    /// * `message` - The error message returned by the Typesense API for this specific search.
+    #[error("The search at index {index} failed with an API error: {message}")]
+    ApiError {
+        /// The index of the search query that failed.
+        index: usize,
+        /// The error message returned by the Typesense API for this specific search.
+        message: String,
+    },
+
+    /// Indicates a failure to deserialize a document's JSON into the target struct `T`.
+    ///
+    /// This typically happens when the fields in the document stored in Typesense do not
+    /// match the fields defined in the target Rust struct `T`. Check for mismatches in
+    /// field names or data types.
+    ///
+    /// # Fields
+    /// * `index` - The index of the search query where the deserialization error occurred.
+    /// * `source` - The underlying `serde_json::Error` that provides detailed information
+    ///   about the deserialization failure.
+    #[error("Failed to deserialize a document at index {index}: {source}")]
+    Deserialization {
+        /// The index of the search query where the deserialization error occurred.
+        index: usize,
+        /// The underlying `serde_json::Error` that provides detailed information
+        /// about the deserialization failure.
+        #[source]
+        source: serde_json::Error,
+    },
+}

typesense/src/error.rs

@@ -49,11 +49,14 @@ mod error;
 pub mod collection_schema;
 pub mod document;
 pub mod field;
+pub mod prelude;
 // pub mod keys;
 pub mod models;
 
 pub use client::{Client, MultiNodeConfiguration};
-pub use error::{ApiError, Error};
+pub use error::*;
+pub use models::*;
+pub use prelude::*;
 
 #[cfg(feature = "typesense_derive")]
 #[doc(hidden)]

typesense/src/lib.rs

@@ -1,7 +1,8 @@
 //! # Typesense generic models
+mod multi_search;
 mod scoped_key_parameters;
 mod search_result;
-
+pub use multi_search::*;
 pub use scoped_key_parameters::*;
 pub use search_result::*;
 
@@ -19,18 +20,17 @@ pub use typesense_codegen::models::{
     FacetCountsStats, Field, FieldEmbed, FieldEmbedModelConfig, HealthStatus,
     ImportDocumentsParameters, IndexAction, ListStemmingDictionaries200Response,
     MultiSearchCollectionParameters, MultiSearchParameters, MultiSearchResult,
-    MultiSearchResultItem, MultiSearchSearchesParameter, NlSearchModelBase,
-    NlSearchModelCreateSchema, NlSearchModelDeleteSchema, NlSearchModelSchema, PresetDeleteSchema,
-    PresetSchema, PresetUpsertSchema, PresetUpsertSchemaValue, PresetsRetrieveSchema,
-    SchemaChangeStatus, SearchGroupedHit, SearchHighlight, SearchOverride,
-    SearchOverrideDeleteResponse, SearchOverrideExclude, SearchOverrideInclude, SearchOverrideRule,
-    SearchOverrideSchema, SearchOverridesResponse, SearchParameters, SearchResultConversation,
-    SearchResultHitTextMatchInfo, SearchResultRequestParams, SearchResultRequestParamsVoiceQuery,
-    SearchSynonym, SearchSynonymDeleteResponse, SearchSynonymSchema, SearchSynonymsResponse,
-    SnapshotParameters, StemmingDictionary, StemmingDictionaryWordsInner,
-    StopwordsSetRetrieveSchema, StopwordsSetSchema, StopwordsSetUpsertSchema,
-    StopwordsSetsRetrieveAllSchema, SuccessStatus, UpdateDocuments200Response,
-    UpdateDocumentsParameters, VoiceQueryModelCollectionConfig,
+    MultiSearchResultItem, NlSearchModelBase, NlSearchModelCreateSchema, NlSearchModelDeleteSchema,
+    NlSearchModelSchema, PresetDeleteSchema, PresetSchema, PresetUpsertSchema,
+    PresetUpsertSchemaValue, PresetsRetrieveSchema, SchemaChangeStatus, SearchGroupedHit,
+    SearchHighlight, SearchOverride, SearchOverrideDeleteResponse, SearchOverrideExclude,
+    SearchOverrideInclude, SearchOverrideRule, SearchOverrideSchema, SearchOverridesResponse,
+    SearchParameters, SearchResultConversation, SearchResultHitTextMatchInfo,
+    SearchResultRequestParams, SearchResultRequestParamsVoiceQuery, SearchSynonym,
+    SearchSynonymDeleteResponse, SearchSynonymSchema, SearchSynonymsResponse, SnapshotParameters,
+    StemmingDictionary, StemmingDictionaryWordsInner, StopwordsSetRetrieveSchema,
+    StopwordsSetSchema, StopwordsSetUpsertSchema, StopwordsSetsRetrieveAllSchema, SuccessStatus,
+    UpdateDocuments200Response, UpdateDocumentsParameters, VoiceQueryModelCollectionConfig,
 };
 // Only re-export the sub modules that have enums inside them.
 pub use typesense_codegen::models::{

typesense/src/models/mod.rs

@@ -0,0 +1,23 @@
+use crate::models;
+use serde::{Deserialize, Serialize};
+
+/// Represents the body of a multi-search request.
+///
+/// This struct acts as a container for a list of individual search queries that will be
+/// sent to the Typesense multi-search endpoint. Each search query is defined in a
+/// `MultiSearchCollectionParameters` struct within the `searches` vector.
+#[derive(Clone, Default, Debug, PartialEq, Serialize, Deserialize)]
+pub struct MultiSearchSearchesParameter {
+    /// A vector of individual search queries to be executed. The order of the search results returned by Typesense will match the order of these queries.
+    #[serde(rename = "searches")]
+    pub searches: Vec<models::MultiSearchCollectionParameters>,
+}
+
+impl MultiSearchSearchesParameter {
+    /// Creates a new `MultiSearchSearchesParameter` instance.
+    pub fn new(
+        searches: Vec<models::MultiSearchCollectionParameters>,
+    ) -> MultiSearchSearchesParameter {
+        MultiSearchSearchesParameter { searches }
+    }
+}

typesense/src/models/multi_search.rs

@@ -1,6 +1,7 @@
 //! Contains the generic `SearchResult` and `SearchResultHit` structs
 
 use serde::{de::DeserializeOwned, Deserialize, Serialize};
+use serde_json::Value;
 use typesense_codegen::models as raw_models;
 
 /// Represents a single search result hit, with the document deserialized into a strongly-typed struct `T`.
@@ -105,24 +106,28 @@ where
     ) -> Result<Self, serde_json::Error> {
         let typed_hits = match raw_result.hits {
             Some(raw_hits) => {
-                let mut hits = Vec::with_capacity(raw_hits.len());
-                for raw_hit in raw_hits {
-                    let document: Option<T> = match raw_hit.document {
-                        Some(doc_value) => Some(serde_json::from_value(doc_value)?),
-                        None => None,
-                    };
-
-                    hits.push(SearchResultHit {
-                        document,
-                        highlights: raw_hit.highlights,
-                        highlight: raw_hit.highlight,
-                        text_match: raw_hit.text_match,
-                        text_match_info: raw_hit.text_match_info,
-                        geo_distance_meters: raw_hit.geo_distance_meters,
-                        vector_distance: raw_hit.vector_distance,
-                    });
-                }
-                Some(hits)
+                let hits_result: Result<Vec<SearchResultHit<T>>, _> = raw_hits
+                    .into_iter()
+                    .map(|raw_hit| {
+                        // Map each raw hit to a Result<SearchResultHit<T>, _>
+                        let document: Result<Option<T>, _> = raw_hit
+                            .document
+                            .map(|doc_value| serde_json::from_value(doc_value))
+                            .transpose();
+
+                        Ok(SearchResultHit {
+                            document: document?,
+                            highlights: raw_hit.highlights,
+                            highlight: raw_hit.highlight,
+                            text_match: raw_hit.text_match,
+                            text_match_info: raw_hit.text_match_info,
+                            geo_distance_meters: raw_hit.geo_distance_meters,
+                            vector_distance: raw_hit.vector_distance,
+                        })
+                    })
+                    .collect();
+
+                Some(hits_result?)
             }
             None => None,
         };
@@ -142,3 +147,71 @@ where
         })
     }
 }
+
+// This impl block specifically targets `SearchResult<serde_json::Value>`.
+// The methods inside will only be available on a search result of that exact type.
+impl SearchResult<Value> {
+    /// Attempts to convert a `SearchResult<serde_json::Value>` into a `SearchResult<T>`.
+    ///
+    /// This method is useful after a `perform_union` call where you know all resulting
+    /// documents share the same schema and can be deserialized into a single concrete type `T`.
+    ///
+    /// It iterates through each hit and tries to deserialize its `document` field. If any
+    /// document fails to deserialize into type `T`, the entire conversion fails.
+    ///
+    /// # Type Parameters
+    ///
+    /// * `T` - The concrete, `DeserializeOwned` type you want to convert the documents into.
+    ///
+    /// # Errors
+    ///
+    /// Returns a `serde_json::Error` if any document in the hit list cannot be successfully
+    /// deserialized into `T`.
+    pub fn try_into_typed<T: DeserializeOwned>(self) -> Result<SearchResult<T>, serde_json::Error> {
+        // This logic is very similar to `from_raw`, but it converts between generic types
+        // instead of from a raw model.
+        let typed_hits = match self.hits {
+            Some(value_hits) => {
+                let hits_result: Result<Vec<SearchResultHit<T>>, _> = value_hits
+                    .into_iter()
+                    .map(|value_hit| {
+                        // `value_hit` here is `SearchResultHit<serde_json::Value>`
+                        let document: Option<T> = match value_hit.document {
+                            Some(doc_value) => Some(serde_json::from_value(doc_value)?),
+                            None => None,
+                        };
+
+                        // Construct the new, strongly-typed hit.
+                        Ok(SearchResultHit {
+                            document,
+                            highlights: value_hit.highlights,
+                            highlight: value_hit.highlight,
+                            text_match: value_hit.text_match,
+                            text_match_info: value_hit.text_match_info,
+                            geo_distance_meters: value_hit.geo_distance_meters,
+                            vector_distance: value_hit.vector_distance,
+                        })
+                    })
+                    .collect();
+
+                Some(hits_result?)
+            }
+            None => None,
+        };
+
+        // Construct the final, strongly-typed search result, carrying over all metadata.
+        Ok(SearchResult {
+            hits: typed_hits,
+            found: self.found,
+            found_docs: self.found_docs,
+            out_of: self.out_of,
+            page: self.page,
+            search_time_ms: self.search_time_ms,
+            facet_counts: self.facet_counts,
+            grouped_hits: self.grouped_hits,
+            search_cutoff: self.search_cutoff,
+            request_params: self.request_params,
+            conversation: self.conversation,
+        })
+    }
+}

typesense/src/models/search_result.rs

@@ -0,0 +1,23 @@
+//! The Typesense prelude.
+//!
+//! This module re-exports the most commonly used traits and types from the library,
+//! making them easy to import with a single `use` statement.
+
+use serde::de::DeserializeOwned;
+
+use crate::{MultiSearchParseError, SearchResult};
+
+/// An extension trait for `typesense_codegen::models::MultiSearchResult` to provide typed parsing.
+pub trait MultiSearchResultExt {
+    /// Parses the result at a specific index from a multi-search response into a strongly-typed `SearchResult<T>`.
+    ///
+    /// # Arguments
+    /// * `index` - The zero-based index of the search result to parse.
+    ///
+    /// # Type Parameters
+    /// * `T` - The concrete document type to deserialize the hits into.
+    fn parse_at<T: DeserializeOwned>(
+        &self,
+        index: usize,
+    ) -> Result<SearchResult<T>, MultiSearchParseError>;
+}