Cloud Firestore API - Package cloud.google.com/go/firestore (v1.22.0)

Package firestore provides a client for reading and writing to a Cloud Firestore database.

See https://cloud.google.com/firestore/docs for an introduction to Cloud Firestore and additional help on using the Firestore API.

See https://godoc.org/cloud.google.com/go for authentication, timeouts, connection pooling and similar aspects of this package.

Note: you can't use both Cloud Firestore and Cloud Datastore in the same project.

Creating a Client

To start working with this package, create a client with a project ID:

ctx := context.Background()
client, err := firestore.NewClient(ctx, "projectID")
if err != nil {
    // TODO: Handle error.
}

CollectionRefs and DocumentRefs

In Firestore, documents are sets of key-value pairs, and collections are groups of documents. A Firestore database consists of a hierarchy of alternating collections and documents, referred to by slash-separated paths like "States/California/Cities/SanFrancisco".

This client is built around references to collections and documents. CollectionRefs and DocumentRefs are lightweight values that refer to the corresponding database entities. Creating a ref does not involve any network traffic.

states := client.Collection("States")
ny := states.Doc("NewYork")
// Or, in a single call:
ny = client.Doc("States/NewYork")

Reading

Use DocumentRef.Get to read a document. The result is a DocumentSnapshot. Call its Data method to obtain the entire document contents as a map.

docsnap, err := ny.Get(ctx)
if err != nil {
    // TODO: Handle error.
}
dataMap := docsnap.Data()
fmt.Println(dataMap)

You can also obtain a single field with DataAt, or extract the data into a struct with DataTo. With the type definition

type State struct {
    Capital    string  `firestore:"capital"`
    Population float64 `firestore:"pop"` // in millions
}

we can extract the document's data into a value of type State:

var nyData State
if err := docsnap.DataTo(&nyData); err != nil {
    // TODO: Handle error.
}

Note that this client supports struct tags beginning with "firestore:" that work like the tags of the encoding/json package, letting you rename fields, ignore them, or omit their values when empty.

To retrieve multiple documents from their references in a single call, use Client.GetAll.

docsnaps, err := client.GetAll(ctx, []*firestore.DocumentRef{
    states.Doc("Wisconsin"), states.Doc("Ohio"),
})
if err != nil {
    // TODO: Handle error.
}
for _, ds := range docsnaps {
    _ = ds // TODO: Use ds.
}

Writing

For writing individual documents, use the methods on DocumentReference. Create creates a new document.

wr, err := ny.Create(ctx, State{
    Capital:    "Albany",
    Population: 19.8,
})
if err != nil {
    // TODO: Handle error.
}
fmt.Println(wr)

The first return value is a WriteResult, which contains the time at which the document was updated.

Create fails if the document exists. Another method, Set, either replaces an existing document or creates a new one.

ca := states.Doc("California")
_, err = ca.Set(ctx, State{
    Capital:    "Sacramento",
    Population: 39.14,
})

To update some fields of an existing document, use Update. It takes a list of paths to update and their corresponding values.

_, err = ca.Update(ctx, []firestore.Update{{Path: "capital", Value: "Sacramento"}})

Use DocumentRef.Delete to delete a document.

_, err = ny.Delete(ctx)

Preconditions

You can condition Deletes or Updates on when a document was last changed. Specify these preconditions as an option to a Delete or Update method. The check and the write happen atomically with a single RPC.

docsnap, err = ca.Get(ctx)
if err != nil {
    // TODO: Handle error.
}
_, err = ca.Update(ctx,
    []firestore.Update{{Path: "capital", Value: "Sacramento"}},
    firestore.LastUpdateTime(docsnap.UpdateTime))

Here we update a doc only if it hasn't changed since we read it. You could also do this with a transaction.

To perform multiple writes at once, use a WriteBatch. Its methods chain for convenience.

WriteBatch.Commit sends the collected writes to the server, where they happen atomically.

writeResults, err := client.Batch().
    Create(ny, State{Capital: "Albany"}).
    Update(ca, []firestore.Update{{Path: "capital", Value: "Sacramento"}}).
    Delete(client.Doc("States/WestDakota")).
    Commit(ctx)

Queries

You can use SQL to select documents from a collection. Begin with the collection, and build up a query using Select, Where and other methods of Query.

q := states.Where("pop", ">", 10).OrderBy("pop", firestore.Desc)

Supported operators include '<', '<=', '>', '>=', '==', 'in', 'array-contains', and 'array-contains-any'.

Call the Query's Documents method to get an iterator, and use it like the other Google Cloud Client iterators.

