add option api

Author: cherylEnkidu

Firestore/Swift/Source/SwiftAPI/Pipeline/Options/ExplainOptions.swift

@@ -0,0 +1,83 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+public struct ExplainOptions: OptionProtocol, Sendable, Equatable, Hashable {
+  public struct Mode: Sendable, Equatable, Hashable {
+    let rawValue: String
+
+    public static let execute = Mode(rawValue: "execute")
+    public static let explain = Mode(rawValue: "explain")
+    public static let analyze = Mode(rawValue: "analyze")
+
+    init(rawValue: String) {
+      self.rawValue = rawValue
+    }
+  }
+
+  public struct OutputFormat: Sendable, Equatable, Hashable {
+    let rawValue: String
+
+    public static let text = OutputFormat(rawValue: "text")
+    public static let json = OutputFormat(rawValue: "json")
+    public static let `struct` = OutputFormat(rawValue: "struct")
+
+    init(rawValue: String) {
+      self.rawValue = rawValue
+    }
+  }
+
+  public struct Verbosity: Sendable, Equatable, Hashable {
+    let rawValue: String
+
+    public static let summaryOnly = Verbosity(rawValue: "summary_only")
+    public static let executionTree = Verbosity(rawValue: "execution_tree")
+
+    init(rawValue: String) {
+      self.rawValue = rawValue
+    }
+  }
+
+  public struct Profiles: Sendable, Equatable, Hashable {
+    let rawValue: String
+
+    public static let latency = Profiles(rawValue: "latency")
+    public static let recordsCount = Profiles(rawValue: "records_count")
+    public static let bytesThroughput = Profiles(rawValue: "bytes_throughput")
+
+    init(rawValue: String) {
+      self.rawValue = rawValue
+    }
+  }
+
+  public let mode: Mode?
+  public let outputFormat: OutputFormat?
+  public let verbosity: Verbosity?
+  public let indexRecommendation: Bool?
+  public let profiles: Profiles?
+  public let redact: Bool?
+
+  public init(mode: Mode? = nil,
+              outputFormat: OutputFormat? = nil,
+              verbosity: Verbosity? = nil,
+              indexRecommendation: Bool? = nil,
+              profiles: Profiles? = nil,
+              redact: Bool? = nil) {
+    self.mode = mode
+    self.outputFormat = outputFormat
+    self.verbosity = verbosity
+    self.indexRecommendation = indexRecommendation
+    self.profiles = profiles
+    self.redact = redact
+  }
+}

Firestore/Swift/Source/SwiftAPI/Pipeline/Options/GenericOptions.swift

@@ -0,0 +1,20 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+public struct CustomOptions: OptionProtocol {
+  var values: [String: Sendable]
+  public init(_ values: [String: Sendable] = [:]) {
+    self.values = values
+  }
+}

Firestore/Swift/Source/SwiftAPI/Pipeline/Options/IndexMode.swift

@@ -0,0 +1,23 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+public struct IndexMode: Sendable, Equatable, Hashable {
+  let rawValue: String
+
+  public static let recommended = IndexMode(rawValue: "recommended")
+
+  init(rawValue: String) {
+    self.rawValue = rawValue
+  }
+}

Firestore/Swift/Source/SwiftAPI/Pipeline/Options/OptionProtocol.swift

@@ -0,0 +1,15 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+public protocol OptionProtocol: Sendable {}

Firestore/Swift/Source/SwiftAPI/Pipeline/Pipeline.swift

@@ -109,7 +109,9 @@ public struct Pipeline: @unchecked Sendable {
   ///
   /// - Throws: An error if the pipeline execution fails on the backend.
   /// - Returns: A `PipelineSnapshot` containing the result of the pipeline execution.
-  public func execute() async throws -> PipelineSnapshot {
+  public func execute(explainOptions: ExplainOptions? = nil,
+                      indexMode: IndexMode? = nil,
+                      customOptions: CustomOptions? = nil) async throws -> PipelineSnapshot {
     return try await withCheckedThrowingContinuation { continuation in
       self.bridge.execute { result, error in
         if let error {

Firestore/Swift/Tests/Integration/PipelineApiTests.swift

@@ -401,4 +401,24 @@ final class PipelineTests: FSTIntegrationTestCase {
     // Create a generic AggregateFunction for use where AggregateFunction is required
     let mySum = AggregateFunction("sum", [Field("price")])
   }
+
+  func testOption() async throws {
+    let _: PipelineSnapshot = try await db.pipeline().database().execute(
+      explainOptions:
+      ExplainOptions(
+        mode: .analyze,
+        outputFormat: .json,
+        verbosity: .executionTree,
+        indexRecommendation: true,
+        profiles: .bytesThroughput,
+        redact: false
+      ),
+      indexMode: .recommended,
+      customOptions: CustomOptions(
+        ["option_not_known_to_sdk": true,
+         "explain_options.new_explain_option": "any value here",
+         "explain_options.mode": "newServerKnownMode"]
+      )
+    )
+  }
 }