feat(multi-search): add union search functionality and update docker-compose version

Author: haydenhoang

docker-compose.yml

@@ -1,17 +1,17 @@
-version: "3"
+version: '3'
 
 services:
   typesense:
-    image: typesense/typesense:0.24.1
-    container_name: "typesense"
+    image: typesense/typesense:29.0
+    container_name: 'typesense'
     ports:
-      - "8108:8108"
+      - '8108:8108'
     volumes:
       - data-dir:/data
     environment:
       TYPESENSE_DATA_DIR: /data
       TYPESENSE_API_KEY: xyz
-    restart: "no"
+    restart: 'no'
 
 volumes:
-  data-dir:
+  data-dir:

src/main/java/org/typesense/api/MultiSearch.java

@@ -1,6 +1,7 @@
 package org.typesense.api;
 
 import org.typesense.model.MultiSearchResult;
+import org.typesense.model.SearchResult;
 import org.typesense.model.MultiSearchSearchesParameter;
 
 import java.util.Map;
@@ -14,8 +15,84 @@ public MultiSearch(ApiCall apiCall) {
         this.apiCall = apiCall;
     }
 
+    /**
+     * Performs a federated multi-search, returning individual result sets for each
+     * query.
+     * <p>
+     * This method is used for running multiple search queries in a single API call,
+     * where
+     * the results for each query are returned as separate and distinct sets. This
+     * is
+     * also known as a
+     * <a href=
+     * "https://typesense.org/docs/latest/api/federated-multi-search.html#federated-search"
+     * target="_blank">Federated Search</a>.
+     * <p>
+     * This method strictly handles non-union searches. It will validate that the
+     * {@code union} flag is set to {@code false}. If the flag is {@code true}, it
+     * will
+     * throw an {@link IllegalArgumentException} to prevent unexpected behavior. For
+     * union
+     * searches, use the {@link #performUnion(MultiSearchSearchesParameter, Map)}
+     * method instead.
+     *
+     * @param multiSearchParameters The object containing the list of search queries
+     *                              to perform.
+     *                              The {@code union} flag must be {@code false} or
+     *                              unset.
+     * @param common_params         A map of common parameters that will be applied
+     *                              to every
+     *                              search query in the request. Can be null or
+     *                              empty.
+     * @return A {@link MultiSearchResult} object containing a list of individual
+     *         search
+     *         results. The order of results in this list is guaranteed to match the
+     *         order of the queries sent in the request.
+     * @throws IllegalArgumentException if the {@code union} flag in
+     *                                  {@code multiSearchParameters}
+     *                                  is set to {@code true}, as this method is
+     *                                  strictly for
+     *                                  non-union federated searches.
+     * @throws Exception                if there is an issue with the API call, such
+     *                                  as a network
+     *                                  problem or an error response from the
+     *                                  server.
+     */
     public MultiSearchResult perform(MultiSearchSearchesParameter multiSearchParameters,
-                                     Map<String, String> common_params) throws Exception {
-        return this.apiCall.post(MultiSearch.RESOURCEPATH, multiSearchParameters, common_params, MultiSearchResult.class);
+            Map<String, String> common_params) throws Exception {
+        if (multiSearchParameters.isUnion()) {
+            throw new IllegalArgumentException(
+                    "The 'perform()' method is for non-union searches. For a union search, please use the 'performUnion()' method.");
+        }
+        return this.apiCall.post(MultiSearch.RESOURCEPATH, multiSearchParameters, common_params,
+                MultiSearchResult.class);
+    }
+
+    /**
+     * Performs a <a href=
+     * "https://typesense.org/docs/latest/api/federated-multi-search.html#union-search"
+     * target="_blank">Union Search</a>
+     * and returns a single, combined search result.
+     * <p>
+     * This method offers a convenient way to perform a union search. It
+     * automatically
+     * enforces {@code union=true}, merging results from all queries into a single
+     * ordered set of hits without requiring you to set the flag manually.
+     * <p>
+     * This method is guaranteed to not modify the provided
+     * {@code multiSearchParameters}
+     * object, making it safe to reuse the same parameter object across multiple API
+     * calls.
+     *
+     */
+    public SearchResult performUnion(MultiSearchSearchesParameter multiSearchParameters,
+            Map<String, String> common_params) throws Exception {
+        // Create a shallow copy to safely enforce union=true without modifying the
+        // caller's original parameters.
+        MultiSearchSearchesParameter copiedParams = new MultiSearchSearchesParameter();
+        copiedParams.setSearches(multiSearchParameters.getSearches());
+        copiedParams.setUnion(true);
+
+        return this.apiCall.post(MultiSearch.RESOURCEPATH, copiedParams, common_params, SearchResult.class);
     }
 }