iter := q.Documents(ctx)
defer iter.Stop()
for {
    doc, err := iter.Next()
    if err == iterator.Done {
        break
    }
    if err != nil {
        // TODO: Handle error.
    }
    fmt.Println(doc.Data())
}

To get all the documents in a collection, you can use the collection itself as a query.

iter = client.Collection("States").Documents(ctx)

Firestore supports similarity search over embedding vectors. See Query.FindNearest for details.

Collection Group Partition Queries

You can partition the documents of a Collection Group allowing for smaller subqueries.

collectionGroup = client.CollectionGroup("States")
partitions, err = collectionGroup.GetPartitionedQueries(ctx, 20)

You can also Serialize/Deserialize queries making it possible to run/stream the queries elsewhere; another process or machine for instance.

queryProtos := make([][]byte, 0)
for _, query := range partitions {
    protoBytes, err := query.Serialize()
    // handle err
    queryProtos = append(queryProtos, protoBytes)
    ...
}

for _, protoBytes := range queryProtos {
    query, err := client.CollectionGroup("").Deserialize(protoBytes)
    ...
}

Transactions

Use a transaction to execute reads and writes atomically. All reads must happen before any writes. Transaction creation, commit, rollback and retry are handled for you by the Client.RunTransaction method; just provide a function and use the read and write methods of the Transaction passed to it.

ny := client.Doc("States/NewYork")
err := client.RunTransaction(ctx, func(ctx context.Context, tx *firestore.Transaction) error {
    doc, err := tx.Get(ny) // tx.Get, NOT ny.Get!
    if err != nil {
        return err
    }
    pop, err := doc.DataAt("pop")
    if err != nil {
        return err
    }
    return tx.Update(ny, []firestore.Update{{Path: "pop", Value: pop.(float64) + 0.2}})
})
if err != nil {
    // TODO: Handle error.
}

Google Cloud Firestore Emulator

This package supports the Cloud Firestore emulator, which is useful for testing and development. Environment variables are used to indicate that Firestore traffic should be directed to the emulator instead of the production Firestore service.

To install and run the emulator and its environment variables, see the documentation at https://cloud.google.com/sdk/gcloud/reference/beta/emulators/firestore/. Once the emulator is running, set FIRESTORE_EMULATOR_HOST to the API endpoint.

// Set FIRESTORE_EMULATOR_HOST environment variable.
err := os.Setenv("FIRESTORE_EMULATOR_HOST", "localhost:9000")
if err != nil {
    // TODO: Handle error.
}
// Create client as usual.
client, err := firestore.NewClient(ctx, "my-project-id")
if err != nil {
    // TODO: Handle error.
}
defer client.Close()

DefaultDatabaseID is name of the default database

DefaultTransactionMaxAttempts is the default number of times to attempt a transaction.

