feat(search): Client-level search method (#751)

Author: VladislavFitz

Sources/AlgoliaSearchClient/Client/Search/SearchClient+MultiIndex.swift

@@ -74,7 +74,7 @@ public extension SearchClient {
   /**
    Perform a search on several indices at the same time, with one method call.
 
-   - Parameter queries: The list of IndexedQuery objects mathcing index name and a query to execute on it.
+   - Parameter queries: The list of IndexedQuery objects matching index name and a query to execute on it.
    - Parameter strategy: The MultipleQueriesStrategy of the query.
    - Parameter requestOptions: Configure request locally with RequestOptions
    - Parameter completion: Result completion
@@ -91,7 +91,7 @@ public extension SearchClient {
   /**
    Perform a search on several indices at the same time, with one method call.
 
-   - Parameter queries: The list of IndexedQuery objects mathcing index name and a query to execute on it.
+   - Parameter queries: The list of IndexedQuery objects matching index name and a query to execute on it.
    - Parameter strategy: The MultipleQueriesStrategy of the query.
    - Parameter requestOptions: Configure request locally with RequestOptions
    - Returns: SearchesResponse object
@@ -103,6 +103,39 @@ public extension SearchClient {
     return try execute(command)
   }
 
+  /**
+   Perform a search for hits or facet values on several indices at the same time, with one method call.
+   
+   - Parameter queries: The list of MultiSearchQuery objects encapsulating either IndexedQuery or IndexedFacetQuery.
+   - Parameter strategy: The MultipleQueriesStrategy of the query.
+   - Parameter requestOptions: Configure request locally with RequestOptions
+   - Parameter completion: Result completion
+   - Returns: Launched asynchronous operation
+   */
+  @discardableResult func search(queries: [MultiSearchQuery],
+                                 strategy: MultipleQueriesStrategy = .none,
+                                 requestOptions: RequestOptions? = nil,
+                                 completion: @escaping ResultCallback<MultiSearchResponse>) -> Operation {
+    let command = Command.MultipleIndex.Queries(queries: queries, strategy: strategy, requestOptions: requestOptions)
+    return execute(command, completion: completion)
+  }
+
+  /**
+   Perform a search for hits or facet values on several indices at the same time, with one method call.
+
+   - Parameter queries: The list of MultiSearchQuery objects encapsulating either IndexedQuery or IndexedFacetQuery.
+   - Parameter strategy: The MultipleQueriesStrategy of the query.
+   - Parameter requestOptions: Configure request locally with RequestOptions
+   - Parameter completion: Result completion
+   - Returns: MultiSearchResponse object
+   */
+  @discardableResult func search(queries: [MultiSearchQuery],
+                                 strategy: MultipleQueriesStrategy = .none,
+                                 requestOptions: RequestOptions? = nil) throws -> MultiSearchResponse {
+    let command = Command.MultipleIndex.Queries(queries: queries, strategy: strategy, requestOptions: requestOptions)
+    return try execute(command)
+  }
+
   // MARK: - Multiple get objects
 
   /**

Sources/AlgoliaSearchClient/Command/Command+MultipleIndex.swift

@@ -46,12 +46,31 @@ extension Command {
       let body: Data?
       let requestOptions: RequestOptions?
 
-      init(indexName: IndexName, queries: [Query], strategy: MultipleQueriesStrategy = .none, requestOptions: RequestOptions?) {
-        let queries = queries.map { IndexedQuery(indexName: indexName, query: $0) }
-        self.init(queries: queries, strategy: strategy, requestOptions: requestOptions)
+      init(indexName: IndexName,
+           queries: [Query],
+           strategy: MultipleQueriesStrategy = .none,
+           requestOptions: RequestOptions?) {
+        let queries = queries
+          .map { IndexedQuery(indexName: indexName, query: $0) }
+          .map(MultiSearchQuery.init)
+        self.init(queries: queries,
+                  strategy: strategy,
+                  requestOptions: requestOptions)
       }
+      
+      init(queries: [IndexedQuery],
+           strategy: MultipleQueriesStrategy = .none,
+           requestOptions: RequestOptions?) {
+        let queries = queries.map(MultiSearchQuery.init)
+        self.init(queries: queries,
+                  strategy: strategy,
+                  requestOptions: requestOptions)
+      }
+
 
-      init(queries: [IndexedQuery], strategy: MultipleQueriesStrategy = .none, requestOptions: RequestOptions?) {
+      init(queries: [MultiSearchQuery],
+           strategy: MultipleQueriesStrategy = .none,
+           requestOptions: RequestOptions?) {
         self.requestOptions = requestOptions
         self.body = MultipleQueriesRequest(requests: queries, strategy: strategy).httpBody
         self.path = (.indexesV1 >>> .multiIndex >>> .queries)

Sources/AlgoliaSearchClient/Models/Search/MultipleIndex/IndexedFacetQuery.swift

@@ -0,0 +1,63 @@
+//
+//  IndexedFacetQuery.swift
+//  
+//
+//  Created by Vladislav Fitc on 05/11/2021.
+//
+
+import Foundation
+
+/// The composition of search for facet values parameters with an associated index name
+public struct IndexedFacetQuery {
+  
+  /// The name of the index to search in.
+  public let indexName: IndexName
+  
+  /// The attribute to facet on.
+  public let attribute: Attribute
+  
+  /// The query to filter results.
+  public let query: Query
+  
+  /// The textual query used to search for facets.
+  public let facetQuery: String
+    
+  /**
+   - Parameter indexName: The name of the index to search in
+   - Parameter attribute: The Attribute to facet on.
+   - Parameter query: The Query to filter results.
+   - Parameter facetQuery: The textual query used to search for facets.
+   */
+  public init(indexName: IndexName,
+              attribute: Attribute,
+              facetQuery: String,
+              query: Query) {
+    self.indexName = indexName
+    self.attribute = attribute
+    self.facetQuery = facetQuery
+    var parameters = query.customParameters ?? [:]
+    parameters["facetQuery"] = .init(facetQuery)
+    self.query = query.set(\.customParameters, to: parameters)
+  }
+  
+}
+
+extension IndexedFacetQuery: Encodable {
+  
+  enum CodingKeys: String, CodingKey {
+    case indexName
+    case query = "params"
+    case type
+    case facet
+    case facetQuery
+  }
+  
+  public func encode(to encoder: Encoder) throws {
+    var container = encoder.container(keyedBy: CodingKeys.self)
+    try container.encode(indexName, forKey: .indexName)
+    try container.encode(query.urlEncodedString, forKey: .query)
+    try container.encode(attribute, forKey: .facet)
+    try container.encode("facet", forKey: .type)
+  }
+
+}

Sources/AlgoliaSearchClient/Models/Search/MultipleIndex/IndexedQuery.swift

@@ -7,16 +7,22 @@
 
 import Foundation
 
+/// The composition of search parameters with an associated index name
 public struct IndexedQuery {
-
+  
+  /// The name of the index to search in.
   public let indexName: IndexName
+  
+  /// The Query to filter results.
   public let query: Query
-
+  
+  /// - parameter indexName: The name of the index to search in.
+  /// - parameter query: The Query to filter results.
   public init(indexName: IndexName, query: Query) {
     self.indexName = indexName
     self.query = query
   }
-
+  
 }
 
 extension IndexedQuery: Codable {

Sources/AlgoliaSearchClient/Models/Search/MultipleIndex/MultiSearchQuery.swift

@@ -0,0 +1,43 @@
+//
+//  MultiSearchQuery.swift
+//  
+//
+//  Created by Vladislav Fitc on 05/11/2021.
+//
+
+import Foundation
+
+/// Polymorphic wrapper for either and IndexedQuery or an IndexedFacetQuery to perform a multi-index search
+public enum MultiSearchQuery {
+  
+  case hitsSearch(IndexedQuery)
+  case facetsSearch(IndexedFacetQuery)
+  
+  /**
+   - Parameter indexedQuery: The IndexedQuery to wrap
+   */
+  public init(_ indexedQuery: IndexedQuery) {
+    self = .hitsSearch(indexedQuery)
+  }
+  
+  /**
+   - Parameter indexedFacetQuery: The IndexedFacetQuery to wrap
+   */
+  public init(_ indexedFacetQuery: IndexedFacetQuery) {
+    self = .facetsSearch(indexedFacetQuery)
+  }
+  
+}
+
+extension MultiSearchQuery: Encodable {
+  
+  public func encode(to encoder: Encoder) throws {
+    switch self {
+    case .facetsSearch(let facetsSearch):
+      try facetsSearch.encode(to: encoder)
+    case .hitsSearch(let hitsSearch):
+      try hitsSearch.encode(to: encoder)
+    }
+  }
+  
+}

Sources/AlgoliaSearchClient/Models/Search/MultipleIndex/MultipleQueriesRequest.swift

@@ -9,24 +9,18 @@ import Foundation
 
 struct MultipleQueriesRequest {
 
-  let requests: [IndexedQuery]
+  let requests: [MultiSearchQuery]
   let strategy: MultipleQueriesStrategy
 
 }
 
-extension MultipleQueriesRequest: Codable {
+extension MultipleQueriesRequest: Encodable {
 
   enum CodingKeys: String, CodingKey {
     case requests
     case strategy
   }
 
-  init(from decoder: Decoder) throws {
-    let container = try decoder.container(keyedBy: CodingKeys.self)
-    self.requests = try container.decode(forKey: .requests)
-    self.strategy = try container.decodeIfPresent(forKey: .strategy) ?? .none
-  }
-
   func encode(to encoder: Encoder) throws {
     var container = encoder.container(keyedBy: CodingKeys.self)
     try container.encode(requests, forKey: .requests)

Sources/AlgoliaSearchClient/Models/Search/Response/MultiSearchResponse.swift

@@ -0,0 +1,89 @@
+//
+//  MultiSearchResponse.swift
+//  
+//
+//  Created by Vladislav Fitc on 21/07/2021.
+//
+
+import Foundation
+
+/// Wraps the list of multi search results (either FacetSearchResponse or SearchResponse)
+public struct MultiSearchResponse: Codable {
+
+  /// List of result in the order they were submitted, one element for each IndexedQuery.
+  public var results: [Response]
+
+  /// - parameter results: List of result in the order they were submitted, one element for each IndexedQuery.
+  public init(results: [Response]) {
+    self.results = results
+  }
+
+}
+
+public extension MultiSearchResponse {
+
+  /// Container for either FacetSearchResponse or SearchResponse
+  enum Response: Codable {
+
+    case facets(FacetSearchResponse)
+    case hits(SearchResponse)
+
+    public var facetsResponse: FacetSearchResponse? {
+      if case .facets(let response) = self {
+        return response
+      } else {
+        return .none
+      }
+    }
+
+    public var hitsResponse: SearchResponse? {
+      if case .hits(let response) = self {
+        return response
+      } else {
+        return .none
+      }
+    }
+
+    public init(from decoder: Decoder) throws {
+      do {
+        let searchResponse = try SearchResponse(from: decoder)
+        self = .hits(searchResponse)
+      } catch let searchResponseError {
+        do {
+          let facetSearchResponse = try FacetSearchResponse(from: decoder)
+          self = .facets(facetSearchResponse)
+        } catch let facetSearchResponseError {
+          throw DecodingError(searchResponseDecodingError: searchResponseError,
+                              facetSearchResponseDecodingError: facetSearchResponseError)
+        }
+      }
+    }
+
+    public func encode(to encoder: Encoder) throws {
+      switch self {
+      case .facets(let response):
+        try response.encode(to: encoder)
+      case .hits(let response):
+        try response.encode(to: encoder)
+      }
+    }
+
+    public struct DecodingError: Error {
+
+      /// Error occured while search response decoding
+      public let searchResponseDecodingError: Error
+
+      /// Error occured while facets search response decoding
+      public let facetSearchResponseDecodingError: Error
+
+      init(searchResponseDecodingError: Error,
+           facetSearchResponseDecodingError: Error) {
+        self.searchResponseDecodingError = searchResponseDecodingError
+        self.facetSearchResponseDecodingError = facetSearchResponseDecodingError
+      }
+
+    }
+
+  }
+
+}

Sources/AlgoliaSearchClient/Models/Task/Index/IndexedTask.swift

@@ -9,7 +9,7 @@ import Foundation
 
 public struct IndexedTask: Task {
 
-  /// The IndexName this task is running on.
+  /// The name of the index this task is running on.
   public let indexName: IndexName
 
   /// The TaskID which can be used with the .waitTask method.

Tests/AlgoliaSearchClientTests/Integration/PersonalizationIntegrationTests.swift

@@ -19,7 +19,7 @@ class PersonalizationIntegrationTests: IntegrationTestCase {
   }
 
   func getStrategy() throws {
-    let recommendationClient = PersonalizationClient(appID: client.applicationID, apiKey: client.apiKey, region: .custom("eu"))
+    let recommendationClient = PersonalizationClient(appID: client.applicationID, apiKey: client.apiKey, region: .custom("us"))
     let _ = try recommendationClient.getPersonalizationStrategy()
   }
 

Tests/AlgoliaSearchClientTests/Unit/Command/MultiIndexCommandTest.swift

@@ -35,13 +35,18 @@ class MultiIndexCommandTest: XCTestCase, AlgoliaCommandTest {
   }
 
   func testQueries() {
-    let command = Command.MultipleIndex.Queries(queries: [.init(indexName: "index0", query: "query0"), .init(indexName: "index1", query: "query1")], strategy: .stopIfEnoughMatches, requestOptions: test.requestOptions)
+    let command = Command.MultipleIndex.Queries(queries: [
+      IndexedQuery(indexName: "index0", query: "query0"),
+      IndexedQuery(indexName: "index1", query: "query1")
+    ],
+                                                strategy: .stopIfEnoughMatches,
+                                                requestOptions: test.requestOptions)
     check(command: command,
           callType: .read,
           method: .post,
           urlPath: "/1/indexes/*/queries",
           queryItems: [.init(name: "testParameter", value: "testParameterValue")],
-          body: MultipleQueriesRequest(requests: [.init(indexName: "index0", query: "query0"), .init(indexName: "index1", query: "query1")], strategy: .stopIfEnoughMatches).httpBody,
+          body: MultipleQueriesRequest(requests: [.init(IndexedQuery(indexName: "index0", query: "query0")), .init(IndexedQuery(indexName: "index1", query: "query1"))], strategy: .stopIfEnoughMatches).httpBody,
           requestOptions: test.requestOptions)
   }