func ArrayRemove(elems ...interface{}) arrayRemove

package main
import (
	"context"
	"fmt"
	"cloud.google.com/go/firestore"
)
func main() {
	ctx := context.Background()
	client, err := firestore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	defer client.Close()
	co := client.Doc("States/Colorado")
	wr, err := co.Update(ctx, []firestore.Update{
		{Path: "cities", Value: firestore.ArrayRemove("Denver")},
	})
	if err != nil {
		// TODO: Handle error.
	}
	fmt.Println(wr.UpdateTime)
}

func ArrayUnion(elems ...interface{}) arrayUnion

package main
import (
	"context"
	"fmt"
	"cloud.google.com/go/firestore"
)
func main() {
	ctx := context.Background()
	client, err := firestore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	defer client.Close()
	wr, err := client.Doc("States/Colorado").Create(ctx, map[string]interface{}{
		"cities": firestore.ArrayUnion("Denver", "Golden", "Boulder"),
		"pop":    5.5,
	})
	if err != nil {
		// TODO: Handle error.
	}
	fmt.Println(wr.UpdateTime)
}

package main
import (
	"context"
	"fmt"
	"cloud.google.com/go/firestore"
)
func main() {
	ctx := context.Background()
	client, err := firestore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	defer client.Close()
	co := client.Doc("States/Colorado")
	wr, err := co.Update(ctx, []firestore.Update{
		{Path: "cities", Value: firestore.ArrayUnion("Broomfield")},
	})
	if err != nil {
		// TODO: Handle error.
	}
	fmt.Println(wr.UpdateTime)
}

func FieldTransformIncrement(n interface{}) transform

func FieldTransformMaximum(n interface{}) transform

func FieldTransformMinimum(n interface{}) transform

func Increment(n interface{}) transform

package main
import (
	"context"
	"fmt"
	"cloud.google.com/go/firestore"
)
func main() {
	ctx := context.Background()
	client, err := firestore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	defer client.Close()
	wr, err := client.Doc("States/Colorado").Create(ctx, map[string]interface{}{
		"cities": []string{"Denver", "Golden", "Boulder"},
		"pop":    firestore.Increment(7), // "pop" will be set to 7.
	})
	if err != nil {
		// TODO: Handle error.
	}
	fmt.Println(wr.UpdateTime)
}

package main
import (
	"context"
	"fmt"
	"cloud.google.com/go/firestore"
)
func main() {
	ctx := context.Background()
	client, err := firestore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	defer client.Close()
	co := client.Doc("States/Colorado")
	wr, err := co.Update(ctx, []firestore.Update{
		{Path: "pop", Value: firestore.Increment(7)}, // "pop" will incremented by 7.
	})
	if err != nil {
		// TODO: Handle error.
	}
	fmt.Println(wr.UpdateTime)
}

func MaxAttempts(n int) maxAttempts

func WithCommitResponseTo(r *CommitResponse) commitResponse

type AddFieldsOption interface {
	StageOption
}

type AggregateFunction interface {
	As(alias string) *AliasedAggregate

}

func ArrayAgg(fieldOrExpr any) AggregateFunction

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.

func ArrayAggDistinct(fieldOrExpr any) AggregateFunction

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.

func Average(fieldOrExpr any) AggregateFunction

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")

func Count(fieldOrExpr any) AggregateFunction

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(...)

func CountAll() AggregateFunction

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

Example:

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

func CountDistinct(fieldOrExpr any) AggregateFunction

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(...)

func CountIf(condition BooleanExpression) AggregateFunction

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")

func First(fieldOrExpr any) AggregateFunction

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

func Last(fieldOrExpr any) AggregateFunction

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

func Maximum(fieldOrExpr any) AggregateFunction

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(...)

func Minimum(fieldOrExpr any) AggregateFunction

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")

func Sum(fieldOrExpr any) AggregateFunction

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(...)

type AggregateOption interface {
	StageOption
}

func WithAggregateGroups(groups ...any) AggregateOption

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.

type AggregationQuery struct {
}

Get retrieves the aggregation query results from the service.

GetResponse runs the aggregation with the options provided in the query

func (aq *AggregationQuery) Pipeline() *Pipeline

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.

func (a *AggregationQuery) Transaction(tx *Transaction) *AggregationQuery

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.

type AggregationResponse struct {
	Result AggregationResult


	ExplainMetrics *ExplainMetrics
}

type AggregationResult map[string]interface{}

func (ar AggregationResult) Data() map[string]interface{}

Data returns the AggregationResult's fields as a map of native Go types. It is equivalent to

var m map[string]interface{}
ar.DataTo(&m)

func (ar AggregationResult) DataTo(p interface{}) error

DataTo uses the aggregation result's fields to populate p, which can be a pointer to a map[string]interface{} or a pointer to a struct.

See DocumentSnapshot.DataTo for how Firestore values are converted to Go values.

type AliasedAggregate struct {
}

func Accumulators(a ...*AliasedAggregate) []*AliasedAggregate

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.

type AliasedExpression struct {
}

func AliasedExpressions(v ...*AliasedExpression) []*AliasedExpression

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.

type AndFilter struct {
	Filters []EntityFilter
}

type BSONBinary struct {
	Subtype byte
	Data    []byte
}

type BSONMaxKey struct{}

type BSONMinKey struct{}

String returns the string representation of the BSONObjectID.

type BSONTimestamp struct {
	Seconds   uint32
	Increment uint32
}

type BooleanExpression interface {
	Expression


	Conditional(thenVal, elseVal any) Expression


	IfErrorBoolean(catchExpr BooleanExpression) BooleanExpression

	Not() BooleanExpression


	CountIf() AggregateFunction
}

func And ¶ added in v1.21.0

func And(condition BooleanExpression, right ...BooleanExpression) BooleanExpression

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

func ArrayContains(exprOrFieldPath any, value any) BooleanExpression

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")

func ArrayContainsAll(exprOrFieldPath any, values any) BooleanExpression

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"})

func ArrayContainsAny(exprOrFieldPath any, values any) BooleanExpression

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.

func EndsWith(exprOrFieldPath any, suffix any) BooleanExpression

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")

func Equal(left, right any) BooleanExpression

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")

func EqualAny(exprOrFieldPath any, values any) BooleanExpression

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"})

func FieldExists(exprOrField any) BooleanExpression

FieldExists creates an expression that checks if a field exists.

func GreaterThan(left, right any) BooleanExpression

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"))

func GreaterThanOrEqual(left, right any) BooleanExpression

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"))

func IfErrorBoolean(tryExpr BooleanExpression, catchExpr BooleanExpression) BooleanExpression

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.

func IsAbsent(exprOrField any) BooleanExpression

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

func IsError(expr Expression) BooleanExpression

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"

func LessThan(left, right any) BooleanExpression

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"))

func LessThanOrEqual(left, right any) BooleanExpression

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"))

func Like(exprOrFieldPath any, pattern any) BooleanExpression

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%")

func Nor(condition BooleanExpression, right ...BooleanExpression) BooleanExpression

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

func Not(condition BooleanExpression) BooleanExpression

Not creates an expression that negates a boolean expression.

func NotEqual(left, right any) BooleanExpression

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")

func NotEqualAny(exprOrFieldPath any, values any) BooleanExpression

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"})

func Or(condition BooleanExpression, right ...BooleanExpression) BooleanExpression

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.

func RegexContains(exprOrFieldPath any, pattern any) BooleanExpression

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$")

func RegexMatch(exprOrFieldPath any, pattern any) BooleanExpression

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}$")

func StartsWith(exprOrFieldPath any, prefix any) BooleanExpression

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.")

func StringContains(exprOrFieldPath any, substring any) BooleanExpression

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")

func Xor(condition BooleanExpression, right ...BooleanExpression) BooleanExpression

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

type BulkWriter struct {
}

func (bw *BulkWriter) Create(doc *DocumentRef, datum interface{}) (*BulkWriterJob, error)

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.

func (bw *BulkWriter) Delete(doc *DocumentRef, preconds ...Precondition) (*BulkWriterJob, error)

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.

func (bw *BulkWriter) End()

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.

func (bw *BulkWriter) Flush()

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

func (bw *BulkWriter) Set(doc *DocumentRef, datum interface{}, opts ...SetOption) (*BulkWriterJob, error)

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.

func (bw *BulkWriter) Update(doc *DocumentRef, updates []Update, preconds ...Precondition) (*BulkWriterJob, error)

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.

type BulkWriterJob struct {
}

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

type Client struct {
	UsesEmulator bool

}

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

package main
import (
	"context"
	"cloud.google.com/go/firestore"
)
func main() {
	ctx := context.Background()
	client, err := firestore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	defer client.Close() // Close client when done.
	_ = client           // TODO: Use client.
}

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

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

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.

package main
import (
	"context"
	"fmt"
	"cloud.google.com/go/firestore"
)
func main() {
	ctx := context.Background()
	client, err := firestore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	defer client.Close()
	coll1 := client.Collection("States")
	coll2 := client.Collection("States/NewYork/Cities")
	fmt.Println(coll1, coll2)
}

func (c *Client) CollectionGroup(collectionID string) *CollectionGroupRef

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.

package main
import (
	"context"
	"cloud.google.com/go/firestore"
)
func main() {
	// Given:
	// France/Cities/Paris = {population: 100}
	// Canada/Cities/Montreal = {population: 95}
	ctx := context.Background()
	client, err := firestore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	defer client.Close()
	// Query for ANY city with >95 pop, regardless of country.
	docs, err := client.CollectionGroup("Cities").
		Where("pop", ">", 95).
		OrderBy("pop", firestore.Desc).
		Limit(10).
		Documents(ctx).
		GetAll()
	if err != nil {
		// TODO: Handle error.
	}
	_ = docs // TODO: Use docs.
}

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.

package main
import (
	"context"
	"fmt"
	"cloud.google.com/go/firestore"
)
func main() {
	ctx := context.Background()
	client, err := firestore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	defer client.Close()
	doc1 := client.Doc("States/NewYork")
	doc2 := client.Doc("States/NewYork/Cities/Albany")
	fmt.Println(doc1, doc2)
}

func (c *Client) DocFromFullPath(fullPath string) *DocumentRef

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.

package main
import (
	"context"
	"fmt"
	"cloud.google.com/go/firestore"
)
func main() {
	ctx := context.Background()
	client, err := firestore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	defer client.Close()
	docs, err := client.GetAll(ctx, []*firestore.DocumentRef{
		client.Doc("States/NorthCarolina"),
		client.Doc("States/SouthCarolina"),
		client.Doc("States/WestCarolina"),
		client.Doc("States/EastCarolina"),
	})
	if err != nil {
		// TODO: Handle error.
	}
	// docs is a slice with four DocumentSnapshots, but the last two are
	// nil because there is no West or East Carolina.
	fmt.Println(docs)
}

func (c *Client) Pipeline() *PipelineSource

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.

package main
import (
	"context"
	"cloud.google.com/go/firestore"
)
func main() {
	ctx := context.Background()
	client, err := firestore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	defer client.Close()
	// write the CommitResponse here, via firestore.WithCommitResponse (below)
	var cr firestore.CommitResponse
	nm := client.Doc("States/NewMexico")
	err = client.RunTransaction(ctx, func(ctx context.Context, tx *firestore.Transaction) error {
		doc, err := tx.Get(nm) // tx.Get, NOT nm.Get!
		if err != nil {
			return err
		}
		pop, err := doc.DataAt("pop")
		if err != nil {
			return err
		}
		return tx.Update(nm, []firestore.Update{{Path: "pop", Value: pop.(float64) + 0.2}})
	}, firestore.WithCommitResponseTo(&cr))
	if err != nil {
		// TODO: Handle error.
	}
	// CommitResponse can be accessed here
}

func (c *Client) WithAlwaysUseImplicitOrderBy(b bool) *Client

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.

func (c *Client) WithReadOptions(opts ...ReadOption) *Client

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

type CollectionGroupOption interface {
	StageOption
}

type CollectionGroupRef struct {

	Query
}

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.

type CollectionIterator struct {
}

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.

