FirebaseFirestore Framework Reference

PipelineSource

public struct PipelineSource : @unchecked Sendable

A PipelineSource is the entry point for building a Firestore pipeline. It allows you to specify the source of the data for the pipeline, which can be a collection, a collection group, a list of documents, or the entire database.

  • Specifies a collection as the data source for the pipeline.

    Declaration

    Swift

    public func collection(_ path: String, forceIndex: String? = nil) -> Pipeline

    Parameters

    path

    The path to the collection.

    forceIndex

    The name of the index to be used.

    Return Value

    A Pipeline with the specified collection as its source.

  • Specifies a collection as the data source for the pipeline.

    Declaration

    Swift

    public func collection(_ coll: CollectionReference, forceIndex: String? = nil) -> Pipeline

    Parameters

    coll

    The CollectionReference of the

    forceIndex

    The name of the index to be used.

    Return Value

    A Pipeline with the specified collection as its source.

  • Specifies a collection group as the data source for the pipeline.

    Declaration

    Swift

    public func collectionGroup(_ collectionId: String, forceIndex: String? = nil) -> Pipeline

    Parameters

    collectionId

    The ID of the collection group.

    Return Value

    A Pipeline with the specified collection group as its source.

  • Specifies the entire database as the data source for the pipeline.

    Declaration

    Swift

    public func database() -> Pipeline

    Return Value

    A Pipeline with the entire database as its source.

  • Specifies a list of documents as the data source for the pipeline.

    Declaration

    Swift

    public func documents(_ docs: [DocumentReference]) -> Pipeline

    Parameters

    docs

    An array of DocumentReference objects.

    Return Value

    A Pipeline with the specified documents as its source.

  • Specifies a list of documents as the data source for the pipeline.

    Declaration

    Swift

    public func documents(_ paths: [String]) -> Pipeline

    Parameters

    paths

    An array of document paths.

    Return Value

    A Pipeline with the specified documents as its source.

  • Creates a Pipeline from an existing Query.

    This allows you to convert a standard Firestore query into a pipeline, which can then be further modified with additional pipeline stages.

    Declaration

    Swift

    public func create(from query: Query) -> Pipeline

    Parameters

    query

    The Query to convert into a pipeline.

    Return Value

    A Pipeline that is equivalent to the given query.

  • Specifies an array of in-memory document dictionaries as the data source for the pipeline.

    Using literal documents as a data source allows constructing pipelines without fetching existing data from Firestore. This is useful for bulk inserting or upserting predefined records, testing pipelines with synthetic datasets, or applying transformations to static data.

    Dictionary values can include primitive types (such as String, Int, Double, Bool), nested collections, or Firestore Expression objects. Write-only FieldValue sentinels (such as FieldValue.serverTimestamp()) are not supported; use pipeline expressions such as CurrentTimestamp() instead.

    // Example 1: Transform and project literal records
    let snapshot = try await db.pipeline()
      .literals([
        ["name": "Alice", "age": 30, "role": "Admin"],
        ["name": "Bob", "age": 25, "role": "User"]
      ])
      .select([Field("name"), Field("role")])
      .execute()
    
    // Example 2: Bulk insert literal documents into a collection
    let insertSnapshot = try await db.pipeline()
      .literals([
        ["id": "user_1", "name": "Charlie", "email": "charlie@example.com"],
        ["id": "user_2", "name": "Dana", "email": "dana@example.com"]
      ])
      .insert(collectionPath: "users", documentIdExpression: Field("id"))
      .execute()
    

    Declaration

    Swift

    public func literals(_ data: [[String : Sendable]]) -> Pipeline

    Parameters

    data

    An array of dictionaries representing document literals.

    Return Value

    A Pipeline with the specified literal documents as its source.

  • Specifies in-memory document dictionaries as variadic arguments for the pipeline data source.

    Using literal documents as a data source allows constructing pipelines without fetching existing data from Firestore. This is useful for bulk inserting or upserting predefined records, testing pipelines with synthetic datasets, or applying transformations to static data.

    Dictionary values can include primitive types (such as String, Int, Double, Bool), nested collections, or Firestore Expression objects. Write-only FieldValue sentinels (such as FieldValue.serverTimestamp()) are not supported; use pipeline expressions such as CurrentTimestamp() instead.

    // Example 1: Execute literals containing expressions
    let snapshot = try await db.pipeline()
      .literals(
        ["id": "doc_1", "baseValue": 10, "doubled": Constant(10).multiply(2)]
      )
      .execute()
    
    // Example 2: Bulk upsert variadic literal records into a collection
    let upsertSnapshot = try await db.pipeline()
      .literals(
        ["id": "user_1", "status": "Active"],
        ["id": "user_2", "status": "Pending"]
      )
      .upsert(
        collectionPath: "users",
        documentIdExpression: Field("id"),
        additionalFields: [Field("status").as("accountStatus")]
      )
      .execute()
    

    Declaration

    Swift

    public func literals(_ document: [String: Sendable],
                         _ additionalDocuments: [String: Sendable]...) -> Pipeline

    Parameters

    document

    The first dictionary representing a document literal.

    additionalDocuments

    Optional additional dictionary arguments representing document literals.

    Return Value

    A Pipeline with the specified literal documents as its source.