Skip to content

Commit 94cc75f

Browse files
cherylEnkiducherylEnkidu
committed
address feedbacks
1 parent b6ab3a0 commit 94cc75f

File tree

3 files changed

+52
-173
lines changed

3 files changed

+52
-173
lines changed

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

Lines changed: 16 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -22,32 +22,31 @@
2222
import Foundation
2323

2424
@objc public extension Firestore {
25-
/// Creates a `PipelineSource` that can be used to build and execute a pipeline of operations on
26-
/// the Firestore database.
25+
/// Creates a new `PipelineSource` to build and execute a data pipeline.
2726
///
28-
/// A pipeline is a sequence of stages that are executed in order. Each stage can perform an
29-
/// operation on the data, such as filtering, sorting, or transforming it.
27+
/// A pipeline is composed of a sequence of stages. Each stage processes the
28+
/// output from the previous one, and the final stage's output is the result of the
29+
/// pipeline's execution.
3030
///
3131
/// Example usage:
3232
/// ```swift
33-
/// let db = Firestore.firestore()
34-
/// let pipeline = db.pipeline()
33+
/// let pipeline = firestore.pipeline()
3534
/// .collection("books")
3635
/// .where(Field("rating").isGreaterThan(4.5))
37-
/// .sort([Field("rating").descending()])
36+
/// .sort(Field("rating").descending())
3837
/// .limit(2)
39-
///
40-
/// do {
41-
/// let snapshot = try await pipeline.execute()
42-
/// for doc in snapshot.results {
43-
/// print(doc.data())
44-
/// }
45-
/// } catch {
46-
/// print("Error executing pipeline: \(error)")
47-
/// }
4838
/// ```
4939
///
50-
/// - Returns: A `PipelineSource` that can be used to build and execute a pipeline.
40+
/// Note on Execution: The stages are conceptual. The Firestore backend may
41+
/// optimize execution (e.g., reordering or merging stages) as long as the
42+
/// final result remains the same.
43+
///
44+
/// Important Limitations:
45+
/// - Pipelines operate on a request/response basis only.
46+
/// - They do not utilize or update the local SDK cache.
47+
/// - They do not support realtime snapshot listeners.
48+
///
49+
/// - Returns: A `PipelineSource` to begin defining the pipeline's stages.
5150
@available(iOS 13, tvOS 13, macOS 10.15, macCatalyst 13, watchOS 7, *)
5251
@nonobjc func pipeline() -> PipelineSource {
5352
return PipelineSource(db: self) { stages, db in

‎Firestore/Swift/Source/SwiftAPI/Pipeline/Expressions/Expression.swift‎

Lines changed: 36 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -465,84 +465,96 @@ public protocol Expression: Sendable {
465465
/// than the given expression.
466466
///
467467
/// - Parameter other: The expression to compare against.
468-
/// - Returns: A `BooleanExpression` that can be used in `where` clauses.
468+
/// - Returns: A `BooleanExpression` that can be used in a where stage, together with other
469+
/// boolean expressions.
469470
func greaterThan(_ other: Expression) -> BooleanExpression
470471

471472
/// Creates a `BooleanExpression` that returns `true` if this expression is greater
472473
/// than the given value.
473474
///
474475
/// - Parameter other: The value to compare against.
475-
/// - Returns: A `BooleanExpression` that can be used in `where` clauses.
476+
/// - Returns: A `BooleanExpression` that can be used in a where stage, together with other
477+
/// boolean expressions.
476478
func greaterThan(_ other: Sendable) -> BooleanExpression
477479

478480
/// Creates a `BooleanExpression` that returns `true` if this expression is
479481
/// greater than or equal to the given expression.
480482
///
481483
/// - Parameter other: The expression to compare against.
482-
/// - Returns: A `BooleanExpression` that can be used in `where` clauses.
484+
/// - Returns: A `BooleanExpression` that can be used in a where stage, together with other
485+
/// boolean expressions.
483486
func greaterThanOrEqual(_ other: Expression) -> BooleanExpression
484487

485488
/// Creates a `BooleanExpression` that returns `true` if this expression is
486489
/// greater than or equal to the given value.
487490
///
488491
/// - Parameter other: The value to compare against.
489-
/// - Returns: A `BooleanExpression` that can be used in `where` clauses.
492+
/// - Returns: A `BooleanExpression` that can be used in a where stage, together with other
493+
/// boolean expressions.
490494
func greaterThanOrEqual(_ other: Sendable) -> BooleanExpression
491495

492496
/// Creates a `BooleanExpression` that returns `true` if this expression is less
493497
/// than the given expression.
494498
///
495499
/// - Parameter other: The expression to compare against.
496-
/// - Returns: A `BooleanExpression` that can be used in `where` clauses.
500+
/// - Returns: A `BooleanExpression` that can be used in a where stage, together with other
501+
/// boolean expressions.
497502
func lessThan(_ other: Expression) -> BooleanExpression
498503

499504
/// Creates a `BooleanExpression` that returns `true` if this expression is less
500505
/// than the given value.
501506
///
502507
/// - Parameter other: The value to compare against.
503-
/// - Returns: A `BooleanExpression` that can be used in `where` clauses.
508+
/// - Returns: A `BooleanExpression` that can be used in a where stage, together with other
509+
/// boolean expressions.
504510
func lessThan(_ other: Sendable) -> BooleanExpression
505511

506512
/// Creates a `BooleanExpression` that returns `true` if this expression is less
507513
/// than or equal to the given expression.
508514
///
509515
/// - Parameter other: The expression to compare against.
510-
/// - Returns: A `BooleanExpression` that can be used in `where` clauses.
516+
/// - Returns: A `BooleanExpression` that can be used in a where stage, together with other
517+
/// boolean expressions.
511518
func lessThanOrEqual(_ other: Expression) -> BooleanExpression
512519

513520
/// Creates a `BooleanExpression` that returns `true` if this expression is less
514521
/// than or equal to the given value.
515522
///
516523
/// - Parameter other: The value to compare against.
517-
/// - Returns: A `BooleanExpression` that can be used in `where` clauses.
524+
/// - Returns: A `BooleanExpression` that can be used in a where stage, together with other
525+
/// boolean expressions.
518526
func lessThanOrEqual(_ other: Sendable) -> BooleanExpression
519527

520528
/// Creates a `BooleanExpression` that returns `true` if this expression is equal
521529
/// to the given expression.
522530
///
523531
/// - Parameter other: The expression to compare against.
524-
/// - Returns: A `BooleanExpression` that can be used in `where` clauses.
532+
/// - Returns: A `BooleanExpression` that can be used in a where stage, together with other
533+
/// boolean expressions.
525534
func equal(_ other: Expression) -> BooleanExpression
526535

527536
/// Creates a `BooleanExpression` that returns `true` if this expression is equal
528537
/// to the given value.
529538
///
530539
/// - Parameter other: The value to compare against.
531-
/// - Returns: A `BooleanExpression` that can be used in `where` clauses.
540+
/// - Returns: A `BooleanExpression` that can be used in a where stage, together with other
541+
/// boolean expressions.
532542
func equal(_ other: Sendable) -> BooleanExpression
533543

534544
/// Creates a `BooleanExpression` that returns `true` if this expression is not
535545
/// equal to the given expression.
536546
///
537547
/// - Parameter other: The expression to compare against.
538-
/// - Returns: A `BooleanExpression` that can be used in `where` clauses.
548+
/// - Returns: A `BooleanExpression` that can be used in a where stage, together with other
549+
/// boolean expressions.
539550
func notEqual(_ other: Expression) -> BooleanExpression
540551

541552
/// Creates a `BooleanExpression` that returns `true` if this expression is not
542553
/// equal to the given value.
543554
///
544555
/// - Parameter other: The value to compare against.
545-
/// - Returns: A `BooleanExpression` that can be used in `where` clauses.
556+
/// - Returns: A `BooleanExpression` that can be used in a where stage, together with other
557+
/// boolean expressions.
546558
func notEqual(_ other: Sendable) -> BooleanExpression
547559

548560
/// Creates an expression that checks if this expression is equal to any of the provided
@@ -554,7 +566,8 @@ public protocol Expression: Sendable {
554566
/// ```
555567
///
556568
/// - Parameter others: An array of at least one `Expression` value to check against.
557-
/// - Returns: A `BooleanExpression` that can be used in `where` clauses.
569+
/// - Returns: A `BooleanExpression` that can be used in a where stage, together with other
570+
/// boolean expressions.
558571
func equalAny(_ others: [Expression]) -> BooleanExpression
559572

560573
/// Creates an expression that checks if this expression is equal to any of the provided literal
@@ -566,7 +579,8 @@ public protocol Expression: Sendable {
566579
/// ```
567580
///
568581
/// - Parameter others: An array of at least one `Sendable` literal value to check against.
569-
/// - Returns: A `BooleanExpression` that can be used in `where` clauses.
582+
/// - Returns: A `BooleanExpression` that can be used in a where stage, together with other
583+
/// boolean expressions.
570584
func equalAny(_ others: [Sendable]) -> BooleanExpression
571585

572586
/// Creates an expression that checks if this expression is equal to any of the provided
@@ -578,7 +592,8 @@ public protocol Expression: Sendable {
578592
/// ```
579593
///
580594
/// - Parameter arrayExpression: An `Expression` elements evaluated to be array.
581-
/// - Returns: A `BooleanExpression` that can be used in `where` clauses.
595+
/// - Returns: A `BooleanExpression` that can be used in a where stage, together with other
596+
/// boolean expressions.
582597
func equalAny(_ arrayExpression: Expression) -> BooleanExpression
583598

584599
/// Creates an expression that checks if this expression is not equal to any of the provided
@@ -590,7 +605,8 @@ public protocol Expression: Sendable {
590605
/// ```
591606
///
592607
/// - Parameter others: An array of at least one `Expression` value to check against.
593-
/// - Returns: A `BooleanExpression` that can be used in `where` clauses.
608+
/// - Returns: A `BooleanExpression` that can be used in a where stage, together with other
609+
/// boolean expressions.
594610
func notEqualAny(_ others: [Expression]) -> BooleanExpression
595611

596612
/// Creates an expression that checks if this expression is not equal to any of the provided
@@ -602,7 +618,8 @@ public protocol Expression: Sendable {
602618
/// ```
603619
///
604620
/// - Parameter others: An array of at least one `Sendable` literal value to check against.
605-
/// - Returns: A `BooleanExpression` that can be used in `where` clauses.
621+
/// - Returns: A `BooleanExpression` that can be used in a where stage, together with other
622+
/// boolean expressions.
606623
func notEqualAny(_ others: [Sendable]) -> BooleanExpression
607624

608625
/// Creates an expression that checks if this expression is equal to any of the provided
@@ -614,7 +631,8 @@ public protocol Expression: Sendable {
614631
/// ```
615632
///
616633
/// - Parameter arrayExpression: An `Expression` elements evaluated to be array.
617-
/// - Returns: A `BooleanExpression` that can be used in `where` clauses.
634+
/// - Returns: A `BooleanExpression` that can be used in a where stage, together with other
635+
/// boolean expressions.
618636
func notEqualAny(_ arrayExpression: Expression) -> BooleanExpression
619637

620638
/// Creates an expression that checks if this expression evaluates to "NaN" (Not a Number).

‎Firestore/Swift/Tests/Integration/PipelineTests.swift‎

Lines changed: 0 additions & 138 deletions
Original file line numberDiff line numberDiff line change
@@ -3503,144 +3503,6 @@ class PipelineIntegrationTests: FSTIntegrationTestCase {
35033503
}
35043504
}
35053505

3506-
// func testReplaceFirst() async throws {
3507-
// try XCTSkipIf(true, "Skip this test since backend has not yet supported.")
3508-
// let collRef = collectionRef(withDocuments: bookDocs)
3509-
// let db = collRef.firestore
3510-
//
3511-
// let pipeline = db.pipeline()
3512-
// .collection(collRef.path)
3513-
// .where(Field("title").equal("The Lord of the Rings"))
3514-
// .limit(1)
3515-
// .select([Field("title").replaceFirst("o", with: "0").as("newName")])
3516-
// let snapshot = try await pipeline.execute()
3517-
// TestHelper.compare(
3518-
// snapshot: snapshot,
3519-
// expected: [["newName": "The L0rd of the Rings"]],
3520-
// enforceOrder: false
3521-
// )
3522-
// }
3523-
3524-
// func testStringReplace() async throws {
3525-
// try XCTSkipIf(true, "Skip this test since backend has not yet supported.")
3526-
// let collRef = collectionRef(withDocuments: bookDocs)
3527-
// let db = collRef.firestore
3528-
//
3529-
// let pipeline = db.pipeline()
3530-
// .collection(collRef.path)
3531-
// .where(Field("title").equal("The Lord of the Rings"))
3532-
// .limit(1)
3533-
// .select([Field("title").stringReplace("o", with: "0").as("newName")])
3534-
// let snapshot = try await pipeline.execute()
3535-
// TestHelper.compare(
3536-
// snapshot: snapshot,
3537-
// expected: [["newName": "The L0rd 0f the Rings"]],
3538-
// enforceOrder: false
3539-
// )
3540-
// }
3541-
3542-
// func testBitAnd() async throws {
3543-
// try XCTSkipIf(true, "Skip this test since backend has not yet supported.")
3544-
// let db = firestore()
3545-
// let randomCol = collectionRef()
3546-
// try await randomCol.document("dummyDoc").setData(["field": "value"])
3547-
//
3548-
// let pipeline = db.pipeline()
3549-
// .collection(randomCol.path)
3550-
// .limit(1)
3551-
// .select([Constant(5).bitAnd(12).as("result")])
3552-
// let snapshot = try await pipeline.execute()
3553-
// TestHelper.compare(snapshot: snapshot, expected: [["result": 4]], enforceOrder: false)
3554-
// }
3555-
//
3556-
// func testBitOr() async throws {
3557-
// try XCTSkipIf(true, "Skip this test since backend has not yet supported.")
3558-
// let db = firestore()
3559-
// let randomCol = collectionRef()
3560-
// try await randomCol.document("dummyDoc").setData(["field": "value"])
3561-
//
3562-
// let pipeline = db.pipeline()
3563-
// .collection(randomCol.path)
3564-
// .limit(1)
3565-
// .select([Constant(5).bitOr(12).as("result")])
3566-
// let snapshot = try await pipeline.execute()
3567-
// TestHelper.compare(snapshot: snapshot, expected: [["result": 13]], enforceOrder: false)
3568-
// }
3569-
//
3570-
// func testBitXor() async throws {
3571-
// try XCTSkipIf(true, "Skip this test since backend has not yet supported.")
3572-
// let db = firestore()
3573-
// let randomCol = collectionRef()
3574-
// try await randomCol.document("dummyDoc").setData(["field": "value"])
3575-
//
3576-
// let pipeline = db.pipeline()
3577-
// .collection(randomCol.path)
3578-
// .limit(1)
3579-
// .select([Constant(5).bitXor(12).as("result")])
3580-
// let snapshot = try await pipeline.execute()
3581-
// TestHelper.compare(snapshot: snapshot, expected: [["result": 9]], enforceOrder: false)
3582-
// }
3583-
//
3584-
// func testBitNot() async throws {
3585-
// try XCTSkipIf(true, "Skip this test since backend has not yet supported.")
3586-
// let db = firestore()
3587-
// let randomCol = collectionRef()
3588-
// try await randomCol.document("dummyDoc").setData(["field": "value"])
3589-
// let bytesInput = Data([0xFD])
3590-
// let expectedOutput = Data([0x02])
3591-
//
3592-
// let pipeline = db.pipeline()
3593-
// .collection(randomCol.path)
3594-
// .limit(1)
3595-
// .select([Constant(bytesInput).bitNot().as("result")])
3596-
// let snapshot = try await pipeline.execute()
3597-
// TestHelper.compare(
3598-
// snapshot: snapshot,
3599-
// expected: [["result": expectedOutput]],
3600-
// enforceOrder: false
3601-
// )
3602-
// }
3603-
//
3604-
// func testBitLeftShift() async throws {
3605-
// try XCTSkipIf(true, "Skip this test since backend has not yet supported.")
3606-
// let db = firestore()
3607-
// let randomCol = collectionRef()
3608-
// try await randomCol.document("dummyDoc").setData(["field": "value"])
3609-
// let bytesInput = Data([0x02])
3610-
// let expectedOutput = Data([0x08])
3611-
//
3612-
// let pipeline = db.pipeline()
3613-
// .collection(randomCol.path)
3614-
// .limit(1)
3615-
// .select([Constant(bytesInput).bitLeftShift(2).as("result")])
3616-
// let snapshot = try await pipeline.execute()
3617-
// TestHelper.compare(
3618-
// snapshot: snapshot,
3619-
// expected: [["result": expectedOutput]],
3620-
// enforceOrder: false
3621-
// )
3622-
// }
3623-
//
3624-
// func testBitRightShift() async throws {
3625-
// try XCTSkipIf(true, "Skip this test since backend has not yet supported.")
3626-
// let db = firestore()
3627-
// let randomCol = collectionRef()
3628-
// try await randomCol.document("dummyDoc").setData(["field": "value"])
3629-
// let bytesInput = Data([0x02])
3630-
// let expectedOutput = Data([0x00])
3631-
//
3632-
// let pipeline = db.pipeline()
3633-
// .collection(randomCol.path)
3634-
// .limit(1)
3635-
// .select([Constant(bytesInput).bitRightShift(2).as("result")])
3636-
// let snapshot = try await pipeline.execute()
3637-
// TestHelper.compare(
3638-
// snapshot: snapshot,
3639-
// expected: [["result": expectedOutput]],
3640-
// enforceOrder: false
3641-
// )
3642-
// }
3643-
36443506
func testDocumentId() async throws {
36453507
try XCTSkipIf(true, "Skip this test since backend has not yet supported.")
36463508
let collRef = collectionRef(withDocuments: bookDocs)

0 commit comments

Comments
 (0)