first draft

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

@@ -0,0 +1,65 @@
+public protocol OptionProtocol: Sendable {}
+
+public struct ExplainOptions: OptionProtocol {
+  public var mode: String = ""
+  public var outputFormat: String = ""
+  public var verbosity: String = ""
+  public var indexRecommendation: Bool = false
+  public var profiles: String = ""
+  public var redact: Bool = false
+
+  public init(mode: String = "",
+              outputFormat: String = "",
+              verbosity: String = "",
+              indexRecommendation: Bool = false,
+              profiles: String = "",
+              redact: Bool = false) {
+    self.mode = mode
+    self.outputFormat = outputFormat
+    self.verbosity = verbosity
+    self.indexRecommendation = indexRecommendation
+    self.profiles = profiles
+    self.redact = redact
+  }
+}
+
+public struct GenericOptions: OptionProtocol {
+  var values: [String: Sendable]
+  public init(_ values: [String: Sendable] = [:]) {
+    self.values = values
+  }
+}
+
+public struct IndexMode: OptionProtocol {
+  var values: String
+  public init(_ values: String) {
+    self.values = values
+  }
+}
+
+@resultBuilder
+public struct OptionBuilder {
+  public static func buildBlock(_ components: [OptionProtocol]...) -> [OptionProtocol] {
+    components.flatMap { $0 }
+  }
+
+  public static func buildOptional(_ components: [OptionProtocol]?) -> [OptionProtocol] {
+    components ?? []
+  }
+
+  public static func buildExpression(_ components: OptionProtocol) -> [OptionProtocol] {
+    [components]
+  }
+
+  public static func buildExpression(_ components: [OptionProtocol]) -> [OptionProtocol] {
+    components
+  }
+
+  public static func buildEither(first components: [OptionProtocol]) -> [OptionProtocol] {
+    components
+  }
+
+  public static func buildEither(second components: [OptionProtocol]) -> [OptionProtocol] {
+    components
+  }
+}

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

@@ -109,7 +109,22 @@ 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(@OptionBuilder options: () -> [OptionProtocol] = { [] }) async throws
+    -> PipelineSnapshot {
+    return try await withCheckedThrowingContinuation { continuation in
+      self.bridge.execute { result, error in
+        if let error {
+          continuation.resume(throwing: error)
+        } else {
+          continuation.resume(returning: PipelineSnapshot(result!, pipeline: self))
+        }
+      }
+    }
+  }
+
+  public func execute2(explainOptions: ExplainOptions? = nil,
+                       indexMode: String? = nil,
+                       genericOptions: GenericOptions? = 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

@@ -37,6 +37,57 @@ final class PipelineTests: FSTIntegrationTestCase {
     let _: PipelineSnapshot = try await pipeline.execute()
   }
 
+  func testPipelineOptions() async throws {
+    let pipelineSource: PipelineSource = db.pipeline()
+
+    let pipeline: Pipeline = pipelineSource.documents(
+      [db.collection("foo").document("bar"), db.document("foo/baz")]
+    )
+
+    let developmentModeEnabled = true
+
+    let _: PipelineSnapshot = try await pipeline.execute {
+      // Use different options under different scenarios
+      if developmentModeEnabled {
+        ExplainOptions(
+          mode: "analyze",
+          outputFormat: "json",
+          verbosity: "execution_tree",
+          indexRecommendation: true,
+          profiles: "bytes_throughput",
+          redact: false
+        )
+        IndexMode("recommended")
+      } else {
+        GenericOptions(
+          ["option_not_known_to_sdk": true]
+        )
+      }
+
+      // Default options
+      GenericOptions(
+        ["option_not_known_to_sdk": true]
+      )
+    }
+
+    let _: PipelineSnapshot = try await pipeline.execute2(
+      // Use different options under different scenarios
+      explainOptions:
+      ExplainOptions(
+        mode: "analyze",
+        outputFormat: "json",
+        verbosity: "execution_tree",
+        indexRecommendation: true,
+        profiles: "bytes_throughput",
+        redact: false
+      ),
+      indexMode: "recommended",
+      genericOptions: GenericOptions(
+        ["option_not_known_to_sdk": true]
+      )
+    )
+  }
+
   func testWhereStage() async throws {
     _ = db.pipeline().collection("books")
       .where(