PPL options

Firestore/Source/API/FIRPipelineBridge.mm

@@ -20,6 +20,7 @@
 
 #include <memory>
 
+#import "Firestore/Source/API/FIRCollectionReference+Internal.h"
 #import "Firestore/Source/API/FIRDocumentReference+Internal.h"
 #import "Firestore/Source/API/FIRFieldPath+Internal.h"
 #import "Firestore/Source/API/FIRFirestore+Internal.h"
@@ -39,11 +40,13 @@
 #include "Firestore/core/src/api/pipeline_result.h"
 #include "Firestore/core/src/api/pipeline_snapshot.h"
 #include "Firestore/core/src/api/stages.h"
+#include "Firestore/core/src/util/comparison.h"
 #include "Firestore/core/src/util/error_apple.h"
 #include "Firestore/core/src/util/status.h"
 #include "Firestore/core/src/util/string_apple.h"
 
 using firebase::firestore::api::AddFields;
+using firebase::firestore::api::AddStage;
 using firebase::firestore::api::AggregateFunction;
 using firebase::firestore::api::AggregateStage;
 using firebase::firestore::api::CollectionGroupSource;
@@ -57,7 +60,6 @@
 using firebase::firestore::api::Field;
 using firebase::firestore::api::FindNearestStage;
 using firebase::firestore::api::FunctionExpr;
-using firebase::firestore::api::GenericStage;
 using firebase::firestore::api::LimitStage;
 using firebase::firestore::api::MakeFIRTimestamp;
 using firebase::firestore::api::OffsetStage;
@@ -73,13 +75,21 @@
 using firebase::firestore::api::Where;
 using firebase::firestore::model::FieldPath;
 using firebase::firestore::nanopb::SharedMessage;
+using firebase::firestore::util::ComparisonResult;
 using firebase::firestore::util::MakeCallback;
 using firebase::firestore::util::MakeNSString;
 using firebase::firestore::util::MakeString;
 using firebase::firestore::util::ThrowInvalidArgument;
 
 NS_ASSUME_NONNULL_BEGIN
 
+inline std::string EnsureLeadingSlash(const std::string &path) {
+  if (!path.empty() && path[0] == '/') {
+    return path;
+  }
+  return "/" + path;
+}
+
 @implementation FIRExprBridge
 @end
 
@@ -216,10 +226,19 @@ @implementation FIRCollectionSourceStageBridge {
   std::shared_ptr<CollectionSource> collection_source;
 }
 