In addition, if Next returns an error other than iterator.Done, all subsequent calls will return the same error. To continue iteration, a new CollectionIterator must be created.

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

type CollectionOption interface {
	StageOption
}

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.

package main
import (
	"context"
	"fmt"
	"cloud.google.com/go/firestore"
)
func main() {
	ctx := context.Background()
	client, err := firestore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	defer client.Close()
	doc, wr, err := client.Collection("Users").Add(ctx, map[string]interface{}{
		"name":  "Alice",
		"email": "aj@example.com",
	})
	if err != nil {
		// TODO: Handle error.
	}
	fmt.Println(doc, wr)
}

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

package main
import (
	"context"
	"fmt"
	"cloud.google.com/go/firestore"
)
func main() {
	ctx := context.Background()
	client, err := firestore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	defer client.Close()
	fl := client.Collection("States").Doc("Florida")
	ta := client.Collection("States").Doc("Florida/Cities/Tampa")
	fmt.Println(fl, ta)
}

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.

func (c *CollectionRef) NewDoc() *DocumentRef

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.

package main
import (
	"context"
	"fmt"
	"cloud.google.com/go/firestore"
)
func main() {
	ctx := context.Background()
	client, err := firestore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	defer client.Close()
	doc := client.Collection("Users").NewDoc()
	fmt.Println(doc)
}

func (c *CollectionRef) WithReadOptions(opts ...ReadOption) *CollectionRef

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

type CollectionSourceOption interface {
	CollectionOption
	CollectionGroupOption
}

WithForceIndex specifies an index to force the query to use.

func WithIgnoreIndexFields(fields ...string) CollectionSourceOption

WithIgnoreIndexFields specifies fields to ignore when selecting an index.

type CommitResponse struct {
}

CommitTime returns the commit time from the commit response.

type CompositeFilter interface {
	EntityFilter
}

type DatabaseOption interface {
	StageOption
}

type DefineOption interface {
	StageOption
}

type DeleteOption interface {
	StageOption
}

type DistanceMeasure int32

type DistinctOption interface {
	StageOption
}

type DocumentChange struct {
	Kind DocumentChangeKind
	Doc  *DocumentSnapshot


	OldDoc *DocumentSnapshot


	OldIndex int


	NewIndex int
}

type DocumentChangeKind int

const (

	DocumentAdded DocumentChangeKind = iota

	DocumentRemoved

	DocumentModified
)

String returns the string representation of the DocumentChangeKind.

type DocumentIterator struct {
}

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.

package main
import (
	"context"
	"fmt"
	"cloud.google.com/go/firestore"
)
func main() {
	ctx := context.Background()
	client, err := firestore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	defer client.Close()
	q := client.Collection("States").
		Where("pop", ">", 10).
		OrderBy("pop", firestore.Desc).
		Limit(10) // a good idea with GetAll, to avoid filling memory
	docs, err := q.Documents(ctx).GetAll()
	if err != nil {
		// TODO: Handle error.
	}
	for _, doc := range docs {
		fmt.Println(doc.Data())
	}
}

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.

In addition, if Next returns an error other than iterator.Done, all subsequent calls will return the same error. To continue iteration, a new DocumentIterator must be created.

package main
import (
	"context"
	"fmt"
	"cloud.google.com/go/firestore"
	"google.golang.org/api/iterator"
)
func main() {
	ctx := context.Background()
	client, err := firestore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	defer client.Close()
	q := client.Collection("States").
		Where("pop", ">", 10).
		OrderBy("pop", firestore.Desc)
	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())
	}
}

func (it *DocumentIterator) Stop()

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.

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

package main
import (
	"context"
	"fmt"
	"cloud.google.com/go/firestore"
)
func main() {
	ctx := context.Background()
	client, err := firestore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	defer client.Close()
	mi := client.Collection("States").Doc("Michigan")
	cities := mi.Collection("Cities")
	fmt.Println(cities)
}

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.

package main
import (
	"context"
	"fmt"
	"cloud.google.com/go/firestore"
)
func main() {
	ctx := context.Background()
	client, err := firestore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	defer client.Close()
	wr, err := client.Doc("States/Colorado").Create(ctx, map[string]interface{}{
		"capital": "Denver",
		"pop":     5.5,
	})
	if err != nil {
		// TODO: Handle error.
	}
	fmt.Println(wr.UpdateTime)
}

package main
import (
	"context"
	"fmt"
	"cloud.google.com/go/firestore"
)
func main() {
	ctx := context.Background()
	client, err := firestore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	defer client.Close()
	type State struct {
		Capital    string  `firestore:"capital"`
		Population float64 `firestore:"pop"` // in millions
	}
	wr, err := client.Doc("States/Colorado").Create(ctx, State{
		Capital:    "Denver",
		Population: 5.5,
	})
	if err != nil {
		// TODO: Handle error.
	}
	fmt.Println(wr.UpdateTime)
}

Delete deletes the document. If the document doesn't exist, it does nothing and returns no error.

package main
import (
	"context"
	"cloud.google.com/go/firestore"
)
func main() {
	ctx := context.Background()
	client, err := firestore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	defer client.Close()
	// Oops, Ontario is a Canadian province...
	if _, err = client.Doc("States/Ontario").Delete(ctx); err != nil {
		// TODO: Handle error.
	}
}

Get retrieves the document. If the document does not exist, Get return a NotFound error, which can be checked with

status.Code(err) == codes.NotFound

In that case, Get returns a non-nil DocumentSnapshot whose Exists method return false and whose ReadTime is the time of the failed read operation.

