feat(multi-search): add async support for multi-search operations

- add AsyncMultiSearch class for async multi-search operations
- add async tests for multi-search functionality
- add async fixtures for testing async multi-search operations

Author: tharropoulos

src/typesense/async_multi_search.py

@@ -0,0 +1,108 @@
+"""
+This module provides async functionality for performing multi-search operations in the Typesense API.
+
+It contains the AsyncMultiSearch class, which allows for executing multiple search queries
+asynchronously in a single API call.
+
+Classes:
+    AsyncMultiSearch: Manages async multi-search operations in the Typesense API.
+
+Dependencies:
+    - typesense.async_api_call: Provides the AsyncApiCall class for making async API requests.
+    - typesense.preprocess: Provides the stringify_search_params function for parameter processing.
+    - typesense.types.document: Provides the MultiSearchCommonParameters type.
+    - typesense.types.multi_search: Provides MultiSearchRequestSchema and MultiSearchResponse types.
+
+Note: This module uses conditional imports to support both Python 3.11+ and earlier versions.
+"""
+
+import sys
+
+from typesense.async_api_call import AsyncApiCall
+from typesense.preprocess import stringify_search_params
+from typesense.types.document import MultiSearchCommonParameters
+from typesense.types.multi_search import MultiSearchRequestSchema, MultiSearchResponse
+
+if sys.version_info >= (3, 11):
+    import typing
+else:
+    import typing_extensions as typing
+
+
+class AsyncMultiSearch:
+    """
+    Manages async multi-search operations in the Typesense API.
+
+    This class provides async methods to perform multiple search queries in a single API call.
+
+    Attributes:
+        resource_path (str): The API endpoint path for multi-search operations.
+        api_call (AsyncApiCall): The AsyncApiCall instance for making async API requests.
+    """
+
+    resource_path: typing.Final[str] = "/multi_search"
+
+    def __init__(self, api_call: AsyncApiCall) -> None:
+        """
+        Initialize the AsyncMultiSearch instance.
+
+        Args:
+            api_call (AsyncApiCall): The AsyncApiCall instance for making async API requests.
+        """
+        self.api_call = api_call
+
+    async def perform(
+        self,
+        search_queries: MultiSearchRequestSchema,
+        common_params: typing.Union[MultiSearchCommonParameters, None] = None,
+    ) -> MultiSearchResponse:
+        """
+        Perform a multi-search operation.
+
+        This method allows executing multiple search queries in a single API call.
+        It processes the search parameters, sends the request to the Typesense API,
+        and returns the multi-search response.
+
+        Args:
+            search_queries (MultiSearchRequestSchema):
+                A dictionary containing the list of search queries to perform.
+                The dictionary should have a 'searches' key with a list of search
+                parameter dictionaries.
+            common_params (Union[MultiSearchCommonParameters, None], optional):
+                Common parameters to apply to all search queries. Defaults to None.
+
+        Returns:
+            MultiSearchResponse:
+                The response from the multi-search operation, containing
+                the results of all search queries.
+
+        Example:
+            >>> multi_search = AsyncMultiSearch(async_api_call)
+            >>> response = await multi_search.perform(
+            ...     {
+            ...         "searches": [
+            ...             {
+            ...                 "q": "com",
+            ...                 "query_by": "company_name",
+            ...                 "collection": "companies",
+            ...             },
+            ...         ],
+            ...     }
+            ... )
+        """
+        stringified_search_params = [
+            stringify_search_params(search_params)
+            for search_params in search_queries.get("searches")
+        ]
+        search_body = {
+            "searches": stringified_search_params,
+            "union": search_queries.get("union", False),
+        }
+        response: MultiSearchResponse = await self.api_call.post(
+            AsyncMultiSearch.resource_path,
+            body=search_body,
+            params=common_params,
+            as_json=True,
+            entity_type=MultiSearchResponse,
+        )
+        return response

tests/fixtures/multi_search_fixtures.py

@@ -3,10 +3,28 @@
 import pytest
 
 from typesense.api_call import ApiCall
+from typesense.async_api_call import AsyncApiCall
+from typesense.async_multi_search import AsyncMultiSearch
 from typesense.multi_search import MultiSearch
 
 
 @pytest.fixture(scope="function", name="actual_multi_search")
 def actual_multi_search_fixture(actual_api_call: ApiCall) -> MultiSearch:
     """Return a MultiSearch object using a real API."""
     return MultiSearch(actual_api_call)
+
+
+@pytest.fixture(scope="function", name="actual_async_multi_search")
+def actual_async_multi_search_fixture(
+    actual_async_api_call: AsyncApiCall,
+) -> AsyncMultiSearch:
+    """Return a AsyncMultiSearch object using a real API."""
+    return AsyncMultiSearch(actual_async_api_call)
+
+
+@pytest.fixture(scope="function", name="fake_async_multi_search")
+def fake_async_multi_search_fixture(
+    fake_async_api_call: AsyncApiCall,
+) -> AsyncMultiSearch:
+    """Return a AsyncMultiSearch object with test values."""
+    return AsyncMultiSearch(fake_async_api_call)

tests/multi_search_test.py

@@ -10,25 +10,42 @@
 )
 from typesense import exceptions
 from typesense.api_call import ApiCall
+from typesense.async_api_call import AsyncApiCall
+from typesense.async_multi_search import AsyncMultiSearch
 from typesense.multi_search import MultiSearch
 from typesense.types.multi_search import MultiSearchRequestSchema
 
 
 def test_init(fake_api_call: ApiCall) -> None:
-    """Test that the Document object is initialized correctly."""
-    documents = MultiSearch(fake_api_call)
+    """Test that the MultiSearch object is initialized correctly."""
+    multi_search = MultiSearch(fake_api_call)
 
-    assert_match_object(documents.api_call, fake_api_call)
+    assert_match_object(multi_search.api_call, fake_api_call)
     assert_object_lists_match(
-        documents.api_call.node_manager.nodes,
+        multi_search.api_call.node_manager.nodes,
         fake_api_call.node_manager.nodes,
     )
     assert_match_object(
-        documents.api_call.config.nearest_node,
+        multi_search.api_call.config.nearest_node,
         fake_api_call.config.nearest_node,
     )
 
 
+def test_init_async(fake_async_api_call: AsyncApiCall) -> None:
+    """Test that the AsyncMultiSearch object is initialized correctly."""
+    multi_search = AsyncMultiSearch(fake_async_api_call)
+
+    assert_match_object(multi_search.api_call, fake_async_api_call)
+    assert_object_lists_match(
+        multi_search.api_call.node_manager.nodes,
+        fake_async_api_call.node_manager.nodes,
+    )
+    assert_match_object(
+        multi_search.api_call.config.nearest_node,
+        fake_async_api_call.config.nearest_node,
+    )
+
+
 def test_multi_search_single_search(
     actual_multi_search: MultiSearch,
     actual_api_call: ApiCall,
@@ -220,3 +237,157 @@ def test_search_invalid_parameters(
                 ],
             },
         )
+
+
+async def test_multi_search_single_search_async(
+    actual_async_multi_search: AsyncMultiSearch,
+    delete_all: None,
+    create_collection: None,
+    create_document: None,
+) -> None:
+    """Test that the AsyncMultiSearch object can perform a single search."""
+    request_params: MultiSearchRequestSchema = {
+        "searches": [
+            {"q": "com", "query_by": "company_name", "collection": "companies"},
+        ],
+    }
+    response = await actual_async_multi_search.perform(
+        search_queries=request_params,
+    )
+
+    assert len(response.get("results")) == 1
+    assert_to_contain_keys(
+        response.get("results")[0],
+        [
+            "facet_counts",
+            "found",
+            "hits",
+            "page",
+            "out_of",
+            "request_params",
+            "search_time_ms",
+            "search_cutoff",
+        ],
+    )
+
+    assert_to_contain_keys(
+        response.get("results")[0].get("hits")[0],
+        ["document", "highlights", "highlight", "text_match", "text_match_info"],
+    )
+
+
+async def test_multi_search_multiple_searches_async(
+    actual_async_multi_search: AsyncMultiSearch,
+    delete_all: None,
+    create_collection: None,
+    create_document: None,
+) -> None:
+    """Test that the AsyncMultiSearch object can perform multiple searches."""
+    request_params: MultiSearchRequestSchema = {
+        "searches": [
+            {"q": "com", "query_by": "company_name", "collection": "companies"},
+            {"q": "company", "query_by": "company_name", "collection": "companies"},
+        ],
+    }
+
+    response = await actual_async_multi_search.perform(search_queries=request_params)
+
+    assert len(response.get("results")) == len(request_params.get("searches"))
+    for search_results in response.get("results"):
+        assert_to_contain_keys(
+            search_results,
+            [
+                "facet_counts",
+                "found",
+                "hits",
+                "page",
+                "out_of",
+                "request_params",
+                "search_time_ms",
+                "search_cutoff",
+            ],
+        )
+
+        assert_to_contain_keys(
+            search_results.get("hits")[0],
+            ["document", "highlights", "highlight", "text_match", "text_match_info"],
+        )
+
+
+async def test_multi_search_union_async(
+    actual_async_multi_search: AsyncMultiSearch,
+    delete_all: None,
+    create_collection: None,
+    create_document: None,
+) -> None:
+    """Test that the AsyncMultiSearch object can perform multiple searches with union."""
+    request_params: MultiSearchRequestSchema = {
+        "union": True,
+        "searches": [
+            {"q": "com", "query_by": "company_name", "collection": "companies"},
+            {"q": "company", "query_by": "company_name", "collection": "companies"},
+        ],
+    }
+
+    response = await actual_async_multi_search.perform(search_queries=request_params)
+
+    assert_to_contain_keys(
+        response,
+        [
+            "found",
+            "hits",
+            "page",
+            "out_of",
+            "union_request_params",
+            "search_time_ms",
+            "search_cutoff",
+        ],
+    )
+
+    assert_to_contain_keys(
+        response.get("hits")[0],
+        [
+            "collection",
+            "document",
+            "highlights",
+            "highlight",
+            "text_match",
+            "text_match_info",
+            "search_index",
+        ],
+    )
+
+
+async def test_multi_search_array_async(
+    actual_async_multi_search: AsyncMultiSearch,
+    delete_all: None,
+    create_collection: None,
+    create_document: None,
+) -> None:
+    """Test that the AsyncMultiSearch object can perform a search with an array query_by."""
+    request_params: MultiSearchRequestSchema = {
+        "searches": [
+            {"q": "com", "query_by": ["company_name"], "collection": "companies"},
+        ],
+    }
+    response = await actual_async_multi_search.perform(search_queries=request_params)
+
+    assert len(response.get("results")) == 1
+    assert_to_contain_keys(
+        response.get("results")[0],
+        [
+            "facet_counts",
+            "found",
+            "hits",
+            "page",
+            "out_of",
+            "request_params",
+            "search_time_ms",
+            "search_cutoff",
+        ],
+    )
+
+    assert_to_contain_keys(
+        response.get("results")[0].get("hits")[0],
+        ["document", "highlights", "highlight", "text_match", "text_match_info"],
+    )