DetectProjectID is a sentinel value that instructs NewClient to detect the project ID. It is given in place of the projectID argument. NewClient will use the project ID from the given credentials or the default credentials (https://developers.google.com/accounts/docs/application-default-credentials) if no credentials were provided. When providing credentials, not all options will allow NewClient to extract the project ID. Specifically a JWT does not have the project ID encoded.

DocumentID is the special field name representing the ID of a document in queries.

LogWatchStreams controls whether watch stream status changes are logged. This feature is EXPERIMENTAL and may disappear at any time.

ReadOnly is a TransactionOption that makes the transaction read-only. Read-only transactions cannot issue write operations, but are more efficient.

ArrayRemove specifies elements to be removed from whatever array already exists in the server.

If a value exists and it's an array, values are removed from it. All duplicate values are removed. If a value exists and it's not an array, the value is replaced by an empty array. If a value does not exist, an empty array is created.

ArrayRemove must be the value of a field directly; it cannot appear in array or struct values, or in any value that is itself inside an array or struct.

ArrayUnion specifies elements to be added to whatever array already exists in the server, or to create an array if no value exists.

If a value exists and it's an array, values are appended to it. Any duplicate value is ignored. If a value exists and it's not an array, the value is replaced by an array of the values in the ArrayUnion. If a value does not exist, an array of the values in the ArrayUnion is created.

ArrayUnion must be the value of a field directly; it cannot appear in array or struct values, or in any value that is itself inside an array or struct.

FieldTransformIncrement returns a special value that can be used with Set, Create, or Update that tells the server to transform the field's current value by the given value.

The supported values are:

int, int8, int16, int32, int64
uint8, uint16, uint32
float32, float64

If the field does not yet exist, the transformation will set the field to the given value.

FieldTransformMaximum returns a special value that can be used with Set, Create, or Update that tells the server to set the field to the maximum of the field's current value and the given value.

The supported values are:

int, int8, int16, int32, int64
uint8, uint16, uint32
float32, float64

If the field is not an integer or double, or if the field does not yet exist, the transformation will set the field to the given value. If a maximum operation is applied where the field and the input value are of mixed types (that is - one is an integer and one is a double) the field takes on the type of the larger operand. If the operands are equivalent (e.g. 3 and 3.0), the field does not change. 0, 0.0, and -0.0 are all zero. The maximum of a zero stored value and zero input value is always the stored value. The maximum of any numeric value x and NaN is NaN.

FieldTransformMinimum returns a special value that can be used with Set, Create, or Update that tells the server to set the field to the minimum of the field's current value and the given value.

The supported values are:

int, int8, int16, int32, int64
uint8, uint16, uint32
float32, float64

If the field is not an integer or double, or if the field does not yet exist, the transformation will set the field to the given value. If a minimum operation is applied where the field and the input value are of mixed types (that is - one is an integer and one is a double) the field takes on the type of the smaller operand. If the operands are equivalent (e.g. 3 and 3.0), the field does not change. 0, 0.0, and -0.0 are all zero. The minimum of a zero stored value and zero input value is always the stored value. The minimum of any numeric value x and NaN is NaN.

Fields is a helper function that returns its arguments as a slice of any. It is used to provide variadic-like ergonomics for pipeline stages that accept a slice of fields or expressions.

Increment is an alias for FieldTransformIncrement.

MaxAttempts is a TransactionOption that configures the maximum number of times to try a transaction. In defaults to DefaultTransactionMaxAttempts.

Ptr returns a pointer to its argument. It can be used to initialize pointer fields:

findNearestOptions.DistanceThreshold = firestore.Ptr[float64](0.1)

WithCommitResponseTo returns a TransactionOption that specifies where the CommitResponse should be written on successful commit. Nothing is written on a failed commit.

AddFieldsOption is an option for an AddFields pipeline stage.

AggregateFunction represents an aggregation function in a pipeline.

ArrayAgg returns an array containing all values of the expression when evaluated on each document in the group. If the expression resolves to an absent value, it is converted to NULL. The order of elements in the output array is not stable and shouldn't be relied upon.

ArrayAggDistinct returns an array containing all distinct values of the expression when evaluated on each document in the group. If the expression resolves to an absent value, it is converted to NULL. The order of elements in the output array is not stable and shouldn't be relied upon.

Average creates an aggregation that calculates the average (mean) of values from an expression or a field's values across multiple stage inputs. fieldOrExpr can be a field path string, [FieldPath] or [Expression] Example:

    // Calculate the average age of users
    Average(FieldOf("info.age")).As("averageAge")       // FieldOf returns Expr
    Average(FieldOfPath("info.age")).As("averageAge") // FieldOfPath returns Expr
    Average("info.age").As("averageAge")              // String implicitly becomes FieldOf(...).As(...)
    Average(FieldPath([]string{"info", "age"})).As("averageAge")

Count creates an aggregation that counts the number of stage inputs with valid evaluations of the provided field or expression. fieldOrExpr can be a field path string, [FieldPath] or [Expression] Example:

    // Count the number of items where the price is greater than 10
    Count(FieldOf("price").Gt(10)).As("expensiveItemCount") // FieldOf("price").Gt(10) is a BooleanExpr
    // Count the total number of products
    Count("productId").As("totalProducts")                  // String implicitly becomes FieldOf(...).As(...)

CountAll creates an aggregation that counts the total number of stage inputs.

Example:

    // Count the total number of users
    CountAll().As("totalUsers")

CountDistinct creates an aggregation that counts the number of distinct values of the provided field or expression. fieldOrExpr can be a field path string, [FieldPath] or [Expression] Example:

    // CountDistinct the number of distinct items where the price is greater than 10
    CountDistinct(FieldOf("price").Gt(10)).As("expensiveItemCount") // FieldOf("price").Gt(10) is a BooleanExpr
    // CountDistinct the total number of distinct products
    CountDistinct("productId").As("totalProducts")                  // String implicitly becomes FieldOf(...).As(...)

CountIf creates an aggregation that counts the number of stage inputs where the provided boolean expression evaluates to true. Example:

CountIf(FieldOf("published").Equal(true)).As("publishedCount")

First returns the value of the expression for the first document in the group.

Last returns the value of the expression for the last document in the group.

Maximum creates an aggregation that calculates the maximum of values from an expression or a field's values across multiple stage inputs.

Example:

    // Find the highest order amount
    Maximum(FieldOf("orderAmount")).As("maxOrderAmount") // FieldOf returns Expr
    Maximum("orderAmount").As("maxOrderAmount")          // String implicitly becomes FieldOf(...).As(...)

Minimum creates an aggregation that calculates the minimum of values from an expression or a field's values across multiple stage inputs.

Example:

    // Find the lowest order amount
    Minimum(FieldOf("orderAmount")).As("minOrderAmount") // FieldOf returns Expr
    Minimum("orderAmount").As("minOrderAmount")          // String implicitly becomes FieldOf(...).As(...)

RawAggregate creates a raw aggregation function.

This method provides a way to call aggregation functions that are supported by the Firestore backend but that are not available as specific factory methods in this class.

Example:

RawAggregate("sum", "orderAmount").As("totalRevenue")

Sum creates an aggregation that calculates the sum of values from an expression or a field's values across multiple stage inputs.

Example:

    // Calculate the total revenue from a set of orders
    Sum(FieldOf("orderAmount")).As("totalRevenue") // FieldOf returns Expr
    Sum("orderAmount").As("totalRevenue")          // String implicitly becomes FieldOf(...).As(...)

AggregateOption is an option for executing a pipeline aggregation stage.

WithAggregateGroups specifies the fields or expressions to group the documents by. Each of the grouping keys can be a string field path, a [FieldPath], or a [Selectable] expression.

AggregationQuery allows for generating aggregation results of an underlying basic query. A single AggregationQuery can contain multiple aggregations.

Get retrieves the aggregation query results from the service.

GetResponse runs the aggregation with the options provided in the query

Pipeline creates a new [Pipeline] from the aggregation query. All of the operations of the underlying query will be converted to pipeline stages, and an aggregate stage will be added for the aggregations.

Transaction specifies that aggregation query should run within provided transaction

WithAvg specifies that the aggregation query should provide an average of the values of the provided field in the results returned by the underlying Query. The alias argument can be empty or a valid Firestore document field name. It can be used as key in the AggregationResult to get the average value. If alias is empty, Firestore will autogenerate a key.

WithAvgPath specifies that the aggregation query should provide an average of the values of the provided field in the results returned by the underlying Query. The path argument can be a single field or a dot-separated sequence of fields, and must not contain any of the runes "˜*/[]". The alias argument can be empty or a valid Firestore document field name. It can be used as key in the AggregationResult to get the average value. If alias is empty, Firestore will autogenerate a key.

WithCount specifies that the aggregation query provide a count of results returned by the underlying Query.

WithSum specifies that the aggregation query should provide a sum of the values of the provided field in the results returned by the underlying Query. The alias argument can be empty or a valid Firestore document field name. It can be used as key in the AggregationResult to get the sum value. If alias is empty, Firestore will autogenerate a key.

WithSumPath specifies that the aggregation query should provide a sum of the values of the provided field in the results returned by the underlying Query. The path argument can be a single field or a dot-separated sequence of fields, and must not contain any of the runes "˜*/[]". The alias argument can be empty or a valid Firestore document field name. It can be used as key in the AggregationResult to get the sum value. If alias is empty, Firestore will autogenerate a key.

AggregationResponse contains AggregationResult and response from the run options in the query

AggregationResult contains the results of an aggregation query.

AliasedAggregate is an aliased [AggregateFunction]. It's used to give a name to the result of an aggregation.

Accumulators is a helper function that returns its arguments as a slice of *AliasedAggregate. It is used to provide variadic-like ergonomics for the Aggregate pipeline stage.

AliasedExpression represents an expression with an alias. It implements the [Selectable] interface, allowing it to be used in projection stages like Select and AddFields.

AliasedExpressions is a helper function that returns its arguments as a slice of *AliasedExpression. It is used to provide variadic-like ergonomics for the [Pipeline.Define] pipeline stage.

AndFilter represents the intersection of two or more filters.

BooleanExpression is an interface that represents a boolean expression in a pipeline.

And creates an expression that performs a logical 'AND' operation.

ArrayContains creates an expression that checks if an array contains a specified element.

• exprOrFieldPath can be a field path string, [FieldPath] or an [Expression] that evaluates to an array.
• value is the element to check for.

Example:

// Check if the 'tags' array contains "Go".
ArrayContains("tags", "Go")

ArrayContainsAll creates an expression that checks if an array contains all of the provided values.

• exprOrFieldPath can be a field path string, [FieldPath] or an [Expression] that evaluates to an array.
• values can be an array of values or an expression that evaluates to an array.

Example:

// Check if the 'tags' array contains both "Go" and "Firestore".
ArrayContainsAll("tags", []string{"Go", "Firestore"})

ArrayContainsAny creates an expression that checks if an array contains any of the provided values.

• exprOrFieldPath can be a field path string, [FieldPath] or an [Expression] that evaluates to an array.
• values can be an array of values or an expression that evaluates to an array.

Example:

// Check if the 'tags' array contains either "Go" or "Firestore".
ArrayContainsAny("tags", []string{"Go", "Firestore"})

DocumentMatches creates a boolean expression that performs a full-text search on all indexed search fields in the document.

This Expression can only be used within a Search stage.

Example:

client.Pipeline().Collection("restaurants").
    Search(WithSearchQuery(DocumentMatches("waffles OR pancakes")))

• query: Define the search query using the search domain-specific language (DSL).

Experimental: Update, Delete and Search stages in pipeline queries are in public preview and are subject to potential breaking changes in future versions, regardless of any other documented package stability guarantees.

EndsWith creates an expression that checks if a string field or expression ends with a given suffix.

• exprOrFieldPath can be a field path string, [FieldPath] or [Expression].
• suffix string or [Expression] to check for.

Example:

// Check if the 'filename' field ends with ".go".
EndsWith("filename", ".go")

Equal creates an expression that checks if field's value or an expression is equal to an expression or a constant value, returning it as a BooleanExpr.

• left: The field path string, [FieldPath] or [Expression] to compare.
• right: The constant value or [Expression] to compare to.

Example:

    // Check if the 'age' field is equal to 21
    Equal(FieldOf("age"), 21)

    // Check if the 'age' field is equal to an expression
    Equal(FieldOf("age"), FieldOf("minAge").Add(10))

    // Check if the 'age' field is equal to the 'limit' field
    Equal("age", FieldOf("limit"))

    // Check if the 'city' field is equal to string constant "London"
    Equal("city", "London")

EqualAny creates an expression that checks if a field or expression is equal to any of the provided values.

• exprOrFieldPath can be a field path string, [FieldPath] or an [Expression].
• values can be an array of values or an expression that evaluates to an array.

Example:

// Check if the 'status' field is either "active" or "pending".
EqualAny("status", []string{"active", "pending"})

FieldExists creates an expression that checks if a field exists.

GreaterThan creates an expression that checks if field's value or an expression is greater than an expression or a constant value, returning it as a BooleanExpr.

• left: The field path string, [FieldPath] or [Expression] to compare.
• right: The constant value or [Expression] to compare to.

Example:

    // Check if the 'age' field is greater than 21
    GreaterThan(FieldOf("age"), 21)

    // Check if the 'age' field is greater than an expression
    GreaterThan(FieldOf("age"), FieldOf("minAge").Add(10))

    // Check if the 'age' field is greater than the 'limit' field
    GreaterThan("age", FieldOf("limit"))

GreaterThanOrEqual creates an expression that checks if field's value or an expression is greater than or equal to an expression or a constant value, returning it as a BooleanExpr.

• left: The field path string, [FieldPath] or [Expression] to compare.
• right: The constant value or [Expression] to compare to.

Example:

    // Check if the 'age' field is greater than or equal to 21
    GreaterThanOrEqual(FieldOf("age"), 21)

    // Check if the 'age' field is greater than or equal to an expression
    GreaterThanOrEqual(FieldOf("age"), FieldOf("minAge").Add(10))

    // Check if the 'age' field is greater than or equal to the 'limit' field
    GreaterThanOrEqual("age", FieldOf("limit"))

IfErrorBoolean creates a boolean expression that evaluates and returns tryExpr if it does not produce an error; otherwise, it evaluates and returns catchExpr. It returns a new [BooleanExpression] representing the if_error operation.

• tryExpr is the boolean expression to try.
• catchExpr is the boolean expression to return if tryExpr errors.

IsAbsent creates an expression that checks if an expression evaluates to an absent value.

IsError creates an expression that checks if an expression evaluates to an error.

IsType creates an expression that checks if an expression is of a specific type.

• exprOrField can be a field path string, [FieldPath] or an [Expression].
• dataType can be a valid type name. Valid values are "null", "array", "boolean", "bytes", "timestamp", "geo_point", "number", "int32", "int64", "float64", "decimal128", "map", "reference", "string", "vector", "max_key", "min_key", "min_array", "object_id", "regex", "request_timestamp"

LessThan creates an expression that checks if field's value or an expression is less than an expression or a constant value, returning it as a BooleanExpr.

• left: The field path string, [FieldPath] or [Expression] to compare.
• right: The constant value or [Expression] to compare to.

Example:

    // Check if the 'age' field is less than 21
    LessThan(FieldOf("age"), 21)

    // Check if the 'age' field is less than an expression
    LessThan(FieldOf("age"), FieldOf("minAge").Add(10))

    // Check if the 'age' field is less than the 'limit' field
    LessThan("age", FieldOf("limit"))

LessThanOrEqual creates an expression that checks if field's value or an expression is less than or equal to an expression or a constant value, returning it as a BooleanExpr.

• left: The field path string, [FieldPath] or [Expression] to compare.
• right: The constant value or [Expression] to compare to.

Example:

    // Check if the 'age' field is less than or equal to 21
    LessThanOrEqual(FieldOf("age"), 21)

    // Check if the 'age' field is less than or equal to an expression
    LessThanOrEqual(FieldOf("age"), FieldOf("minAge").Add(10))

    // Check if the 'age' field is less than or equal to the 'limit' field
    LessThanOrEqual("age", FieldOf("limit"))

Like creates an expression that performs a case-sensitive wildcard string comparison.

• exprOrFieldPath can be a field path string, [FieldPath] or [Expression].
• pattern string or [Expression] to search for. You can use "%" as a wildcard character.

Example:

// Check if the 'name' field starts with "G".
Like("name", "G%")

Nor creates an expression that performs a logical 'NOR' operation.

Not creates an expression that negates a boolean expression.

NotEqual creates an expression that checks if field's value or an expression is not equal to an expression or a constant value, returning it as a BooleanExpr.

• left: The field path string, [FieldPath] or [Expression] to compare.
• right: The constant value or [Expression] to compare to.

Example:

    // Check if the 'age' field is not equal to 21
    NotEqual(FieldOf("age"), 21)

    // Check if the 'age' field is not equal to an expression
    NotEqual(FieldOf("age"), FieldOf("minAge").Add(10))

    // Check if the 'age' field is not equal to the 'limit' field
    NotEqual("age", FieldOf("limit"))

    // Check if the 'city' field is not equal to string constant "London"
    NotEqual("city", "London")

NotEqualAny creates an expression that checks if a field or expression is not equal to any of the provided values.

• exprOrFieldPath can be a field path string, [FieldPath] or an [Expression].
• values can be an array of values or an expression that evaluates to an array.

Example:

// Check if the 'status' field is not "archived" or "deleted".
NotEqualAny("status", []string{"archived", "deleted"})

Or creates an expression that performs a logical 'OR' operation.

RawBooleanFunction creates a 'raw' boolean function expression. This is useful if the expression is available in the backend, but not yet in the current version of the SDK.

RegexContains creates an expression that checks if a string contains a match for a regular expression.

• exprOrFieldPath can be a field path string, [FieldPath] or [Expression].
• pattern is the regular expression to search for.

Example:

// Check if the 'email' field contains a gmail address.
RegexContains("email", "@gmail\\.com$")

RegexMatch creates an expression that checks if a string matches a regular expression.

• exprOrFieldPath can be a field path string, [FieldPath] or [Expression].
• pattern is the regular expression to match against.

Example:

// Check if the 'zip_code' field is a 5-digit number.
RegexMatch("zip_code", "^[0-9]{5}$")

StartsWith creates an expression that checks if a string field or expression starts with a given prefix.

• exprOrFieldPath can be a field path string, [FieldPath] or [Expression].
• prefix string or [Expression] to check for.

Example:

// Check if the 'name' field starts with "Mr.".
StartsWith("name", "Mr.")

StringContains creates an expression that checks if a string contains a specified substring.

• exprOrFieldPath can be a field path string, [FieldPath] or [Expression].
• substring is the string to search for.

Example:

// Check if the 'description' field contains the word "Firestore".
StringContains("description", "Firestore")

Xor creates an expression that performs a logical 'XOR' operation.

A BulkWriter supports concurrent writes to multiple documents. The BulkWriter submits document writes in maximum batches of 20 writes per request. Each request can contain many different document writes: create, delete, update, and set are all supported.

Only one operation (create, set, update, delete) per document is allowed. BulkWriter cannot promise atomicity: individual writes can fail or succeed independent of each other. Bulkwriter does not apply writes in any set order; thus a document can't have set on it immediately after creation.

Create adds a document creation write to the queue of writes to send. Note: You cannot write to (Create, Update, Set, or Delete) the same document more than once.

Delete adds a document deletion write to the queue of writes to send. Note: You cannot write to (Create, Update, Set, or Delete) the same document more than once.

End sends all enqueued writes in parallel and closes the BulkWriter to new requests. After calling End(), calling any additional method automatically returns with an error. This method completes when there are no more pending writes in the queue.

Flush commits all writes that have been enqueued up to this point in parallel. This method blocks execution.

Set adds a document set write to the queue of writes to send. Note: You cannot write to (Create, Update, Set, or Delete) the same document more than once.

Update adds a document update write to the queue of writes to send. Note: You cannot write to (Create, Update, Set, or Delete) the same document more than once.

BulkWriterJob provides read-only access to the results of a BulkWriter write attempt.

Results gets the results of the BulkWriter write attempt. This method blocks if the results for this BulkWriterJob haven't been received.

A Client provides access to the Firestore service.

NewClient creates a new Firestore client that uses the given project.

NewClientWithDatabase creates a new Firestore client that accesses the specified database.

NewRESTClient creates a new Firestore client that uses the REST API.

Batch returns a WriteBatch.

Deprecated: The WriteBatch API has been replaced with the transaction and the bulk writer API. For atomic transaction operations, use Transaction. For bulk read and write operations, use BulkWriter.

BulkWriter returns a BulkWriter instance. The context passed to the BulkWriter remains stored through the lifecycle of the object. This context allows callers to cancel BulkWriter operations.

Close closes any resources held by the client.

Close need not be called at program exit.

Collection creates a reference to a collection with the given path. A path is a sequence of IDs separated by slashes.

Collection returns nil if path contains an even number of IDs or any ID is empty.

CollectionGroup creates a reference to a group of collections that include the given ID, regardless of parent document.

For example, consider: France/Cities/Paris = {population: 100} Canada/Cities/Montreal = {population: 90}

CollectionGroup can be used to query across all "Cities" regardless of its parent "Countries". See ExampleCollectionGroup for a complete example.

Collections returns an iterator over the top-level collections.

Doc creates a reference to a document with the given path. A path is a sequence of IDs separated by slashes.

Doc returns nil if path contains an odd number of IDs or any ID is empty.

DocFromFullPath creates a reference to a document from its full, absolute path, also known as its Google Cloud resource name. The path must be in the format: "projects/{projectID}/databases/{databaseID}/documents/{collectionID}/{documentID}/..." This method returns nil if:

• The fullPath is empty.
• The fullPath does not match the expected resource name format (e.g., missing "projects/" or "/documents/").
• The projectID or databaseID in the fullPath do not match the client's configuration.
• The fullPath refers to a collection instead of a document (i.e., has an odd number of segments after "/documents/").
• The fullPath contains any empty path segments.

GetAll retrieves multiple documents with a single call. The DocumentSnapshots are returned in the order of the given DocumentRefs. The return value will always contain the same number of DocumentSnapshots as the number of DocumentRefs in the input.

If the same DocumentRef is specified multiple times in the input, the return value will contain the same number of DocumentSnapshots referencing the same document.

If a document is not present, the corresponding DocumentSnapshot's Exists method will return false.

Pipeline creates a PipelineSource to start building a Firestore pipeline.

RunTransaction runs f in a transaction. f should use the transaction it is given for all Firestore operations. For any operation requiring a context, f should use the context it is passed, not the first argument to RunTransaction.

f must not call Commit or Rollback on the provided Transaction.

If f returns nil, RunTransaction commits the transaction. If the commit fails due to a conflicting transaction, RunTransaction retries f. It gives up and returns an error after a number of attempts that can be configured with the MaxAttempts option. If the commit succeeds, RunTransaction returns a nil error.

If f returns non-nil, then the transaction will be rolled back and this method will return the same error. The function f is not retried.

Note that when f returns, the transaction is not committed. Calling code must not assume that any of f's changes have been committed until RunTransaction returns nil.

Since f may be called more than once, f should usually be idempotent – that is, it should have the same result when called multiple times.

WithAlwaysUseImplicitOrderBy configures the default behavior for queries. If enabled, queries will automatically inject an OrderBy clause for the Document ID (__name__) if one is not explicitly provided. In addition, it will automatically inject OrderBy clauses for any inequality filters (e.g. >, <, !=) present in the query if they are missing from the explicit orders. This ensures strictly deterministic query results and is especially useful when executing backwards pagination (e.g. limitToLast) without cursors.

WithReadOptions specifies constraints for accessing documents from the database, e.g. at what time snapshot to read the documents.

CollectionGroupOption is an option for a CollectionGroup pipeline stage.

A CollectionGroupRef is a reference to a group of collections sharing the same ID.

GetPartitionedQueries returns a slice of Query objects, each containing a partition of a collection group. partitionCount must be a positive value and the number of returned partitions may be less than the requested number if providing the desired number would result in partitions with very few documents.

If a Collection Group Query would return a large number of documents, this can help to subdivide the query to smaller working units that can be distributed.

If the goal is to run the queries across processes or workers, it may be useful to use Query.Serialize and Query.Deserialize to serialize the query.

CollectionIterator is an iterator over sub-collections of a document.

GetAll returns all the collections remaining from the iterator.

Next returns the next result. Its second return value is iterator.Done if there are no more results. Once Next returns Done, all subsequent calls will return Done.

PageInfo supports pagination. See the google.golang.org/api/iterator package for details.

CollectionOption is an option for a Collection pipeline stage.

A CollectionRef is a reference to Firestore collection.

Add generates a DocumentRef with a unique ID. It then creates the document with the given data, which can be a map[string]interface{}, a struct or a pointer to a struct.

Add returns an error in the unlikely event that a document with the same ID already exists.

Doc returns a DocumentRef that refers to the document in the collection with the given identifier.

DocumentRefs returns references to all the documents in the collection, including missing documents. A missing document is a document that does not exist but has sub-documents.

NewDoc returns a DocumentRef with a uniquely generated ID.

NewDoc will panic if crypto/rand cannot generate enough bytes to make a new doc ID.

WithReadOptions specifies constraints for accessing documents from the database, e.g. at what time snapshot to read the documents.

CollectionSourceOption is an option that can be applied to both Collection and CollectionGroup pipeline stages.

WithForceIndex specifies an index to force the query to use.

WithIgnoreIndexFields specifies fields to ignore when selecting an index.

CommitResponse exposes information about a committed transaction.

CommitTime returns the commit time from the commit response.

CompositeFilter represents a composite Firestore filter.

DatabaseOption is an option for a Database pipeline stage.

DefineOption is an option for a Define pipeline stage.

DeleteOption is an option for a Delete pipeline stage.

Experimental: Update, Delete and Search stages in pipeline queries are in public preview and are subject to potential breaking changes in future versions, regardless of any other documented package stability guarantees.

Direction is the sort direction for result ordering.

DistanceMeasure is the distance measure to use when comparing vectors with [Query.FindNearest] or [Query.FindNearestPath].

DistinctOption is an option for a Distinct pipeline stage.

A DocumentChange describes the change to a document from one query snapshot to the next.

DocumentChangeKind describes the kind of change to a document between query snapshots.

String returns the string representation of the DocumentChangeKind.

DocumentIterator is an iterator over documents returned by a query.

ExplainMetrics returns query explain metrics. This is only present when [ExplainOptions] is added to the query (see [Query.WithRunOptions]), and after the iterator reaches the end. An error is returned if either of those conditions does not hold.

GetAll returns all the documents remaining from the iterator. It is not necessary to call Stop on the iterator after calling GetAll.

Next returns the next result. Its second return value is iterator.Done if there are no more results. Once Next returns Done, all subsequent calls will return Done.

Stop stops the iterator, freeing its resources. Always call Stop when you are done with a DocumentIterator. It is not safe to call Stop concurrently with Next.

A DocumentRef is a reference to a Firestore document.

Collection returns a reference to sub-collection of this document.

Collections returns an iterator over the immediate sub-collections of the document.

Create creates the document with the given data. It returns an error if a document with the same ID already exists.

The data argument can be a map with string keys, a struct, or a pointer to a struct. The map keys or exported struct fields become the fields of the firestore document. The values of data are converted to Firestore values as follows:

• bool converts to Bool.
• string converts to String.
• int, int8, int16, int32 and int64 convert to Integer.
• uint8, uint16 and uint32 convert to Integer. uint, uint64 and uintptr are disallowed, because they may be able to represent values that cannot be represented in an int64, which is the underlying type of a Integer.
• float32 and float64 convert to Double.
• []byte converts to Bytes.
• time.Time and *ts.Timestamp convert to Timestamp. ts is the package "google.golang.org/protobuf/types/known/timestamppb".
• *latlng.LatLng converts to GeoPoint. latlng is the package "google.golang.org/genproto/googleapis/type/latlng". You should always use a pointer to a LatLng.
• Slices convert to Array.
• *firestore.DocumentRef converts to Reference.
• Maps and structs convert to Map.
• nils of any type convert to Null.

Pointers and interface{} are also permitted, and their elements processed recursively.

Struct fields can have tags like those used by the encoding/json package. Tags begin with "firestore:" and are followed by "-", meaning "ignore this field," or an alternative name for the field. Following the name, these comma-separated options may be provided:

• omitempty: Do not encode this field if it is empty. A value is empty if it is a zero value, or an array, slice or map of length zero.
• serverTimestamp: The field must be of type time.Time. serverTimestamp is a sentinel token that tells Firestore to substitute the server time into that field. When writing, if the field has the zero value, the server will populate the stored document with the time that the request is processed. However, if the field value is non-zero it won't be saved.