package main
import (
	"context"
	"cloud.google.com/go/firestore"
)
func main() {
	ctx := context.Background()
	client, err := firestore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	defer client.Close()
	docsnap, err := client.Doc("States/Ohio").Get(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	_ = docsnap // TODO: Use DocumentSnapshot.
}

Set creates or overwrites the document with the given data. See DocumentRef.Create for the acceptable values of data. Without options, Set overwrites the document completely. Specify one of the Merge options to preserve an existing document's fields. To delete some fields, use a Merge option with firestore.Delete as the field value.

package main
import (
	"context"
	"fmt"
	"cloud.google.com/go/firestore"
)
func main() {
	ctx := context.Background()
	client, err := firestore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	defer client.Close()
	// Overwrite the document with the given data. Any other fields currently
	// in the document will be removed.
	wr, err := client.Doc("States/Alabama").Set(ctx, map[string]interface{}{
		"capital": "Montgomery",
		"pop":     4.9,
	})
	if err != nil {
		// TODO: Handle error.
	}
	fmt.Println(wr.UpdateTime)
}

package main
import (
	"context"
	"cloud.google.com/go/firestore"
)
func main() {
	ctx := context.Background()
	client, err := firestore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	defer client.Close()
	// Overwrite only the fields in the map; preserve all others.
	_, err = client.Doc("States/Alabama").Set(ctx, map[string]interface{}{
		"pop": 5.2,
	}, firestore.MergeAll)
	if err != nil {
		// TODO: Handle error.
	}
	type State struct {
		Capital    string  `firestore:"capital"`
		Population float64 `firestore:"pop"` // in millions
	}
	// To do a merging Set with struct data, specify the exact fields to overwrite.
	// MergeAll is disallowed here, because it would probably be a mistake: the "capital"
	// field would be overwritten with the empty string.
	_, err = client.Doc("States/Alabama").Set(ctx, State{Population: 5.2}, firestore.Merge([]string{"pop"}))
	if err != nil {
		// TODO: Handle error.
	}
}

Snapshots returns an iterator over snapshots of the document. Each time the document changes or is added or deleted, a new snapshot will be generated.

package main
import (
	"context"
	"cloud.google.com/go/firestore"
)
func main() {
	ctx := context.Background()
	client, err := firestore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	defer client.Close()
	iter := client.Doc("States/Idaho").Snapshots(ctx)
	defer iter.Stop()
	for {
		docsnap, err := iter.Next()
		if err != nil {
			// TODO: Handle error.
		}
		_ = docsnap // TODO: Use DocumentSnapshot.
	}
}

Update updates the document. The values at the given field paths are replaced, but other fields of the stored document are untouched.

package main
import (
	"context"
	"fmt"
	"cloud.google.com/go/firestore"
)
func main() {
	ctx := context.Background()
	client, err := firestore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	defer client.Close()
	tenn := client.Doc("States/Tennessee")
	wr, err := tenn.Update(ctx, []firestore.Update{
		{Path: "pop", Value: 6.6},
		{FieldPath: []string{".", "*", "/"}, Value: "odd"},
	})
	if err != nil {
		// TODO: Handle error.
	}
	fmt.Println(wr.UpdateTime)
}

func (d *DocumentRef) WithReadOptions(opts ...ReadOption) *DocumentRef

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

type DocumentRefIterator struct {
}

GetAll returns all the DocumentRefs 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.

In addition, if Next returns an error other than iterator.Done, all subsequent calls will return the same error. To continue iteration, a new DocumentRefIterator must be created.

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

func (d *DocumentSnapshot) Data() map[string]interface{}

Data returns the DocumentSnapshot's fields as a map. It is equivalent to

var m map[string]interface{}
d.DataTo(&m)

except that it returns nil if the document does not exist.

package main
import (
	"context"
	"fmt"
	"cloud.google.com/go/firestore"
)
func main() {
	ctx := context.Background()
	client, err := firestore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	defer client.Close()
	docsnap, err := client.Doc("States/Ohio").Get(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	ohioMap := docsnap.Data()
	fmt.Println(ohioMap["capital"])
}

DataAt returns the data value denoted by path.

The path argument can be a single field or a dot-separated sequence of fields, and must not contain any of the runes "˜*/[]". Use DataAtPath instead for such a path.

See DocumentSnapshot.DataTo for how Firestore values are converted to Go values.

If the document does not exist, DataAt returns a NotFound error.

package main
import (
	"context"
	"fmt"
	"cloud.google.com/go/firestore"
)
func main() {
	ctx := context.Background()
	client, err := firestore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	defer client.Close()
	docsnap, err := client.Doc("States/Ohio").Get(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	cap, err := docsnap.DataAt("capital")
	if err != nil {
		// TODO: Handle error.
	}
	fmt.Println(cap)
}

func (d *DocumentSnapshot) DataAtPath(fp FieldPath) (interface{}, error)

DataAtPath returns the data value denoted by the FieldPath fp. If the document does not exist, DataAtPath returns a NotFound error.

package main
import (
	"context"
	"fmt"
	"cloud.google.com/go/firestore"
)
func main() {
	ctx := context.Background()
	client, err := firestore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	defer client.Close()
	docsnap, err := client.Doc("States/Ohio").Get(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	pop, err := docsnap.DataAtPath([]string{"capital", "population"})
	if err != nil {
		// TODO: Handle error.
	}
	fmt.Println(pop)
}

func (d *DocumentSnapshot) DataTo(p interface{}) error

DataTo uses the document's fields to populate p, which can be a pointer to a map[string]interface{} or a pointer to a struct.

Firestore field values are converted to Go values as follows:

• Null converts to nil.
• Bool converts to bool.
• String converts to string.
• Integer converts int64. When setting a struct field, any signed or unsigned integer type is permitted except uint, uint64 or uintptr. Overflow is detected and results in an error.
• Double converts to float64. When setting a struct field, float32 is permitted. Overflow is detected and results in an error.
• Bytes is converted to []byte.
• Timestamp converts to time.Time.
• GeoPoint converts to *latlng.LatLng, where latlng is the package "google.golang.org/genproto/googleapis/type/latlng".
• Arrays convert to []interface{}. When setting a struct field, the field may be a slice or array of any type and is populated recursively. Slices are resized to the incoming value's size, while arrays that are too long have excess elements filled with zero values. If the array is too short, excess incoming values will be dropped.
• Vectors convert to []float64
• Maps convert to map[string]interface{}. When setting a struct field, maps of key type string and any value type are permitted, and are populated recursively.
• References are converted to *firestore.DocumentRefs.

Field names given by struct field tags are observed, as described in DocumentRef.Create.

Only the fields actually present in the document are used to populate p. Other fields of p are left unchanged.

If the document does not exist, DataTo returns a NotFound error.

package main
import (
	"context"
	"fmt"
	"cloud.google.com/go/firestore"
)
func main() {
	ctx := context.Background()
	client, err := firestore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	defer client.Close()
	docsnap, err := client.Doc("States/Ohio").Get(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	type State struct {
		Capital    string  `firestore:"capital"`
		Population float64 `firestore:"pop"` // in millions
	}
	var s State
	if err := docsnap.DataTo(&s); err != nil {
		// TODO: Handle error.
	}
	fmt.Println(s)
}

Exists reports whether the DocumentSnapshot represents an existing document. Even if Exists returns false, the Ref and ReadTime fields of the DocumentSnapshot are valid.

type DocumentSnapshotIterator struct {
}

Next blocks until the document changes, then returns the DocumentSnapshot for the current state of the document. If the document has been deleted, Next returns a DocumentSnapshot whose Exists method returns false.

Next is not expected to return iterator.Done unless it is called after Stop. Rarely, networking issues may also cause iterator.Done to be returned.

In addition, if Next returns an error other than iterator.Done, all subsequent calls will return the same error. To continue iteration, a new DocumentSnapshotIterator must be created.

func (it *DocumentSnapshotIterator) Stop()

Stop stops receiving snapshots. You should always call Stop when you are done with a DocumentSnapshotIterator, to free up resources. It is not safe to call Stop concurrently with Next.

type DocumentsOption interface {
	StageOption
}

type EntityFilter interface {
}

type ExecuteOption interface {
}

func WithExplainMode(mode ExplainMode) ExecuteOption

WithExplainMode sets the execution mode for pipeline explain.

type ExplainMetrics struct {

	PlanSummary *PlanSummary


	ExecutionStats *ExecutionStats
}

const (

	ExplainModeAnalyze ExplainMode = "analyze"
)

type ExplainOptions struct {


	Analyze bool
}

type ExplainStats struct {
}

RawData returns the explain stats in an encoded proto format, as returned from the Firestore backend. The caller is responsible for unpacking this proto message.

Text returns the explain stats as a string from the Firestore backend. If explain stats were requested with `outputFormat = 'text'`, the string is returned verbatim. If `outputFormat = 'json'`, this returns the explain stats as stringified JSON.

type Expression interface {


	Add(other any) Expression


	Subtract(other any) Expression


	Multiply(other any) Expression


	Divide(other any) Expression

	Abs() Expression

	Floor() Expression

	Ceil() Expression

	Exp() Expression


	Log(other any) Expression

	Log10() Expression

	Ln() Expression


	Mod(other any) Expression


	Pow(other any) Expression

	Round() Expression

	RoundToPrecision(places any) Expression

	Trunc() Expression


	TruncToPrecision(places any) Expression

	Sqrt() Expression


	Cmp(other any) Expression


	ArrayContains(value any) BooleanExpression


	ArrayContainsAll(values any) BooleanExpression


	ArrayContainsAny(values any) BooleanExpression

	ArrayLength() Expression


	EqualAny(values any) BooleanExpression


	NotEqualAny(values any) BooleanExpression


	ArrayGet(offset any) Expression


	Offset(index any) Expression

	ArrayReverse() Expression


	ArrayConcat(otherArrays ...any) Expression

	ArraySum() Expression

	ArrayMaximum() Expression


	ArrayMaximumN(n any) Expression

	ArrayMinimum() Expression


	ArrayMinimumN(n any) Expression

	ArrayFirst() Expression


	ArrayFirstN(n any) Expression

	ArrayLast() Expression


	ArrayLastN(n any) Expression


	ArraySliceToEnd(offset any) Expression


	ArraySlice(offset, length any) Expression


	ReferenceSliceToEnd(offset any) Expression


	ReferenceSlice(offset, length any) Expression


	ArrayIndexOf(search any) Expression


	ArrayIndexOfAll(search any) Expression


	ArrayLastIndexOf(search any) Expression

	First() AggregateFunction

	Last() AggregateFunction


	ArrayAgg() AggregateFunction


	ArrayAggDistinct() AggregateFunction


	ArrayFilter(param string, body BooleanExpression) Expression


	ArrayTransform(param string, body Expression) Expression


	ArrayTransformWithIndex(param, indexParam string, body Expression) Expression

	LogicalMaximum(others ...any) Expression

	LogicalMinimum(others ...any) Expression


	TimestampAdd(unit, amount any) Expression


	TimestampSubtract(unit, amount any) Expression


	TimestampTruncate(granularity any) Expression


	TimestampTruncateWithTimezone(granularity any, timezone any) Expression


	TimestampToUnixMicros() Expression


	TimestampToUnixMillis() Expression


	TimestampToUnixSeconds() Expression
	TimestampExtract(part any) Expression
	TimestampExtractWithTimezone(part, timezone any) Expression


	TimestampDiff(start, unit any) Expression

	UnixMicrosToTimestamp() Expression

	UnixMillisToTimestamp() Expression

	UnixSecondsToTimestamp() Expression


	Equal(other any) BooleanExpression


	NotEqual(other any) BooleanExpression


	GreaterThan(other any) BooleanExpression


	GreaterThanOrEqual(other any) BooleanExpression


	LessThan(other any) BooleanExpression


	LessThanOrEqual(other any) BooleanExpression


	Length() Expression

	Reverse() Expression


	Concat(others ...any) Expression


	GetCollectionID() Expression

	GetDocumentID() Expression

	GetParent() Expression


	GetField(key any) Expression


	IfError(catchExprOrValue any) Expression

	IsError() BooleanExpression

	FieldExists() BooleanExpression

	IsAbsent() BooleanExpression


	IfAbsent(catchExprOrValue any) Expression


	IfNull(elseValueOrExpr any) Expression


	Coalesce(replacement any, others ...any) Expression


	MapGet(strOrExprkey any) Expression


	MapMerge(secondMap Expression, otherMaps ...Expression) Expression


	MapRemove(strOrExprkey any) Expression


	MapSet(key any, value any, moreKeysAndValues ...any) Expression

	MapKeys() Expression

	MapValues() Expression

	MapEntries() Expression


	Sum() AggregateFunction

	Average() AggregateFunction

	Count() AggregateFunction

	CountDistinct() AggregateFunction

	Maximum() AggregateFunction

	Minimum() AggregateFunction


	StorageSize() Expression


	ByteLength() Expression

	CharLength() Expression


	EndsWith(suffix any) BooleanExpression


	Like(suffix any) BooleanExpression


	RegexContains(pattern any) BooleanExpression


	RegexFind(pattern any) Expression


	RegexFindAll(pattern any) Expression


	RegexMatch(pattern any) BooleanExpression


	StartsWith(prefix any) BooleanExpression


	StringConcat(otherStrings ...any) Expression


	StringContains(substring any) BooleanExpression


	StringIndexOf(search any) Expression


	StringRepeat(repetition any) Expression


	StringReplaceOne(search, replacement any) Expression


	StringReplaceAll(search, replacement any) Expression

	StringReverse() Expression


	Join(delimiter any) Expression


	Substring(index, offset any) Expression

	ToLower() Expression

	ToUpper() Expression

	Trim() Expression

	TrimValue(valuesToTrim any) Expression

	LTrim() Expression

	LTrimValue(valuesToTrim any) Expression

	RTrim() Expression

	RTrimValue(valuesToTrim any) Expression


	Split(delimiter any) Expression

	Type() Expression


	IsType(dataType string) BooleanExpression


	CosineDistance(other any) Expression


	DotProduct(other any) Expression


	EuclideanDistance(other any) Expression

	VectorLength() Expression


	Ascending() Ordering

	Descending() Ordering


	GeoDistance(location *latlng.LatLng) Expression


	As(alias string) *AliasedExpression
}

func Abs(numericExprOrFieldPath any) Expression

Abs creates an expression that is the absolute value of the input field or expression. - numericExprOrFieldPath can be a field path string, FieldPath or an Expression that returns a number when evaluated.

func Add(left, right any) Expression

Add creates an expression that adds two expressions together, returning it as an Expr. - left can be a field path string, FieldPath or Expression. - right can be a numeric constant or a numeric Expression.

func Array(elements ...any) Expression

Array creates an expression that represents a Firestore array. - elements can be any number of values or expressions that will form the elements of the array.

func ArrayConcat(exprOrFieldPath any, otherArrays ...any) Expression

ArrayConcat creates an expression that concatenates multiple arrays into a single array. - exprOrFieldPath can be a field path string, FieldPath or an Expression that evaluates to an array. - otherArrays are the other arrays to concatenate.

ArrayFilter creates an expression for array_filter(array, param, body). - array can be a field path string, FieldPath or an Expression that evaluates to an array. - param is the name of the parameter to use in the body expression. - body is the expression to evaluate for each element of the array.

func ArrayFirst(exprOrFieldPath any) Expression

ArrayFirst creates an expression that returns the first element of an array. - exprOrFieldPath can be a field path string, FieldPath or an Expression that evaluates to an array.

func ArrayFirstN(exprOrFieldPath any, n any) Expression

ArrayFirstN creates an expression that returns the first N elements of an array. - exprOrFieldPath can be a field path string, FieldPath or an Expression that evaluates to an array. - n can be an int, int32, int64 or Expression.

func ArrayFromSlice[T any](elements []T) Expression

ArrayFromSlice creates a new array expression from a slice of elements. This function is necessary for creating an array from an existing typed slice (e.g., []int), as the Array function (which takes variadic arguments) cannot directly accept a typed slice using the spread operator (...). It handles the conversion of each element to `any` internally.

func ArrayGet(exprOrFieldPath any, offset any) Expression

ArrayGet creates an expression that retrieves an element from an array at a specified index.

This is a typed function. It expects the first argument to be an array. If the target is not an array, the query will fail with a type error. If the target is null, the result is null.

For a version that returns an absent value (UNSET) instead of failing on type mismatch, use Offset.

- exprOrFieldPath can be a field path string, FieldPath or an Expression that evaluates to an array. - offset is the 0-based index of the element to retrieve. Supports negative indexing.

func ArrayIndexOf(exprOrFieldPath any, search any) Expression

ArrayIndexOf creates an expression that returns the first index of a search value in an array. - exprOrFieldPath can be a field path string, FieldPath or an Expression that evaluates to an array. - search is the value to search for. It can be a constant or Expression.

func ArrayIndexOfAll(exprOrFieldPath any, search any) Expression

ArrayIndexOfAll creates an expression that returns the indices of all occurrences of a search value in an array. - exprOrFieldPath can be a field path string, FieldPath or an Expression that evaluates to an array. - search is the value to search for. It can be a constant or Expression.

func ArrayLast(exprOrFieldPath any) Expression

ArrayLast creates an expression that returns the last element of an array. - exprOrFieldPath can be a field path string, FieldPath or an Expression that evaluates to an array.

func ArrayLastIndexOf(exprOrFieldPath any, search any) Expression

ArrayLastIndexOf creates an expression that returns the last index of a search value in an array. - exprOrFieldPath can be a field path string, FieldPath or an Expression that evaluates to an array. - search is the value to search for. It can be a constant or Expression.

func ArrayLastN(exprOrFieldPath any, n any) Expression

ArrayLastN creates an expression that returns the last N elements of an array. - exprOrFieldPath can be a field path string, FieldPath or an Expression that evaluates to an array. - n can be an int, int32, int64 or Expression.

func ArrayLength(exprOrFieldPath any) Expression

ArrayLength creates an expression that calculates the length of an array. - exprOrFieldPath can be a field path string, FieldPath or an Expression that evaluates to an array.

func ArrayMaximum(exprOrFieldPath any) Expression

ArrayMaximum creates an expression that finds the maximum element in a numeric array. - exprOrFieldPath can be a field path string, FieldPath or an Expression that evaluates to a numeric array.

func ArrayMaximumN(exprOrFieldPath any, n any) Expression

ArrayMaximumN creates an expression that finds the N maximum elements in an array. - exprOrFieldPath can be a field path string, FieldPath or an Expression that evaluates to an array. - n can be an int, int32, int64 or Expression.

func ArrayMinimum(exprOrFieldPath any) Expression

ArrayMinimum creates an expression that finds the minimum element in a numeric array. - exprOrFieldPath can be a field path string, FieldPath or an Expression that evaluates to a numeric array.

func ArrayMinimumN(exprOrFieldPath any, n any) Expression

ArrayMinimumN creates an expression that finds the N minimum elements in an array. - exprOrFieldPath can be a field path string, FieldPath or an Expression that evaluates to an array. - n can be an int, int32, int64 or Expression.

func ArrayReverse(exprOrFieldPath any) Expression

ArrayReverse creates an expression that reverses the order of elements in an array. - exprOrFieldPath can be a field path string, FieldPath or an Expression that evaluates to an array.

func ArraySlice(exprOrFieldPath any, offset any, length any) Expression

ArraySlice creates an expression that returns a slice of an array starting from the specified offset with a given length. - exprOrFieldPath can be a field path string, FieldPath or an Expression that evaluates to an array. - offset is the 0-based index of the first element to include. It can be an int, int32, int64 or Expression. - length is the number of elements to include. It can be an int, int32, int64 or Expression.

func ArraySliceToEnd(exprOrFieldPath any, offset any) Expression

ArraySliceToEnd creates an expression that returns a slice of an array starting from the specified offset. - exprOrFieldPath can be a field path string, FieldPath or an Expression that evaluates to an array. - offset is the 0-based index of the first element to include. It can be an int, int32, int64 or Expression.

func ArraySum(exprOrFieldPath any) Expression

ArraySum creates an expression that calculates the sum of all elements in a numeric array. - exprOrFieldPath can be a field path string, FieldPath or an Expression that evaluates to a numeric array.

ArrayTransform applies a transformation to each element of an array. - array can be a field path string, FieldPath or an Expression that evaluates to an array. - param is the name of the parameter to use in the transform expression. - body is the expression to evaluate for each element of the array.

func ArrayTransformWithIndex(array any, param, indexParam string, body Expression) Expression

ArrayTransformWithIndex applies a transformation to each element of an array, providing the index. - array can be a field path string, FieldPath or an Expression that evaluates to an array. - param is the name of the parameter to use in the transform expression for the element. - indexParam is the name of the parameter to use in the transform expression for the index. - body is the expression to evaluate for each element of the array.

func ByteLength(exprOrFieldPath any) Expression

ByteLength creates an expression that calculates the length of a string represented by a field or Expression in UTF-8 bytes.

• exprOrFieldPath can be a field path string, FieldPath or Expression.

func Ceil(numericExprOrFieldPath any) Expression

Ceil creates an expression that is the smallest integer that isn't less than the input field or expression. - numericExprOrFieldPath can be a field path string, FieldPath or an Expression that returns a number when evaluated.

func CharLength(exprOrFieldPath any) Expression

CharLength creates an expression that calculates the character length of a string field or expression in UTF8.

• exprOrFieldPath can be a field path string, FieldPath or Expression.

func Cmp(left, right any) Expression

Cmp creates an expression that compares the left and right expressions, returning it as an Expr. Returns -1 if left < right, 0 if left == right, and 1 if left > right. - left can be a field path string, FieldPath or Expression. - right can be a constant or an Expression.

func Coalesce(exprOrField any, replacement any, others ...any) Expression

Coalesce returns the first non-null, non-absent argument, without evaluating the rest of the arguments. When all arguments are null or absent, returns the last argument. - exprOrField can be a field path string, FieldPath or an Expression. - replacement is the fallback expression or value if the first one evaluates to null or is absent. - others are optional additional expressions or values to check.

func Concat(exprOrField any, others ...any) Expression

Concat creates an expression that concatenates expressions together. - exprOrField can be a field path string, FieldPath or an Expression. - others can be a list of constants or Expression.

Example:

// Concat the 'name' field with a constant string.
Concat("name", "-suffix")

func Conditional(condition BooleanExpression, thenValOrExpr, elseValOrExpr any) Expression

Conditional creates an expression that evaluates a condition and returns one of two expressions. - condition is the boolean expression to evaluate. - thenValOrExpr is the value or expression to return if the condition is true. - elseValOrExpr is the value or expression to return if the condition is false.

func ConstantOf(value any) Expression

ConstantOf creates a new constant Expression from a Go value. It accepts primitive types (strings, numbers, booleans), slices, arrays, maps, structs, and specific Firestore types such as time.Time, *timestamppb.Timestamp, []byte, Vector32, Vector64, *latlng.LatLng, and *DocumentRef.

func ConstantOfNull() Expression

ConstantOfNull creates a new constant Expression representing a null value.

func ConstantOfVector32(value []float32) Expression

ConstantOfVector32 creates a new Vector32 constant Expression from a slice of float32s.

func ConstantOfVector64(value []float64) Expression

ConstantOfVector64 creates a new Vector64 constant Expression from a slice of float64s.

func CosineDistance(vector1 any, vector2 any) Expression

CosineDistance creates an expression that calculates the cosine distance between two vectors.

• vector1 can be a field path string, FieldPath or Expression.
• vector2 can be Vector32, Vector64, []float32, []float64 or Expression.

func CurrentDocument() Expression

CurrentDocument creates an expression that represents the current document being processed.

This expression is useful when you need to access the entire document as a map, or pass the document itself to a function or subquery.

Example:

// Define the current document as a variable "doc"
client.Pipeline().Collection("books").
	Define(AliasedExpressions(CurrentDocument().As("doc"))).
	// Access a field from the defined document variable
	Select(Fields(GetField(Variable("doc"), "title")))

func CurrentTimestamp() Expression

CurrentTimestamp creates an expression that returns the current timestamp.

func Divide(left, right any) Expression

Divide creates an expression that divides the left expression by the right expression, returning it as an Expr. - left can be a field path string, FieldPath or Expression. - right can be a numeric constant or a numeric Expression.

func DotProduct(vector1 any, vector2 any) Expression

DotProduct creates an expression that calculates the dot product of two vectors.

• vector1 can be a field path string, FieldPath or Expression.
• vector2 can be Vector32, Vector64, []float32, []float64 or Expression.

func EuclideanDistance ¶ added in v1.21.0

func EuclideanDistance(vector1 any, vector2 any) Expression

EuclideanDistance creates an expression that calculates the euclidean distance between two vectors.

• vector1 can be a field path string, FieldPath or Expression.
• vector2 can be Vector32, Vector64, []float32, []float64 or Expression.

func Exp(numericExprOrFieldPath any) Expression

Exp creates an expression that is the Euler's number e raised to the power of the input field or expression. - numericExprOrFieldPath can be a field path string, FieldPath or an Expression that returns a number when evaluated.

FieldOf creates a new field Expression from a dot separated field path string or FieldPath.

func Floor(numericExprOrFieldPath any) Expression

Floor creates an expression that is the largest integer that isn't less than the input field or expression. - numericExprOrFieldPath can be a field path string, FieldPath or an Expression that returns a number when evaluated.

GeoDistance creates an expression that evaluates to the distance in meters between the location in the specified field and the query location.

This Expression can only be used within a Search stage.

Example:

client.Pipeline().Collection("restaurants").
	Search(
		WithSearchQuery("waffles"),
		WithSearchSort(Ascending(GeoDistance("location", &latlng.LatLng{Latitude: 37.0, Longitude: -122.0}))),
	)

- field: Specifies the field in the document which contains the GeoPoint for distance computation. It can be a field path string, FieldPath or Expression. - location: Compute distance to this GeoPoint.

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.

func GetCollectionID(exprOrField any) Expression

GetCollectionID creates an expression that returns the ID of the collection that contains the document. - exprOrField can be a field path string, FieldPath or an Expression that evaluates to a field path.

func GetDocumentID(exprStringOrDocRef any) Expression

GetDocumentID creates an expression that returns the ID of the document. - exprStringOrDocRef can be a string, a DocumentRef, or an Expression that evaluates to a document reference.

func GetField(exprOrField any, key any) Expression

GetField creates an expression that accesses a field/property of a document field using the provided key. - exprOrField: The expression representing the document or map. - key: The key of the field to access.

func GetParent(exprStringOrDocRef any) Expression

GetParent creates an expression that returns the parent document of a document reference. - exprStringOrDocRef can be a string representation of the document path, a DocumentRef, or an Expression that evaluates to a document path.

func IfAbsent(exprOrField any, elseValueOrExpr any) Expression

IfAbsent creates an expression that returns a default value if an expression evaluates to an absent value. - exprOrField is the field or expression to check. It can be a field path string, FieldPath or an Expression. - elseValueOrExpr is the value or expression to return if the expression is absent. It can be a constant or an Expression.

func IfError(tryExpr Expression, catchExprOrValue any) Expression

IfError creates an expression that evaluates and returns `tryExpr` if it does not produce an error; otherwise, it evaluates and returns `catchExprOrValue`. It returns a new Expression representing the if_error operation. - tryExpr is the expression to try. - catchExprOrValue is the expression or value to return if `tryExpr` errors.

func IfNull(exprOrField any, elseValueOrExpr any) Expression

IfNull creates an expression that returns a default value if an expression evaluates to null. Note: This function provides a fallback for both absent and explicit null values. In contrast, IfAbsent only triggers for missing fields. - exprOrField can be a field path string, FieldPath or an Expression. - elseValueOrExpr is the default value or expression to return if the first evaluates to null.

func Join(exprOrFieldPath any, delimiter any) Expression

Join creates an expression that joins the elements of a string array into a single string. - exprOrFieldPath can be a field path string, FieldPath or an Expression that evaluates to a string array. - delimiter is the string to use as a separator between elements.

func LTrim(exprOrFieldPath any) Expression

LTrim creates an expression that removes leading whitespace from a string. - exprOrFieldPath can be a field path string, FieldPath or an Expression that evaluates to a string.

func LTrimValue(exprOrFieldPath any, charsOrExprToTrim any) Expression

LTrimValue creates an expression that removes leading whitespace or specified characters from a string. - exprOrFieldPath can be a field path string, FieldPath or an Expression that evaluates to a string. - charsOrExprToTrim is a string or Expression specifying characters to remove.

func Length(exprOrField any) Expression

Length creates an expression that calculates the length of string, array, map or vector. - exprOrField can be a field path string, FieldPath or an Expression that returns a string, array, map or vector when evaluated.

Example:

// Length of the 'name' field.
Length("name")

func Ln(numericExprOrFieldPath any) Expression

Ln creates an expression that is the natural logarithm (base e) of the input field or expression. - numericExprOrFieldPath can be a field path string, FieldPath or an Expression that returns a number when evaluated.

func Log(left, right any) Expression

Log creates an expression that is logarithm of the left expression to base as the right expression, returning it as an Expr. - left can be a field path string, FieldPath or Expression. - right can be a constant or an Expression.

func Log10(numericExprOrFieldPath any) Expression

Log10 creates an expression that is the base 10 logarithm of the input field or expression. - numericExprOrFieldPath can be a field path string, FieldPath or an Expression that returns a number when evaluated.

func LogicalMaximum(exprOrField any, others ...any) Expression

LogicalMaximum creates an expression that evaluates to the maximum value in a list of expressions. - exprOrField can be a field path string, FieldPath or an Expression. - others can be a list of constants or Expression.

func LogicalMinimum(exprOrField any, others ...any) Expression

LogicalMinimum creates an expression that evaluates to the minimum value in a list of expressions. - exprOrField can be a field path string, FieldPath or an Expression. - others can be a list of constants or Expression.

Map creates an expression that creates a Firestore map value from an input object. - elements: The input map to evaluate in the expression.

func MapEntries(exprOrField any) Expression

MapEntries creates an expression that returns the entries of a map as an array of key-value maps. - exprOrField: The expression representing the map.

func MapGet(exprOrField any, strOrExprkey any) Expression

MapGet creates an expression that accesses a value from a map (object) field using the provided key. - exprOrField: The expression representing the map. - strOrExprkey: The key to access in the map.

func MapKeys(exprOrField any) Expression

MapKeys creates an expression that returns the keys of a map as an array. - exprOrField: The expression representing the map.

func MapMerge(exprOrField any, secondMap Expression, otherMaps ...Expression) Expression

MapMerge creates an expression that merges multiple maps into a single map. If multiple maps have the same key, the later value is used. - exprOrField: First map field path string, FieldPath or an Expression - secondMap: Second map expression that will be merged. - otherMaps: Additional maps to merge.

func MapRemove(exprOrField any, strOrExprkey any) Expression

MapRemove creates an expression that removes a key from a map. - exprOrField: The expression representing the map. - strOrExprkey: The key to remove from the map.

func MapSet(exprOrField any, key any, value any, moreKeysAndValues ...any) Expression

MapSet creates an expression that updates a map with key-value pairs. - exprOrField: The expression representing the map. - key: The first key to set. It can be a string or an Expression. - value: The first value to set. It can be a literal value or an Expression. - moreKeysAndValues: Optional additional alternating key and value arguments.

func MapValues(exprOrField any) Expression

MapValues creates an expression that returns the values of a map as an array. - exprOrField: The expression representing the map.

func Mod(left, right any) Expression

Mod creates an expression that computes the modulo of the left expression by the right expression, returning it as an Expr. - left can be a field path string, FieldPath or Expression. - right can be a numeric constant or a numeric Expression.

func Multiply(left, right any) Expression

Multiply creates an expression that multiplies the left and right expressions, returning it as an Expr. - left can be a field path string, FieldPath or Expression. - right can be a numeric constant or a numeric Expression.

func Offset(exprOrFieldPath any, index any) Expression

Offset creates an expression that accesses an element from an array at a specified index.

This is a field access function. If the input is not an array, or if the index is out of bounds, it evaluates to an absent value.

• exprOrFieldPath can be a field path string, FieldPath or an Expression that evaluates to an array.
• index is the 0-based index of the element to retrieve. It can be an int or an Expression. Supports negative indexing (e.g., -1 returns the last element).

func Pow(left, right any) Expression

Pow creates an expression that computes the left expression raised to the power of the right expression, returning it as an Expr. - left can be a field path string, FieldPath or Expression. - right can be a numeric constant or a numeric Expression.

func RTrim(exprOrFieldPath any) Expression

RTrim creates an expression that removes trailing whitespace from a string. - exprOrFieldPath can be a field path string, FieldPath or an Expression that evaluates to a string.

func RTrimValue(exprOrFieldPath any, charsOrExprToTrim any) Expression

RTrimValue creates an expression that removes trailing whitespace or specified characters from a string. - exprOrFieldPath can be a field path string, FieldPath or an Expression that evaluates to a string. - charsOrExprToTrim is a string or Expression specifying characters to remove.

func Rand ¶ added in v1.22.0

Rand returns a pseudo-random floating point number, chosen uniformly between 0.0 (inclusive) and 1.0 (exclusive).

func ReferenceSlice(exprOrFieldPath any, offset any, length any) Expression

ReferenceSlice creates an expression that returns a subset of segments from a document reference with a given length. - exprOrField can be a field path string, FieldPath or an Expression that evaluates to a document reference. - offset is the 0-based index of the first segment to include. It can be an int, int32, int64 or Expression. - length is the number of segments to include. It can be an int, int32, int64 or Expression.

func ReferenceSliceToEnd(exprOrFieldPath any, offset any) Expression

ReferenceSliceToEnd creates an expression that returns a subset of segments from a document reference. - exprOrField can be a field path string, FieldPath or an Expression that evaluates to a document reference. - offset is the 0-based index of the first segment to include. It can be an int, int32, int64 or Expression.

func RegexFind(exprOrField any, pattern any) Expression

RegexFind creates an expression that returns the first substring that matches the specified regex pattern. - exprOrField: The expression representing the string to search. - pattern is the regular expression to search for. It can be a string or Expression that evaluates to a string.

func RegexFindAll(exprOrField any, pattern any) Expression

RegexFindAll creates an expression that returns all substrings that match the specified regex pattern. - exprOrField: The expression representing the string to search. - pattern is the regular expression to search for. It can be a string or Expression that evaluates to a string.

This expression uses the [RE2](https://github.com/google/re2/wiki/Syntax) regular expression syntax.

func Reverse(exprOrField any) Expression

Reverse creates an expression that reverses a string, or array. - exprOrField can be a field path string, FieldPath or an Expression that returns a string, or array when evaluated.

Example:

// Reverse the 'name' field.

Reverse("name")

func Round(numericExprOrFieldPath any) Expression

Round creates an expression that rounds the input field or expression to nearest integer. - numericExprOrFieldPath can be a field path string, FieldPath or an Expression that returns a number when evaluated.

func RoundToPrecision(numericExprOrFieldPath any, places any) Expression

RoundToPrecision creates an expression that rounds a number to a specified number of decimal places. If places is positive, rounds off digits to the right of the decimal point. If places is negative, rounds off digits to the left of the decimal point. - numericExprOrFieldPath can be a field path string, FieldPath or an Expression that returns a number when evaluated. - places can be an int, int32, int64 or Expression.

Score creates an expression that evaluates to the search score that reflects the topicality of the document to all of the text predicates (for example: DocumentMatches) in the search query.

This Expression can only be used within a Search stage.

Example:

client.Pipeline().Collection("restaurants").
	Search(WithSearchQuery("waffles"), WithSearchSort(Descending(Score())))

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.

func Split(exprOrFieldPath any, delimiter any) Expression

Split creates an expression that splits a string by a delimiter. - exprOrFieldPath can be a field path string, FieldPath or an Expression that evaluates to a string. - delimiter is the string to use to split by.

func Sqrt(numericExprOrFieldPath any) Expression

Sqrt creates an expression that is the square root of the input field or expression. - numericExprOrFieldPath can be a field path string, FieldPath or an Expression that returns a number when evaluated.

func StorageSize(exprOrFieldPath any) Expression

StorageSize creates an expression that calculates the storage size of a field or Expression in bytes.

• exprOrFieldPath can be a field path string, FieldPath or Expression.

func StringConcat(exprOrFieldPath any, otherStrings ...any) Expression

StringConcat creates an expression that concatenates multiple strings into a single string. - exprOrFieldPath can be a field path string, FieldPath or an Expression that evaluates to a string. - otherStrings are optional additional string expressions or string constants to concatenate.

func StringIndexOf(exprOrFieldPath any, search any) Expression

StringIndexOf creates an expression that returns the index of a search value in a string. - exprOrFieldPath can be a field path string, FieldPath or an Expression that evaluates to a string. - search is the value to search for. It can be a string or Expression.

func StringRepeat(exprOrFieldPath any, repetition any) Expression

StringRepeat creates an expression that repeats a string a specified number of times. - exprOrFieldPath can be a field path string, FieldPath or an Expression that evaluates to a string. - repetition is the number of times to repeat the string. It can be an int, int32, int64 or Expression.

func StringReplaceAll(exprOrFieldPath any, search, replacement any) Expression

StringReplaceAll creates an expression that replaces all occurrences of a search value with a replacement value. - exprOrFieldPath can be a field path string, FieldPath or an Expression that evaluates to a string. - search is the value to search for. It can be a string or Expression. - replacement is the value to replace with. It can be a string or Expression.

func StringReplaceOne(exprOrFieldPath any, search, replacement any) Expression

StringReplaceOne creates an expression that replaces the first occurrence of a search value with a replacement value. - exprOrFieldPath can be a field path string, FieldPath or an Expression that evaluates to a string. - search is the value to search for. It can be a string or Expression. - replacement is the value to replace with. It can be a string or Expression.

func StringReverse(exprOrFieldPath any) Expression

StringReverse creates an expression that reverses a string. - exprOrFieldPath can be a field path string, FieldPath or an Expression that evaluates to a string.

func Substring(exprOrFieldPath any, index any, length any) Expression

Substring creates an expression that returns a substring of a string. - exprOrFieldPath can be a field path string, FieldPath or an Expression that evaluates to a string. - index is the starting index of the substring. - length is the length of the substring.

func Subtract(left, right any) Expression

Subtract creates an expression that subtracts the right expression from the left expression, returning it as an Expr. - left can be a field path string, FieldPath or Expression. - right can be a numeric constant or a numeric Expression.

func SwitchOn(condition BooleanExpression, result any, others ...any) Expression

SwitchOn creates an expression that evaluates to the result corresponding to the first true condition.

This function behaves like a `switch` statement. It accepts an alternating sequence of conditions and their corresponding results. If an odd number of arguments is provided, the final argument serves as a default fallback result. If no default is provided and no condition evaluates to true, it throws an error.

• condition: The first condition to check. Must be a BooleanExpression.
• result: The result to return if the first condition is true. Can be an Expression or a literal value.
• others: Additional alternating conditions and results, optionally followed by a default fallback value.

Example:

firestore.SwitchOn(
    firestore.FieldOf("score").GreaterThan(90), "A",
    firestore.FieldOf("score").GreaterThan(80), "B",
    "F", // Default result
)

func TimestampAdd(timestamp, unit, amount any) Expression

TimestampAdd creates an expression that adds a specified amount of time to a timestamp. - timestamp can be a field path string, FieldPath or Expression. - unit can be a string or an Expression. Valid units include "microsecond", "millisecond", "second", "minute", "hour" and "day". - amount can be an int, int32, int64 or Expression.

func TimestampDiff(end, start, unit any) Expression

TimestampDiff creates an expression that calculates the difference between two timestamps. - end can be a field path string, FieldPath or Expression. - start can be a field path string, FieldPath or Expression. - unit can be a string or an Expression. Valid units include "microsecond", "millisecond", "second", "minute", "hour" and "day".

func TimestampExtract(timestamp, part any) Expression

TimestampExtract creates an expression that extracts a part from a timestamp.

• timestamp can be a field path string, FieldPath or Expression.
• part can be a string or an Expression. Valid parts include "microsecond", "millisecond", "second", "minute", "hour", "day", "dayofweek", "dayofyear", "week", "week(monday)", "week(tuesday)", "week(wednesday)", "week(thursday)", "week(friday)", "week(saturday)", "week(sunday)", "month", "quarter", "year", "isoweek", and "isoyear".

func TimestampExtractWithTimezone(timestamp, part, timezone any) Expression

TimestampExtractWithTimezone creates an expression that extracts a part from a timestamp in a given timezone.

• timestamp can be a field path string, FieldPath or Expression.
• part can be a string or an Expression. Valid parts include "microsecond", "millisecond", "second", "minute", "hour", "day", "dayofweek", "dayofyear", "week", "week(monday)", "week(tuesday)", "week(wednesday)", "week(thursday)", "week(friday)", "week(saturday)", "week(sunday)", "month", "quarter", "year", "isoweek", and "isoyear".
• timezone can be a string or an Expression.

func TimestampSubtract(timestamp, unit, amount any) Expression

TimestampSubtract creates an expression that subtracts a specified amount of time from a timestamp. - timestamp can be a field path string, FieldPath or Expression. - unit can be a string or an Expression. Valid units include "microsecond", "millisecond", "second", "minute", "hour" and "day". - amount can be an int, int32, int64 or Expression.

func TimestampToUnixMicros(timestamp any) Expression

TimestampToUnixMicros creates an expression that converts a timestamp expression to the number of microseconds since the Unix epoch (1970-01-01 00:00:00 UTC). - timestamp can be a field path string, FieldPath or Expression.

func TimestampToUnixMillis(timestamp any) Expression

TimestampToUnixMillis creates an expression that converts a timestamp expression to the number of milliseconds since the Unix epoch (1970-01-01 00:00:00 UTC). - timestamp can be a field path string, FieldPath or Expression.

func TimestampToUnixSeconds(timestamp any) Expression

TimestampToUnixSeconds creates an expression that converts a timestamp expression to the number of seconds since the Unix epoch (1970-01-01 00:00:00 UTC). - timestamp can be a field path string, FieldPath or Expression.

func TimestampTruncate(timestamp, granularity any) Expression

TimestampTruncate creates an expression that truncates a timestamp to a specified granularity.

• timestamp can be a field path string, FieldPath or Expression.
• granularity can be a string or an Expression. Valid values are "microsecond", "millisecond", "second", "minute", "hour", "day", "week", "week(monday)", "week(tuesday)", "week(wednesday)", "week(thursday)", "week(friday)", "week(saturday)", "week(sunday)", "isoweek", "month", "quarter", "year", and "isoyear".

func TimestampTruncateWithTimezone(timestamp, granularity any, timezone any) Expression

TimestampTruncateWithTimezone creates an expression that truncates a timestamp to a specified granularity in a given timezone.

• timestamp can be a field path string, FieldPath or Expression.
• granularity can be a string or an Expression. Valid values are "microsecond", "millisecond", "second", "minute", "hour", "day", "week", "week(monday)", "week(tuesday)", "week(wednesday)", "week(thursday)", "week(friday)", "week(saturday)", "week(sunday)", "isoweek", "month", "quarter", "year", and "isoyear".
• timezone can be a string or an Expression. Valid values are from the TZ database (e.g., "America/Los_Angeles") or in the format "Etc/GMT-1".

func ToLower(exprOrFieldPath any) Expression

ToLower creates an expression that converts a string to lowercase. - exprOrFieldPath can be a field path string, FieldPath or an Expression that evaluates to a string.

func ToUpper(exprOrFieldPath any) Expression

ToUpper creates an expression that converts a string to uppercase. - exprOrFieldPath can be a field path string, FieldPath or an Expression that evaluates to a string.

func Trim(exprOrFieldPath any) Expression

Trim creates an expression that removes leading and trailing whitespace from a string. - exprOrFieldPath can be a field path string, FieldPath or an Expression that evaluates to a string.

func TrimValue(exprOrFieldPath any, charsOrExprToTrim any) Expression

TrimValue creates an expression that removes specified characters from the beginning and end of a string. - exprOrFieldPath can be a field path string, FieldPath or an Expression that evaluates to a string. - charsOrExprToTrim is a string or Expression specifying characters to remove.

func Trunc(numericExprOrFieldPath any) Expression

Trunc creates an expression that truncates a number to an integer. - numericExprOrFieldPath can be a field path string, FieldPath or an Expression that returns a number when evaluated.

func TruncToPrecision(numericExprOrFieldPath any, places any) Expression

TruncToPrecision creates an expression that truncates a number to a specified number of decimal places. - numericExprOrFieldPath can be a field path string, FieldPath or an Expression that returns a number when evaluated. - places can be an int, int32, int64 or Expression.

func Type(exprOrFieldPath any) Expression

Type creates an expression that returns the type of the expression. - exprOrFieldPath can be a field path string, FieldPath or an Expression.

func UnixMicrosToTimestamp(micros any) Expression

UnixMicrosToTimestamp creates an expression that converts a Unix timestamp in microseconds to a Firestore timestamp. - micros can be a field path string, FieldPath or Expression.

func UnixMillisToTimestamp(millis any) Expression

UnixMillisToTimestamp creates an expression that converts a Unix timestamp in milliseconds to a Firestore timestamp. - millis can be a field path string, FieldPath or Expression.

func UnixSecondsToTimestamp(seconds any) Expression

UnixSecondsToTimestamp creates an expression that converts a Unix timestamp in seconds to a Firestore timestamp. - seconds can be a field path string, FieldPath or Expression.

Variable creates an expression that retrieves the value of a variable bound via Define.

Example:

// Define a variable "discountedPrice" and use it in a filter
client.Pipeline().Collection("products").
	Define(AliasedExpressions(Multiply("price", 0.9).As("discountedPrice"))).
	Where(LessThan(Variable("discountedPrice"), 100))

func VectorLength(exprOrFieldPath any) Expression

VectorLength creates an expression that calculates the length of a vector.

• exprOrFieldPath can be a field path string, FieldPath or Expression.

type FieldNotFoundError struct {
	Path string
}

type FindNearestOption interface {
	StageOption
}

func WithFindNearestDistanceField(field string) FindNearestOption

WithFindNearestDistanceField specifies the name of the field to store the calculated distance.

func WithFindNearestLimit(limit int) FindNearestOption

WithFindNearestLimit specifies the maximum number of nearest neighbors to return.

type FindNearestOptions struct {


	DistanceThreshold *float64


	DistanceResultField string
}

type FunctionExpression interface {
	Expression
}

type LimitOption interface {
	StageOption
}

type LiteralsOption interface {
	StageOption
}

type OffsetOption interface {
	StageOption
}

type OrFilter struct {
	Filters []EntityFilter
}

type Ordering struct {
	Expr      Expression
	Direction OrderingDirection
}

func Ascending(expr Expression) Ordering

Ascending creates an Ordering for ascending sort direction.

func Descending(expr Expression) Ordering

Descending creates an Ordering for descending sort direction.

func Orders(o ...Ordering) []Ordering

Orders is a helper function that returns its arguments as a slice of Ordering. It is used to provide variadic-like ergonomics for the Sort pipeline stage.

const (

	OrderingAsc OrderingDirection = OrderingDirection("ascending")

	OrderingDesc OrderingDirection = OrderingDirection("descending")
)

type Pipeline struct {
}

Subcollection creates a new Pipeline that operates on a subcollection of the current document.

This method allows you to start a new pipeline that operates on a subcollection of the current document. It is intended to be used as a subquery.

Note: A pipeline created with `Subcollection` cannot be executed directly using Pipeline.Execute. It must be used within a parent pipeline.

Example:

client.Pipeline().Collection("books").
	AddFields(Selectables(
		Subcollection("reviews").
			Aggregate(Accumulators(Average("rating").As("avg_rating"))).
			ToScalarExpression().As("average_rating"),
	))

func (p *Pipeline) AddFields(fields []Selectable, opts ...AddFieldsOption) *Pipeline

AddFields adds new fields to outputs from previous stages.

This stage allows you to compute values on-the-fly based on existing data from previous stages or constants. You can use this to create new fields or overwrite existing ones (if there is name overlaps).

The added fields are defined using Selectable's. Use Selectables to provide variadic-like ergonomics for the fields argument.

func (p *Pipeline) Aggregate(accumulators []*AliasedAggregate, opts ...AggregateOption) *Pipeline

Aggregate performs aggregation operations on the documents from previous stages. This stage allows you to calculate aggregate values over a set of documents. You define the aggregations to perform using AliasedAggregate expressions which are typically results of calling AggregateFunction.As on AggregateFunction instances. Use Accumulators to provide variadic-like ergonomics for the accumulators argument.

Example:

client.Pipeline().Collection("users").
	Aggregate(Accumulators(Sum("age").As("age_sum")))

func (p *Pipeline) Define(variables []*AliasedExpression, opts ...DefineOption) *Pipeline

Define defines one or more variables in the pipeline's scope. `Define` is used to bind a value to a variable for internal reuse within the pipeline body (accessed via the Variable function).

This stage is useful for declaring reusable values or intermediate calculations that can be referenced multiple times in later parts of the pipeline, improving readability and maintainability.

Each variable is defined using an AliasedExpression, which pairs an expression with a name (alias).

Example:

// Define a variable and use it in a filter
client.Pipeline().Collection("products").
	Define(AliasedExpressions(
		Multiply("price", 0.9).As("discountedPrice"),
		Add("stock", 10).As("newStock"),
	)).
	Where(LessThan(Variable("discountedPrice"), 100)).
	Select(Fields("name", Variable("newStock")))

func (p *Pipeline) Delete(opts ...DeleteOption) *Pipeline

Delete deletes the documents from previous stages.

Example:

client.Pipeline().Collection("logs").
	Where(Equal("status", "archived")).
	Delete()

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.

func (p *Pipeline) Distinct(fields []any, opts ...DistinctOption) *Pipeline

Distinct removes duplicate documents from the outputs of previous stages.

You can optionally specify fields or Selectable expressions to determine distinctness. If no fields are specified, the entire document is used to determine distinctness. Use Fields to provide variadic-like ergonomics for the fields argument.

Execute executes the pipeline and returns a snapshot of the results.

func (p *Pipeline) FindNearest(vectorField any, queryVector any, measure PipelineDistanceMeasure, opts ...FindNearestOption) *Pipeline

FindNearest performs vector distance (similarity) search with given parameters to the stage inputs.

This stage adds a "nearest neighbor search" capability to your pipelines. Given a field that stores vectors and a target vector, this stage will identify and return the inputs whose vector field is closest to the target vector.

The vectorField can be a string, a FieldPath or an Expr. The queryVector can be Vector32, Vector64, []float32, or []float64.

func (p *Pipeline) Limit(limit int, opts ...LimitOption) *Pipeline

Limit limits the maximum number of documents returned by previous stages.

func (p *Pipeline) Offset(offset int, opts ...OffsetOption) *Pipeline

Offset skips the first `offset` number of documents from the results of previous stages.

This stage is useful for implementing pagination in your pipelines, allowing you to retrieve results in chunks. It is typically used in conjunction with *Pipeline.Limit to control the size of each page.

Example: Retrieve the second page of 20 results

  client.Pipeline().Collection("books").
	  .Offset(20)   // Skip the first 20 results
	  .Limit(20)    // Take the next 20 results

RawStage adds a generic stage to the pipeline. This method provides a flexible way to extend the pipeline's functionality by adding custom stages.

Example:

// Assume we don't have a built-in "where" stage
client.Pipeline().Collection("books").
	RawStage("where", []any{LessThan(FieldOf("published"), 1900)}).
	Select(Fields("title", "author"))

func (p *Pipeline) RemoveFields(fields []any, opts ...RemoveFieldsOption) *Pipeline

RemoveFields removes fields from outputs from previous stages. fieldpaths can be a string or a FieldPath or an expression obtained by calling FieldOf. Use Fields to provide variadic-like ergonomics for the fields argument.

func (p *Pipeline) ReplaceWith(fieldpathOrExpr any, opts ...ReplaceWithOption) *Pipeline

ReplaceWith fully overwrites all fields in a document with those coming from a nested map.

This stage allows you to emit a map value as a document. Each key of the map becomes a field on the document that contains the corresponding value.

Example:

// Input: { "name": "John Doe Jr.", "parents": { "father": "John Doe Sr.", "mother": "Jane Doe" } }
// Emit parents as document.
client.Pipeline().Collection("people").ReplaceWith("parents")
// Output: { "father": "John Doe Sr.", "mother": "Jane Doe" }

func (p *Pipeline) Sample(sampler *Sampler, opts ...SampleOption) *Pipeline

Sample performs a pseudo-random sampling of the documents from the previous stage.

This stage will filter documents pseudo-randomly. The behavior is defined by the Sampler. Use WithDocLimit or WithPercentage to create a Sampler.

Example:

// Sample 10 books, if available.
client.Pipeline().Collection("books").Sample(WithDocLimit(10))
// Sample 50% of books.
client.Pipeline().Collection("books").Sample(WithPercentage(0.5))

func (p *Pipeline) Search(opts ...SearchOption) *Pipeline

Search adds a search stage to the Pipeline. This must be the first stage of the pipeline. A limited set of expressions are supported in the search stage. Use WithSearchQuery to specify the search query.

Example:

client.Pipeline().Collection("restaurants").Search(
	WithSearchQuery(DocumentMatches("waffles OR pancakes")),
	WithSearchSort(Descending(Score())),
	WithSearchRetrievalDepth(10),
)

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.

func (p *Pipeline) Select(fields []any, opts ...SelectOption) *Pipeline

Select selects or creates a set of fields from the outputs of previous stages. The selected fields are defined using field path string, FieldPath or Selectable expressions. Selectable expressions can be:

• Field: References an existing field.
• Function: Represents the result of a function with an assigned alias name using [FunctionExpression.As].

Use Fields to provide variadic-like ergonomics for the fields argument.

Example:

	client.Pipeline().Collection("users").Select(Fields("info.email"))
	client.Pipeline().Collection("users").Select(Fields(FieldOf("info.email")))
	client.Pipeline().Collection("users").Select(Fields(FieldOf([]string{"info", "email"})))
	client.Pipeline().Collection("users").Select([]any{"info.email", "name"})
 	client.Pipeline().Collection("users").Select(Fields(Add("age", 5).As("agePlus5")))

func (p *Pipeline) Sort(orders []Ordering, opts ...SortOption) *Pipeline

Sort sorts the documents by the given fields and directions. Use Orders to provide variadic-like ergonomics for the orders argument.

func (p *Pipeline) ToArrayExpression() Expression

ToArrayExpression converts this Pipeline into an expression that evaluates to an array result.

Example:

// Embed a subcollection of reviews as an array into each restaurant document
client.Pipeline().Collection("restaurants").
	AddFields(Selectables(
		Subcollection("reviews").
			Select(Fields("reviewer", "rating")).
			ToArrayExpression().As("reviews"),
	))
// Output format:
// [
//   {
//     "name": "The Burger Joint",
//     "reviews": [
//       { "reviewer": "Alice", "rating": 5 },
//       { "reviewer": "Bob", "rating": 4 }
//     ]
//   }
// ]

func (p *Pipeline) ToScalarExpression() Expression

ToScalarExpression converts this Pipeline into an expression that evaluates to a single scalar result. Used for 1:1 lookups or Aggregations when the subquery is expected to return a single value or object.

Example:

// Calculate average rating for each restaurant using a subquery
client.Pipeline().Collection("restaurants").
	AddFields(Selectables(
		Subcollection("reviews").
			Aggregate(Accumulators(Average("rating").As("avg_score"))).
			ToScalarExpression().As("stats"),
	))
// Output format:
// [
//   {
//     "name": "The Burger Joint",
//     "stats": {
//       "avg_score": 4.8,
//       "review_count": 120
//     }
//   }
// ]

func (p *Pipeline) Union(other *Pipeline, opts ...UnionOption) *Pipeline

Union performs union of all documents from two pipelines, including duplicates.

This stage will pass through documents from previous stage, and also pass through documents from previous stage of the other *Pipeline given in parameter. The order of documents emitted from this stage is undefined.

Example:

// Emit documents from books collection and magazines collection.
client.Pipeline().Collection("books").
	Union(client.Pipeline().Collection("magazines"))

func (p *Pipeline) Unnest(field Selectable, opts ...UnnestOption) *Pipeline

Unnest produces a document for each element in an array field. For each input document, this stage outputs zero or more documents. Each output document is a copy of the input document, but the array field is replaced by an element from the array. The `field` parameter specifies the array field to unnest. It can be a string representing the field path or a Selectable expression. The alias of the selectable will be used as the new field name.

func (p *Pipeline) UnnestWithAlias(fieldpath any, alias string, opts ...UnnestOption) *Pipeline

UnnestWithAlias produces a document for each element in an array field, with a specified alias for the unnested field. It can optionally take UnnestOptions.

func (p *Pipeline) Update(opts ...UpdateOption) *Pipeline

Update performs an update operation using documents from previous stages.

This method updates the documents in the database based on the data flowing through the pipeline. You can optionally specify a list of Selectable field transformations using WithUpdateTransformations. If no transformations are provided, the entire document flowing from the previous stage is used as the update payload.

Example:

// In-place update
client.Pipeline().Literals(updateData).Update()
// Update with transformations
client.Pipeline().Collection("books").
	Where(GreaterThan("price", 50)).
	Update(WithUpdateTransformations(ConstantOf("Discounted").As("status")))

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.

func (p *Pipeline) Where(condition BooleanExpression, opts ...WhereOption) *Pipeline

Where filters the documents from previous stages to only include those matching the specified BooleanExpression.

This stage allows you to apply conditions to the data, similar to a "WHERE" clause in SQL.

func (p *Pipeline) WithReadOptions(opts ...ReadOption) *Pipeline

WithReadOptions specifies constraints for accessing documents from the database, such as ReadTime.

type PipelineDistanceMeasure string

const (

	PipelineDistanceMeasureEuclidean PipelineDistanceMeasure = "euclidean"

	PipelineDistanceMeasureCosine PipelineDistanceMeasure = "cosine"

	PipelineDistanceMeasureDotProduct PipelineDistanceMeasure = "dot_product"
)

type PipelineResult struct {
}

CreateTime returns the time at which the document was created.

Data returns the PipelineResult's fields as a map. It is equivalent to

var m map[string]any
p.DataTo(&m)

DataTo uses the PipelineResult's fields to populate v, which can be a pointer to a map[string]any or a pointer to a struct. This is similar to DocumentSnapshot.DataTo

ExecutionTime returns the time at which the document(s) were read.

Exists reports whether the PipelineResult represents an document. Even if Exists returns false, the rest of the fields are valid.

func (p *PipelineResult) Ref() *DocumentRef

Ref returns the DocumentRef for this result.

UpdateTime returns the time at which the document was last changed.

type PipelineResultIterator struct {
}

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.

In addition, if Next returns an error other than iterator.Done, all subsequent calls will return the same error. To continue iteration, a new PipelineResultIterator must be created.

func (it *PipelineResultIterator) Stop()

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.

type PipelineSnapshot struct {
}

ExecutionTime returns the time at which the pipeline was executed. It is available only after the iterator reaches the end.

func (ps *PipelineSnapshot) ExplainStats() *ExplainStats

ExplainStats returns stats from query explain. If WithExplainMode was set to [ExplainModeExplain] or left unset, then no stats will be available.

func (ps *PipelineSnapshot) Results() *PipelineResultIterator

Results returns an iterator over the query results.

type PipelineSource struct {
}

Collection creates a new Pipeline that operates on the specified Firestore collection.

func (ps *PipelineSource) CollectionGroup(collectionID string, opts ...CollectionGroupOption) *Pipeline

CollectionGroup creates a new Pipeline that operates on all documents in a group of collections that include the given ID, regardless of parent document.

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

CollectionGroup can be used to query across all "Cities" regardless of its parent "Countries".

func (ps *PipelineSource) CreateFromAggregationQuery(query *AggregationQuery) *Pipeline

CreateFromAggregationQuery creates a new Pipeline from the given AggregationQuery. Under the hood, this will translate the query semantics (order by document ID, etc.) to an equivalent pipeline.

func (ps *PipelineSource) CreateFromQuery(query Queryer) *Pipeline

CreateFromQuery creates a new Pipeline from the given Queryer. Under the hood, this will translate the query semantics (order by document ID, etc.) to an equivalent pipeline.

func (ps *PipelineSource) Database(opts ...DatabaseOption) *Pipeline

Database creates a new Pipeline that operates on all documents in the Firestore database.

func (ps *PipelineSource) Documents(refs []*DocumentRef, opts ...DocumentsOption) *Pipeline

Documents creates a new Pipeline that operates on a specific set of Firestore documents.

Literals creates a new Pipeline that operates on a fixed set of predefined document objects.

type PlanSummary struct {


	IndexesUsed []*map[string]any
}

type Precondition interface {
}

Exists is a Precondition that checks for the existence of a resource before writing to it. If the check fails, the write does not occur.

LastUpdateTime returns a Precondition that checks that a resource must exist and must have last been updated at the given time. If the check fails, the write does not occur.

type PropertyFilter struct {
	Path     string
	Operator string
	Value    interface{}
}

type PropertyPathFilter struct {
	Path     FieldPath
	Operator string
	Value    interface{}
}

type Query struct {
}

Deserialize takes a slice of bytes holding the wire-format message of RunQueryRequest, the underlying proto message used by Queries. It then populates and returns a Query object that can be used to execute that Query.

Documents returns an iterator over the query's resulting documents.

package main
import (
	"context"
	"cloud.google.com/go/firestore"
)
func main() {
	ctx := context.Background()
	client, err := firestore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	defer client.Close()
	q := client.Collection("States").Select("pop").
		Where("pop", ">", 10).
		OrderBy("pop", firestore.Desc).
		Limit(10)
	iter1 := q.Documents(ctx)
	_ = iter1 // TODO: Use iter1.
	// You can call Documents directly on a CollectionRef as well.
	iter2 := client.Collection("States").Documents(ctx)
	_ = iter2 // TODO: Use iter2.
}

package main
import (
	"context"
	"cloud.google.com/go/firestore"
)
func main() {
	ctx := context.Background()
	client, err := firestore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	defer client.Close()
	q := client.Collection("Unusual").SelectPaths([]string{"*"}, []string{"[~]"}).
		WherePath([]string{"/"}, ">", 10).
		OrderByPath([]string{"/"}, firestore.Desc).
		Limit(10)
	iter1 := q.Documents(ctx)
	_ = iter1 // TODO: Use iter1.
	// You can call Documents directly on a CollectionRef as well.
	iter2 := client.Collection("States").Documents(ctx)
	_ = iter2 // TODO: Use iter2.
}

func (q Query) EndAt(docSnapshotOrFieldValues ...interface{}) Query

EndAt returns a new Query that specifies that results should end at the document with the given field values. See Query.StartAt for more information.

Calling EndAt overrides a previous call to EndAt or EndBefore.

func (q Query) EndBefore(docSnapshotOrFieldValues ...interface{}) Query

EndBefore returns a new Query that specifies that results should end just before the document with the given field values. See Query.StartAt for more information.

Calling EndBefore overrides a previous call to EndAt or EndBefore.

func (q Query) FindNearest(vectorField string, queryVector any, limit int, measure DistanceMeasure, options *FindNearestOptions) VectorQuery

FindNearest returns a query that can perform vector distance (similarity) search.

The returned query, when executed, performs a distance search on the specified vectorField against the given queryVector and returns the top documents that are closest to the queryVector according to measure. At most limit documents are returned.

Only documents whose vectorField field is a Vector32 or Vector64 of the same dimension as queryVector participate in the query; all other documents are ignored. In particular, fields of type []float32 or []float64 are ignored.

The vectorField argument can be a single field or a dot-separated sequence of fields, and must not contain any of the runes "˜*/[]".

The queryVector argument can be any of the following types:

• []float32
• []float64
• Vector32
• Vector64

type Description struct {
   // ...
   Embedding firestore.Vector32
}

package main
import (
	"context"
	"cloud.google.com/go/firestore"
)
func main() {
	ctx := context.Background()
	client, err := firestore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	defer client.Close()
	//
	q := client.Collection("descriptions").
		FindNearest("Embedding", []float32{1, 2, 3}, 5, firestore.DistanceMeasureDotProduct, &firestore.FindNearestOptions{
			DistanceThreshold:   firestore.Ptr(20.0),
			DistanceResultField: "vector_distance",
		})
	iter1 := q.Documents(ctx)
	_ = iter1 // TODO: Use iter1.
}

func (q Query) FindNearestPath(vectorFieldPath FieldPath, queryVector any, limit int, measure DistanceMeasure, options *FindNearestOptions) VectorQuery

FindNearestPath is like Query.FindNearest but it accepts a FieldPath.

func (q Query) Limit(n int) Query

Limit returns a new Query that specifies the maximum number of first results to return. It must not be negative.

func (q Query) LimitToLast(n int) Query

LimitToLast returns a new Query that specifies the maximum number of last results to return. It must not be negative.

func (q *Query) NewAggregationQuery() *AggregationQuery

NewAggregationQuery returns an AggregationQuery with this query as its base query.

func (q Query) Offset(n int) Query

Offset returns a new Query that specifies the number of initial results to skip. It must not be negative.

OrderBy returns a new Query that specifies the order in which results are returned. A Query can have multiple OrderBy/OrderByPath specifications. OrderBy appends the specification to the list of existing ones.

The path argument can be a single field or a dot-separated sequence of fields, and must not contain any of the runes "˜*/[]".

To order by document name, use the special field path DocumentID.

func (q Query) OrderByPath(fp FieldPath, dir Direction) Query

OrderByPath returns a new Query that specifies the order in which results are returned. A Query can have multiple OrderBy/OrderByPath specifications. OrderByPath appends the specification to the list of existing ones.

func (q Query) Pipeline() *Pipeline

Pipeline creates a new Pipeline from the query. All of the operations of the query will be converted to pipeline stages. For example, `query.Where("f", "==", 1).Limit(10).OrderBy("f", Asc).Pipeline()` is equivalent to `client.Pipeline().Collection("C").Where(Equal("f", 1)).Limit(10).Sort(Ascending("f"))`.

Select returns a new Query that specifies the paths to return from the result documents. Each path argument can be a single field or a dot-separated sequence of fields, and must not contain any of the runes "˜*/[]".

An empty Select call will produce a query that returns only document IDs.

func (q Query) SelectPaths(fieldPaths ...FieldPath) Query

SelectPaths returns a new Query that specifies the field paths to return from the result documents.

An empty SelectPaths call will produce a query that returns only document IDs.

Serialize creates a RunQueryRequest wire-format byte slice from a Query object. This can be used in combination with Deserialize to marshal Query objects. This could be useful, for instance, if executing a query formed in one process in another.

Snapshots returns an iterator over snapshots of the query. Each time the query results change, a new snapshot will be generated.

package main
import (
	"context"
	"fmt"
	"cloud.google.com/go/firestore"
	"google.golang.org/api/iterator"
)
func main() {
	ctx := context.Background()
	client, err := firestore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	defer client.Close()
	q := client.Collection("States").
		Where("pop", ">", 10).
		OrderBy("pop", firestore.Desc).
		Limit(10)
	qsnapIter := q.Snapshots(ctx)
	// Listen forever for changes to the query's results.
	for {
		qsnap, err := qsnapIter.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			// TODO: Handle error.
		}
		fmt.Printf("At %s there were %d results.\n", qsnap.ReadTime, qsnap.Size)
		_ = qsnap.Documents // TODO: Iterate over the results if desired.
		_ = qsnap.Changes   // TODO: Use the list of incremental changes if desired.
	}
}

func (q Query) StartAfter(docSnapshotOrFieldValues ...interface{}) Query

StartAfter returns a new Query that specifies that results should start just after the document with the given field values. See Query.StartAt for more information.

Calling StartAfter overrides a previous call to StartAt or StartAfter.

func (q Query) StartAt(docSnapshotOrFieldValues ...interface{}) Query

StartAt returns a new Query that specifies that results should start at the document with the given field values.

StartAt may be called with a single DocumentSnapshot, representing an existing document within the query. The document must be a direct child of the location being queried (not a parent document, or document in a different collection, or a grandchild document, for example).

Otherwise, StartAt should be called with one field value for each OrderBy clause, in the order that they appear. For example, in

q.OrderBy("X", Asc).OrderBy("Y", Desc).StartAt(1, 2)

results will begin at the first document where X = 1 and Y = 2.

If an OrderBy call uses the special DocumentID field path, the corresponding value should be the document ID relative to the query's collection. For example, to start at the document "NewYork" in the "States" collection, write

client.Collection("States").OrderBy(DocumentID, firestore.Asc).StartAt("NewYork")

Calling StartAt overrides a previous call to StartAt or StartAfter.

func (q Query) Where(path, op string, value interface{}) Query

Where returns a new Query that filters the set of results. A Query can have multiple filters. The path argument can be a single field or a dot-separated sequence of fields, and must not contain any of the runes "˜*/[]". The op argument must be one of "==", "!=", "<", "<=", ">", ">=", "array-contains", "array-contains-any", "in" or "not-in". WARNING: Using WhereEntity with Simple and Composite filters is recommended.

func (q Query) WhereEntity(ef EntityFilter) Query

WhereEntity returns a query with provided filter.

EntityFilter can be a simple filter or a composite filter PropertyFilter and PropertyPathFilter are supported simple filters AndFilter and OrFilter are supported composite filters Entity filters in multiple calls are joined together by AND

func (q Query) WherePath(fp FieldPath, op string, value interface{}) Query

WherePath returns a new Query that filters the set of results. A Query can have multiple filters. The op argument must be one of "==", "!=", "<", "<=", ">", ">=", "array-contains", "array-contains-any", "in" or "not-in". WARNING: Using WhereEntity with Simple and Composite filters is recommended.

func (q *Query) WithReadOptions(opts ...ReadOption) *Query

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

func (q Query) WithRunOptions(opts ...RunOption) Query

WithRunOptions allows passing options to the query Calling WithRunOptions overrides a previous call to WithRunOptions.

type QuerySnapshot struct {


	Documents *DocumentIterator

	Size int

	Changes []DocumentChange

	ReadTime time.Time
}

type QuerySnapshotIterator struct {

	Query Query
}

Next blocks until the query's results change, then returns a QuerySnapshot for the current results.

Next is not expected to return iterator.Done unless it is called after Stop. Rarely, networking issues may also cause iterator.Done to be returned.

In addition, if Next returns an error other than iterator.Done, all subsequent calls will return the same error. To continue iteration, a new QuerySnapshotIterator must be created.

func (it *QuerySnapshotIterator) Stop()

Stop stops receiving snapshots. You should always call Stop when you are done with a QuerySnapshotIterator, to free up resources. It is not safe to call Stop concurrently with Next.

type Queryer interface {
}

type ReadOption interface {
}

ReadTime specifies a time-specific snapshot of the database to read.

type RemoveFieldsOption interface {
	StageOption
}

type ReplaceWithOption interface {
	StageOption
}

type RunOption interface {
}

const (

	SampleModeDocuments SampleMode = "documents"

	SampleModePercent SampleMode = "percent"
)

type SampleOption interface {
	StageOption
}

type Sampler struct {
	Size any
	Mode SampleMode
}

func WithDocLimit(limit int) *Sampler

WithDocLimit creates a Sampler for sampling a fixed number of documents.

func WithPercentage(percentage float64) *Sampler

WithPercentage creates a Sampler for sampling a percentage of documents.

type SearchOption interface {
	StageOption
}

func WithSearchAddFields(fields ...Selectable) SearchOption

WithSearchAddFields specifies the fields to add to each document.

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.

func WithSearchLanguageCode(languageCode string) SearchOption

WithSearchLanguageCode specifies the BCP-47 language code of text in the search query, such as "en" or "sr".

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.

func WithSearchLimit(limit int64) SearchOption

WithSearchLimit specifies the maximum number of documents to return from the search stage. The limit is applied after documents are scored and sorted.

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.

func WithSearchOffset(offset int64) SearchOption

WithSearchOffset specifies the number of documents to skip from the beginning of the search result set.

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.

func WithSearchQuery(query any) SearchOption

WithSearchQuery specifies the search query that will be used to query and score documents by the search stage. It can be a string (automatically wrapped in DocumentMatches) or a BooleanExpression.

Example:

client.Pipeline().Collection("restaurants").Search(
	WithSearchQuery("waffles"),
)

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.

func WithSearchRetrievalDepth(depth int64) SearchOption

WithSearchRetrievalDepth specifies the maximum number of documents to retrieve. Documents will be retrieved in the pre-sort order specified by the search index.

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.

func WithSearchSort(orders ...Ordering) SearchOption

WithSearchSort specifies how the returned documents are sorted. One or more ordering are required.

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.

type SelectOption interface {
	StageOption
}

type Selectable interface {
}

func Selectables(s ...Selectable) []Selectable

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

type SetOption interface {
}

var MergeAll SetOption = merge{}

MergeAll is a SetOption that causes all the field paths given in the data argument to Set to be overwritten. It is not supported for struct data.

func Merge(fps ...FieldPath) SetOption

Merge returns a SetOption that causes only the given field paths to be overwritten. Other fields on the existing document will be untouched. It is an error if a provided field path does not refer to a value in the data passed to Set.

type SimpleFilter interface {
	EntityFilter
}

type SortOption interface {
	StageOption
}

type StageOption interface {
}

type Transaction struct {
}

func (t *Transaction) Create(dr *DocumentRef, data interface{}) error

Create adds a Create operation to the Transaction. See DocumentRef.Create for details.

Delete adds a Delete operation to the Transaction. See DocumentRef.Delete for details.

func (t *Transaction) DocumentRefs(cr *CollectionRef) *DocumentRefIterator

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.

func (t *Transaction) Documents(q Queryer) *DocumentIterator

Documents returns a DocumentIterator based on given Query or CollectionRef. The results will be in the context of the transaction.

func (t *Transaction) Execute(p *Pipeline, opts ...ExecuteOption) *PipelineSnapshot

Execute runs the given pipeline in the context of the transaction.

Get gets the document in the context of the transaction. The transaction holds a pessimistic lock on the returned document. If the document does not exist, Get returns a NotFound error, which can be checked with

status.Code(err) == codes.NotFound

GetAll retrieves multiple documents with a single call. The DocumentSnapshots are returned in the order of the given DocumentRefs. If a document is not present, the corresponding DocumentSnapshot's Exists method will return false. The transaction holds a pessimistic lock on all of the returned documents.

func (t *Transaction) Set(dr *DocumentRef, data interface{}, opts ...SetOption) error

Set adds a Set operation to the Transaction. See DocumentRef.Set for details.

func (t *Transaction) Update(dr *DocumentRef, data []Update, opts ...Precondition) error

Update adds a new Update operation to the Transaction. See DocumentRef.Update for details.

func (t *Transaction) WithReadOptions(opts ...ReadOption) *Transaction

WithReadOptions specifies constraints for accessing documents from the database, e.g. at what time snapshot to read the documents. Note: ReadTime cannot be set via WithReadOptions on a Transaction. If ReadTime is passed, subsequent calls to the transaction will return an error. Use TransactionReadTime option when starting the transaction instead.

type TransactionOption interface {
}

TransactionReadTime is a TransactionOption that configures the transaction to read data at a specific time in the past. Specifying this option forces the transaction to be read-only.

type UnionOption interface {
	StageOption
}

type UnnestOption interface {
	StageOption
}

func WithUnnestIndexField(indexField any) UnnestOption

WithUnnestIndexField specifies the name of the field to store the array index of the unnested element.

type Update struct {
	Path      string
	FieldPath FieldPath
	Value     interface{}
}

String returns string representation of firestore.Update

type UpdateOption interface {
	StageOption
}

func WithUpdateTransformations(field Selectable, additionalFields ...Selectable) UpdateOption

WithUpdateTransformations specifies the list of field transformations to apply in an update operation.

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.

type VectorQuery struct {
}

Deserialize takes a slice of bytes holding the wire-format message of RunQueryRequest, the underlying proto message used by Queries. It then populates and returns a VectorQuery object that can be used to execute that VectorQuery.

Documents returns an iterator over the vector query's resulting documents.

Serialize creates a RunQueryRequest wire-format byte slice from a VectorQuery object. This can be used in combination with Deserialize to marshal VectorQuery objects. This could be useful, for instance, if executing a query formed in one process in another.

type WhereOption interface {
	StageOption
}

type WriteBatch struct {
}

A WriteBatch holds multiple database updates. Build a batch with the Create, Set, Update and Delete methods, then run it with the Commit method. Errors in Create, Set, Update or Delete are recorded instead of being returned immediately. The first such error is returned by Commit.

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`.

package main
import (
	"context"
	"fmt"
	"cloud.google.com/go/firestore"
)
func main() {
	ctx := context.Background()
	client, err := firestore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	defer client.Close()
	type State struct {
		Capital    string  `firestore:"capital"`
		Population float64 `firestore:"pop"` // in millions
	}
	ny := client.Doc("States/NewYork")
	ca := client.Doc("States/California")
	writeResults, err := client.Batch().
		Create(ny, State{Capital: "Albany", Population: 19.8}).
		Set(ca, State{Capital: "Sacramento", Population: 39.14}).
		Delete(client.Doc("States/WestDakota")).
		Commit(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	fmt.Println(writeResults)
}

func (b *WriteBatch) Create(dr *DocumentRef, data interface{}) *WriteBatch

func (b *WriteBatch) Delete(dr *DocumentRef, opts ...Precondition) *WriteBatch

func (b *WriteBatch) Set(dr *DocumentRef, data interface{}, opts ...SetOption) *WriteBatch

func (b *WriteBatch) Update(dr *DocumentRef, data []Update, opts ...Precondition) *WriteBatch

type WriteResult struct {


	UpdateTime time.Time
}