-- (id)initWithPath:(NSString *)path {
+- (id)initWithRef:(FIRCollectionReference *)ref firestore:(FIRFirestore *)db {
   self = [super init];
   if (self) {
-    collection_source = std::make_shared<CollectionSource>(MakeString(path));
+    if (ref.firestore.databaseID.CompareTo(db.databaseID) != ComparisonResult::Same) {
+      ThrowInvalidArgument(
+          "Invalid CollectionReference. The project ID (\"%s\") or the database (\"%s\") does not "
+          "match "
+          "the project ID (\"%s\") and database (\"%s\") of the target database of this Pipeline.",
+          ref.firestore.databaseID.project_id(), ref.firestore.databaseID.database_id(),
+          db.databaseID.project_id(), db.databaseID.project_id());
+    }
+    collection_source =
+        std::make_shared<CollectionSource>(EnsureLeadingSlash(MakeString(ref.path)));
   }
   return self;
 }
@@ -270,12 +289,21 @@ @implementation FIRDocumentsSourceStageBridge {
   std::shared_ptr<DocumentsSource> cpp_document_source;
 }
 
-- (id)initWithDocuments:(NSArray<NSString *> *)documents {
+- (id)initWithDocuments:(NSArray<FIRDocumentReference *> *)documents firestore:(FIRFirestore *)db {
   self = [super init];
   if (self) {
     std::vector<std::string> cpp_documents;
-    for (NSString *doc in documents) {
-      cpp_documents.push_back(MakeString(doc));
+    for (FIRDocumentReference *doc in documents) {
+      if (doc.firestore.databaseID.CompareTo(db.databaseID) != ComparisonResult::Same) {
+        ThrowInvalidArgument("Invalid DocumentReference. The project ID (\"%s\") or the database "
+                             "(\"%s\") does not match "
+                             "the project ID (\"%s\") and database (\"%s\") of the target database "
+                             "of this Pipeline.",
+                             doc.firestore.databaseID.project_id(),
+                             doc.firestore.databaseID.database_id(), db.databaseID.project_id(),
+                             db.databaseID.project_id());
+      }
+      cpp_documents.push_back(EnsureLeadingSlash(MakeString(doc.path)));
     }
     cpp_document_source = std::make_shared<DocumentsSource>(std::move(cpp_documents));
   }
@@ -754,12 +782,12 @@ - (id)initWithField:(FIRExprBridge *)field indexField:(NSString *_Nullable)index
 
 @end
 
-@implementation FIRGenericStageBridge {
+@implementation FIRAddStageBridge {
   NSString *_name;
   NSArray<FIRExprBridge *> *_params;
   NSDictionary<NSString *, FIRExprBridge *> *_Nullable _options;
   Boolean isUserDataRead;
-  std::shared_ptr<GenericStage> cpp_generic_stage;
+  std::shared_ptr<AddStage> cpp_generic_stage;
 }
 
 - (id)initWithName:(NSString *)name
@@ -787,8 +815,8 @@ - (id)initWithName:(NSString *)name
         cpp_options[MakeString(key)] = [_options[key] cppExprWithReader:reader];
       }
     }
-    cpp_generic_stage = std::make_shared<GenericStage>(MakeString(_name), std::move(cpp_params),
-                                                       std::move(cpp_options));
+    cpp_generic_stage = std::make_shared<AddStage>(MakeString(_name), std::move(cpp_params),
+                                                   std::move(cpp_options));
   }
 
   isUserDataRead = YES;

Firestore/Source/Public/FirebaseFirestore/FIRPipelineBridge.h

@@ -70,7 +70,7 @@ NS_SWIFT_SENDABLE
 NS_SWIFT_NAME(CollectionSourceStageBridge)
 @interface FIRCollectionSourceStageBridge : FIRStageBridge
 
-- (id)initWithPath:(NSString *)path;
+- (id)initWithRef:(FIRCollectionReference *)ref firestore:(FIRFirestore *)db;
 
 @end
 
@@ -94,7 +94,7 @@ NS_SWIFT_SENDABLE
 NS_SWIFT_NAME(DocumentsSourceStageBridge)
 @interface FIRDocumentsSourceStageBridge : FIRStageBridge
 
-- (id)initWithDocuments:(NSArray<NSString *> *)documents;
+- (id)initWithDocuments:(NSArray<FIRDocumentReference *> *)documents firestore:(FIRFirestore *)db;
 
 @end
 
@@ -195,8 +195,8 @@ NS_SWIFT_NAME(UnnestStageBridge)
 @end
 
 NS_SWIFT_SENDABLE
-NS_SWIFT_NAME(GenericStageBridge)
-@interface FIRGenericStageBridge : FIRStageBridge
+NS_SWIFT_NAME(AddStageBridge)
+@interface FIRAddStageBridge : FIRStageBridge
 - (id)initWithName:(NSString *)name
             params:(NSArray<FIRExprBridge *> *)params
            options:(NSDictionary<NSString *, FIRExprBridge *> *_Nullable)options;

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,25 @@
+// 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.
+
+/// A container for providing arbitrary, backend-specific options to a pipeline.
+///
+/// Use this to pass options that are not explicitly defined in the other option structs.
+public struct CustomOptions: OptionProtocol {
+  var values: [String: Sendable]
+  /// Creates a set of custom options from a dictionary.
+  /// - Parameter values: A dictionary containing the custom options.
+  public init(_ values: [String: Sendable] = [:]) {
+    self.values = values
+  }
+}

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

@@ -0,0 +1,25 @@
+// 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.
+
+/// Specifies which indexes the pipeline should use for execution.
+public struct IndexMode: Sendable, Equatable, Hashable {
+  let rawValue: String
+
+  /// Use the set of indexes recommended by the backend.
+  public static let recommended = IndexMode(rawValue: "recommended")
+
+  init(rawValue: String) {
+    self.rawValue = rawValue
+  }
+}

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

@@ -0,0 +1,16 @@
+// 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.
+
+/// A protocol that all pipeline option types must conform to.
+public protocol OptionProtocol: Sendable {}

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

@@ -107,9 +107,19 @@ public struct Pipeline: @unchecked Sendable {
   /// }
   /// ```
   ///
+  /// - Parameters:
+  ///   - explainOptions: Configures the execution plan report for debugging and optimization. Use
+  /// it to analyze performance, get index recommendations, and control the verbosity and format of
+  /// the output.
+  ///   - indexMode: Specifies which indexes to use for the pipeline, such as the `.recommended`
+  /// set.
+  ///   - customOptions: A dictionary for passing any other backend-specific or advanced options to
+  /// the pipeline execution.
   /// - 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 {
@@ -147,7 +157,8 @@ public struct Pipeline: @unchecked Sendable {
   /// - Parameter field: The first field to add to the documents, specified as a `Selectable`.
   /// - Parameter additionalFields: Optional additional fields to add, specified as `Selectable`s.
   /// - Returns: A new `Pipeline` object with this stage appended.
-  public func addFields(_ field: Selectable, _ additionalFields: Selectable...) -> Pipeline {
+  public func addFields(_ field: Selectable, _ additionalFields: Selectable...,
+                        customOptions: [String: Sendable]? = nil) -> Pipeline {
     let fields = [field] + additionalFields
     return Pipeline(stages: stages + [AddFields(fields: fields)], db: db)
   }
@@ -699,7 +710,7 @@ public struct Pipeline: @unchecked Sendable {
   /// ```swift
   /// // let pipeline: Pipeline = ...
   /// // Example: Assuming a hypothetical backend stage "customFilterV2".
-  /// let genericPipeline = pipeline.genericStage(
+  /// let genericPipeline = pipeline.addStage(
   ///   name: "customFilterV2",
   ///   params: [Field("userScore"), 80], // Ordered parameters.
   ///   options: ["mode": "strict", "logLevel": 2]  // Optional named parameters.
@@ -712,10 +723,10 @@ public struct Pipeline: @unchecked Sendable {
   ///   - params: An array of ordered, `Sendable` parameters for the stage.
   ///   - options: Optional dictionary of named, `Sendable` parameters.
   /// - Returns: A new `Pipeline` object with this stage appended.
-  public func genericStage(name: String, params: [Sendable],
-                           options: [String: Sendable]? = nil) -> Pipeline {
+  public func addStage(name: String, params: [Sendable],
+                       options: [String: Sendable]? = nil) -> Pipeline {
     return Pipeline(
-      stages: stages + [GenericStage(name: name, params: params, options: options)],
+      stages: stages + [AddStage(name: name, params: params, options: options)],
       db: db
     )
   }

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

@@ -25,7 +25,7 @@ public struct PipelineSnapshot: Sendable {
   public let pipeline: Pipeline
 
   /// An array of all the results in the `PipelineSnapshot`.
-  let results_cache: [PipelineResult]
+  public let results: [PipelineResult]
 
   /// The time at which the pipeline producing this result was executed.
   public let executionTime: Timestamp
@@ -36,10 +36,6 @@ public struct PipelineSnapshot: Sendable {
     self.bridge = bridge
     self.pipeline = pipeline
     executionTime = self.bridge.execution_time
-    results_cache = self.bridge.results.map { PipelineResult($0) }
-  }
-
-  public func results() -> [PipelineResult] {
-    return results_cache
+    results = self.bridge.results.map { PipelineResult($0) }
   }
 }