Fixing The Union Parameter Issue In Typesense Multi-Search Queries

July 13, 2025 by StackCamp Team 67 views

Typesense Multi-Search Union Parameter Issue

This article delves into a specific issue encountered while using the multi-search functionality in the Typesense search engine, specifically with the Python client library. The problem arises when attempting to use the union parameter within multi-search queries. This parameter is intended to combine the results from multiple searches into a single, unified result set. However, a bug in the client library prevents the union parameter from being correctly passed to the Typesense API, leading to unexpected and incorrect search results. This article will explore the details of the issue, its impact, the root cause, and the solution implemented to address it.

Understanding Typesense Multi-Search

Before diving into the specifics of the bug, it's crucial to understand the multi-search feature in Typesense. Multi-search allows you to execute multiple search queries in a single API request. This is particularly useful when you need to search across multiple collections or apply different search parameters to the same data. Imagine building an e-commerce platform; you might want to search for products across different categories (e.g., electronics, clothing, books) simultaneously. Multi-search enables this by sending a batch of search queries to Typesense, which processes them and returns a combined result.

Union in Multi-Search

The union parameter in multi-search plays a critical role in how the results are aggregated. When union is set to True, Typesense merges the results from all individual search queries into a single, unified list of hits. This means that the final result set will contain the top matching documents across all collections or queries, effectively treating them as a single search space. Conversely, if union is set to False (or omitted), Typesense returns the results for each query separately. This is useful when you need to analyze the results from each query independently. The union parameter is essential for scenarios where you want a holistic view of the search results across multiple data sources.

The Issue: `union` Parameter Not Passed

The core of the problem lies in how the Python client library for Typesense handles the union parameter when constructing the multi-search request. As reported by a user, the union parameter was not being included in the request body sent to the Typesense API. This meant that the API was not aware of the user's intention to combine the search results, and instead, it returned separate result sets for each query. This behavior deviates from the expected outcome when union is set to True, which should produce a single, unified list of hits.

Impact of the Issue

The impact of this bug can be significant, especially in applications that rely on the union functionality for multi-search. Without the union parameter being correctly passed, users would receive fragmented search results, making it difficult to get a comprehensive overview of the data. For instance, in an e-commerce scenario, if a user searches for a product across multiple categories and the union parameter is not working, they might miss relevant results from certain categories. This can lead to a poor user experience and potentially lost sales. The incorrect behavior of the union parameter undermines the purpose of multi-search, forcing developers to implement workarounds or abandon the feature altogether.

Code Snippet Demonstrating the Issue

To illustrate the issue, let's examine the code snippet provided by the user:

for model, collection in model_and_collection:
    query.append(
        {
            "collection": collection.schema_name,
            "query_by": collection.query_by_fields,
            "q": q,
        }
    )
results = client.multi_search.perform(
    {
        "union": True,
        "searches": query,
    },
    {
        "per_page": self.paginate_by,
        "page": page_number,
    },
)

In this code, the user intends to perform a multi-search across multiple collections (model_and_collection) with the union parameter set to True. They construct a list of search queries (query), each targeting a specific collection. The client.multi_search.perform() method is then called with the union parameter and the list of searches. However, due to the bug, the union parameter is not correctly included in the API request, leading to the issue described above. The code snippet clearly demonstrates the intended usage of the union parameter and highlights the discrepancy between the expected and actual behavior.

Root Cause Analysis

To understand why the union parameter was not being passed, let's examine the relevant code from the Typesense Python client library:

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.
    """
    stringified_search_params = [
        stringify_search_params(search_params)
        for search_params in search_queries.get("searches")
    ]
    search_body = {"searches": stringified_search_params}

    response: MultiSearchResponse = self.api_call.post(
        MultiSearch.resource_path,
        body=search_body,
        params=common_params,
        as_json=True,
        entity_type=MultiSearchResponse,
    )
    return response

Identifying the Bug

The crucial part of the code is the construction of the search_body dictionary. It includes only the searches key, which contains the list of individual search queries. The union parameter, which is part of the search_queries dictionary, is not included in the search_body. This omission is the root cause of the bug. As a result, the Typesense API does not receive the union parameter and defaults to its default behavior, which is to return separate result sets for each query. The bug lies in the incomplete construction of the search_body, specifically the absence of the union parameter.

The Solution

The user who reported the issue also proposed a simple and effective solution: adding a line of code to include the union parameter in the search_body. The proposed fix is as follows:

search_body["union"] = search_queries.get('union', False)

Implementing the Fix

This line of code retrieves the value of the union parameter from the search_queries dictionary using the .get() method with a default value of False. This ensures that if the union parameter is not explicitly provided, it defaults to False. The retrieved value is then assigned to the "union" key in the search_body dictionary. This effectively includes the union parameter in the request body sent to the Typesense API. The proposed solution is straightforward and directly addresses the root cause of the issue.

Corrected Code

With the fix applied, the corrected code snippet looks like this:

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.
    """
    stringified_search_params = [
        stringify_search_params(search_params)
        for search_params in search_queries.get("searches")
    ]
    search_body = {"searches": stringified_search_params}
    search_body["union"] = search_queries.get('union', False) # Added line

    response: MultiSearchResponse = self.api_call.post(
        MultiSearch.resource_path,
        body=search_body,
        params=common_params,
        as_json=True,
        entity_type=MultiSearchResponse,
    )
    return response

Pull Request and Resolution

The user indicated their intention to submit a pull request (MR) with the fix. This is the standard procedure for contributing to open-source projects. By submitting a pull request, the user allows the maintainers of the Typesense Python client library to review the proposed changes, ensure they are correct and consistent with the project's coding standards, and merge them into the codebase. The pull request process is crucial for maintaining the quality and stability of open-source software.

Impact of the Resolution

Once the pull request is merged and a new version of the client library is released, users will be able to use the union parameter in multi-search queries as intended. This will restore the expected behavior of the union parameter, allowing users to combine search results from multiple collections or queries into a single, unified list of hits. This will improve the usability of the multi-search feature and enable developers to build more sophisticated search applications with Typesense. The resolution of the issue will have a positive impact on the user experience and the overall functionality of the Typesense Python client library.

This article has explored a specific bug in the Typesense Python client library that prevented the union parameter from being correctly passed in multi-search queries. We examined the impact of the issue, the root cause, and the solution implemented to address it. The fix, proposed by a user and likely to be implemented through a pull request, involves adding a line of code to include the union parameter in the request body sent to the Typesense API. This resolution will restore the intended behavior of the union parameter, allowing users to combine search results from multiple collections or queries into a single, unified list of hits. This case highlights the importance of community contributions in open-source projects and the iterative process of identifying and resolving bugs to improve software quality.