A property wrapper type that marks a DocumentReference? or String? field to be populated with a document identifier when it is read.

Apply the @DocumentID annotation to a DocumentReference? or String? property in a Codable object to have it populated with the document identifier when it is read and decoded from Firestore.

• Example Read:

  struct Player: Codable {
  @DocumentID var playerID: String?
  var health: Int64
  }
  

let p = try! await Firestore.firestore() .collection("players") .document("player-1") .getDocument(as: Player.self) print("(p.playerID!) Health: (p.health)")

// Prints: "Player: player-1, Health: 95"

- Important: Trying to encode/decode this type using encoders/decoders other than
  Firestore.Encoder throws an error.

- Important: When writing a Codable object containing an `@DocumentID` annotated field,
  its value is ignored. This allows you to read a document from one path and
  write it into another without adjusting the value here.

Wraps an Optional field in a Codable object such that when the field has a nil value it will encode to a null value in Firestore. Normally, optional fields are omitted from the encoded document.

This is useful for ensuring a field is present in a Firestore document, even when there is no associated value.

A property wrapper that marks an Optional<Timestamp> field to be populated with a server timestamp. If a Codable object being written contains a nil for an @ServerTimestamp-annotated field, it will be replaced with FieldValue.serverTimestamp() as it is sent.

Example:

struct CustomModel {
  @ServerTimestamp var ts: Timestamp?
}

Then writing CustomModel(ts: nil) will tell server to fill ts with current timestamp.

A property wrapper that listens to a Firestore collection.

In the following example, FirestoreQuery will fetch all documents from the fruits collection, filtering only documents whose isFavourite attribute is equal to true, map members of result set to the Fruit type, and make them available via the wrapped value fruits.

struct ContentView: View {
  @FirestoreQuery(
    collectionPath: "fruits",
    predicates: [.whereField("isFavourite", isEqualTo: true)]
  ) var fruits: [Fruit]

  var body: some View {
    List(fruits) { fruit in
      Text(fruit.name)
    }
  }
}

FirestoreQuery also supports returning a Result type. The .success case returns an array of elements, whereas the .failure case returns an error in case mapping the Firestore documents wasn't successful:

struct ContentView: View {
  @FirestoreQuery(
    collectionPath: "fruits",
    predicates: [.whereField("isFavourite", isEqualTo: true)]
  ) var fruitResults: Result<[Fruit], Error>

var body: some View {
  if case let .success(fruits) = fruitResults {
    List(fruits) { fruit in
      Text(fruit.name)
    }
  } else if case let .failure(error) = fruitResults {
    Text("Couldn't map data: \(error.localizedDescription)")
  }
}

Alternatively, the projected value of the property wrapper provides access to the error as well. This allows you to display a list of all successfully mapped documents, as well as an error message with details about the documents that couldn't be mapped successfully (e.g. because of a field name mismatch).

struct ContentView: View {
  @FirestoreQuery(
    collectionPath: "mappingFailure",
    decodingFailureStrategy: .ignore
  ) private var fruits: [Fruit]

  var body: some View {
    VStack(alignment: .leading) {
      List(fruits) { fruit in
        Text(fruit.name)
      }
      if $fruits.error != nil {
        HStack {
          Text("There was an error")
            .foregroundColor(Color(UIColor.systemBackground))
          Spacer()
        }
        .padding(30)
        .background(Color.red)
      }
    }
  }
}

Internally, @FirestoreQuery sets up a snapshot listener and publishes any incoming changes via an @StateObject.

The projected value of this property wrapper provides access to a configuration object of type FirestoreQueryConfiguration which can be used to modify the query criteria. Changing the filter predicates results in the underlying snapshot listener being unregistered and a new one registered.

Button("Show only Apples and Oranges") {
  $fruits.predicates = [.whereField("name", isIn: ["Apple", "Orange]]
}

This property wrapper does not support updating the wrappedValue, i.e. you need to use Firestore's other APIs to add, delete, or modify documents.

An AggregateFunction that has been given an alias.

Represents the distance measure to be used in a vector similarity search.

An Expression that has been given an alias.

A Constant is an Expression that represents a fixed, literal value within a Firestore pipeline.

Constants are used to introduce literal values into a query, which can be useful for:

• Comparing a field to a specific value in a where clause.
• Adding new fields with fixed values using addFields.
• Providing literal arguments to functions like sum or average.

Example of using a Constant to add a new field:

// Add a new field "source" with the value "manual" to each document
firestore.pipeline()
  .collection("entries")
  .addFields([
    Constant("manual").as("source")
  ])

An expression that represents the current document being processed.

Example:

// Define the current document as a variable "doc"
firestore.pipeline().collection("books")
    .define([CurrentDocument().as("doc")])
    // Access a field from the defined document variable
    .select([Variable("doc").getField("title")])

A Field is an Expression that represents a field in a Firestore document.

It is a central component for building queries and transformations in Firestore pipelines. A Field can be used to:

• Reference a document field by its name or FieldPath.
• Create complex BooleanExpressions for filtering in a where clause.
• Perform mathematical operations on numeric fields.
• Manipulate string and array fields.

Example of creating a Field and using it in a where clause:

// Reference the "price" field in a document
let priceField = Field("price")

// Create a query to find products where the price is greater than 100
firestore.pipeline()
  .collection("products")
  .where(priceField.greaterThan(100))

A full-text search against all indexed search fields in the document.

Note: This expression can only be used in the search stage.

Example usage in a search stage:

firestore.pipeline()
  .collection("restaurants")
  .search(query: DocumentMatches("waffles OR pancakes"))

Represents the relevance score of a document against the search query.

Example usage:

firestore.pipeline().collection("restaurants")
.search(
  query: "waffles OR pancakes",
  sort: [ Score().as("searchScore") ]
)

A Variable is an Expression that retrieves the value of a variable bound via Pipeline.define.

Variables are typically defined in a define stage and can be referenced in subsequent stages.

Example:

firestore.pipeline().collection("products")
    .define([Field("price").multiply(0.9).as("discountedPrice")])
    .where(Variable("discountedPrice") < 100)
    .select([Field("name"), Variable("discountedPrice")])

An ordering for the documents in a pipeline.

A direction to order results in.

Undocumented

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.

Undocumented

Undocumented

Undocumented