src/test/java/org/typesense/api/MultiSearchTest.java

@@ -7,14 +7,18 @@
 import org.typesense.model.Field;
 import org.typesense.model.MultiSearchCollectionParameters;
 import org.typesense.model.MultiSearchResult;
+import org.typesense.model.SearchResult;
 import org.typesense.model.MultiSearchSearchesParameter;
 
 import java.util.ArrayList;
 import java.util.HashMap;
+import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
+import java.util.Set;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
 
 class MultiSearchTest {
 
@@ -35,12 +39,23 @@ void setUp() throws Exception {
         CollectionSchema collectionSchema = new CollectionSchema();
         collectionSchema.name("embeddings").fields(fields);
         client.collections().create(collectionSchema);
+        // create another collection for union search
+        collectionSchema.name("embeddings-2").fields(fields);
+        client.collections().create(collectionSchema);
+
+        float[] vecVals = { 0.12f, 0.45f, 0.87f, 0.18f };
+        Map<String, Object> doc1 = new HashMap<>();
+        doc1.put("title", "Romeo and Juliet");
+        doc1.put("vec", vecVals);
+        doc1.put("source", "embeddings_1");
+        client.collections("embeddings").documents().create(doc1);
 
-        float[] vecVals = {0.12f, 0.45f, 0.87f, 0.18f};
-        Map<String, Object> doc = new HashMap<>();
-        doc.put("title", "Romeo and Juliet");
-        doc.put("vec", vecVals);
-        client.collections("embeddings").documents().create(doc);
+        // Document for the second collection
+        Map<String, Object> doc2 = new HashMap<>();
+        doc2.put("title", "Romeo and Juliet from collection 2");
+        doc2.put("vec", new float[] { 0.12f, 0.45f, 0.87f, 0.18f });
+        doc2.put("source", "embeddings_2");
+        client.collections("embeddings-2").documents().create(doc2);
     }
 
     @AfterEach
@@ -55,10 +70,36 @@ void testSearch() throws Exception {
         search1.setQ("*");
         search1.setVectorQuery("vec:([0.96826,0.94,0.39557,0.306488], k:10)");
 
-        MultiSearchSearchesParameter multiSearchParameters = new MultiSearchSearchesParameter().addSearchesItem(search1);
+        MultiSearchSearchesParameter multiSearchParameters = new MultiSearchSearchesParameter()
+                .addSearchesItem(search1);
         MultiSearchResult response = this.client.multiSearch.perform(multiSearchParameters, null);
         assertEquals(1, response.getResults().size());
         assertEquals(1, response.getResults().get(0).getHits().size());
         assertEquals("0", response.getResults().get(0).getHits().get(0).getDocument().get("id"));
     }
+
+    @Test
+    void testUnionSearch() throws Exception {
+        MultiSearchCollectionParameters search1 = new MultiSearchCollectionParameters();
+        search1.setCollection("embeddings");
+        search1.setQ("*");
+
+        MultiSearchCollectionParameters search2 = new MultiSearchCollectionParameters();
+        search2.setCollection("embeddings-2");
+        search2.setQ("*");
+
+        MultiSearchSearchesParameter multiSearchParameters = new MultiSearchSearchesParameter()
+                .addSearchesItem(search1).addSearchesItem(search2);
+        SearchResult response = this.client.multiSearch.performUnion(multiSearchParameters, null);
+
+        assertEquals(2, response.getHits().size());
+        assertEquals(2, response.getUnionRequestParams().size());
+
+        Set<String> sources = new HashSet<>();
+        sources.add((String) response.getHits().get(0).getDocument().get("source"));
+        sources.add((String) response.getHits().get(1).getDocument().get("source"));
+
+        assertTrue(sources.contains("embeddings_1"), "Results should contain a document from embeddings_1");
+        assertTrue(sources.contains("embeddings_2"), "Results should contain a document from embeddings_2");
+    }
 }