firedocstore

Documentation

Overview

Package firedocstore provides an implementation of the docstore API for Google Cloud Firestore.

Docstore types not supported by the Go firestore client, cloud.google.com/go/firestore: - unsigned integers: encoded is int64s - complex64/128: encoded as an array of two float32/64s. - arrays: encoded as Firestore array values

Firestore types not supported by Docstore: - Document reference (a pointer to another Firestore document) TODO(jba): figure out how to support this

Queries

Firestore allows only one field in a query to be compared with an inequality operator (one other than "="). This driver selects the first field in a Where clause with an inequality to pass to Firestore and handles the rest locally. For example, if the query specifies the three clauses A > 1, B > 2 and A < 3, then A > 1 and A < 3 will be sent to Firestore, and the results will be filtered by B > 2 in this driver.

Firestore requires a composite index if a query contains both an equality and an inequality comparison. This driver returns an error if the necessary index does not exist. You must create the index manually. See https://cloud.google.com/firestore/docs/query-data/indexing for details.

See https://cloud.google.com/firestore/docs/query-data/queries for more information on Firestore queries.

Package firedocstore provides a docstore implementation backed by GCP Firestore. Use OpenCollection to construct a *docstore.Collection.

URLs

For docstore.OpenCollection, firedocstore registers for the scheme "firestore". The default URL opener will create a connection using default credentials from the environment, as described in https://cloud.google.com/docs/authentication/production. To customize the URL opener, or for more details on the URL format, see URLOpener. See https://github.com/eliben/gocdkx/concepts/urls/ for background information.

As

firedocstore exposes the following types for As: - Collection.As: *firestore.Client - ActionList.BeforeDo: *pb.BatchGetDocumentRequest or *pb.CommitRequest. - Query.BeforeQuery: *firestore.RunQueryRequest - DocumentIterator: firestore.Firestore_RunQueryClient

Index

• Constants
• func Dial(ctx context.Context, ts gcp.TokenSource) (*vkit.Client, func(), error)
• func OpenCollection(client *vkit.Client, projectID, collPath, nameField string, _ *Options) (*docstore.Collection, error)
• func OpenCollectionWithNameFunc(client *vkit.Client, projectID, collPath string, ...) (*docstore.Collection, error)
• type Options
• type URLOpener
  • func (o *URLOpener) OpenCollectionURL(ctx context.Context, u *url.URL) (*docstore.Collection, error)

Constants

const Scheme = "firestore"

Scheme is the URL scheme firestore registers its URLOpener under on docstore.DefaultMux.

Functions

func Dial

func Dial(ctx context.Context, ts gcp.TokenSource) (*vkit.Client, func(), error)

Dial returns a client to use with Firestore and a clean-up function to close the client after used.

func OpenCollection

func OpenCollection(client *vkit.Client, projectID, collPath, nameField string, _ *Options) (*docstore.Collection, error)

OpenCollection creates a *docstore.Collection representing a Firestore collection.

collPath is the path to the collection, starting from a root collection. It may refer to a top-level collection, like "States", or it may be a path to a nested collection, like "States/Wisconsin/Cities".

firedocstore requires that a single string field, nameField, be designated the primary key. Its values must be unique over all documents in the collection, and the primary key must be provided to retrieve a document.

func OpenCollectionWithNameFunc

func OpenCollectionWithNameFunc(client *vkit.Client, projectID, collPath string, nameFunc func(docstore.Document) string, _ *Options) (*docstore.Collection, error)

OpenCollectionWithNameFunc creates a *docstore.Collection representing a Firestore collection.

collPath is the path to the collection, starting from a root collection. It may refer to a top-level collection, like "States", or it may be a path to a nested collection, like "States/Wisconsin/Cities".

The nameFunc argument is function that accepts a document and returns the value to be used for the document's primary key. It should return the empty string if the document is missing the information to construct a name. This will cause all actions, even Create, to fail.

Types

type Options

type Options struct{}

Options contains optional arguments to the OpenCollection functions.

type URLOpener

type URLOpener struct {
	// Client must be set to a non-nil client authenticated with Cloud Firestore
	// scope or equivalent.
	Client *vkit.Client
}

URLOpener opens firestore URLs like "firestore://myproject/mycollection?name_field=myID".

• The URL's host holds the GCP projectID.
• The only element of the URL's path holds the path to a Firestore collection.

See https://firebase.google.com/docs/firestore/data-model for more details.

The following query parameters are supported:

• name_field (required): firedocstore requires that a single string field,

name_field, be designated the primary key. Its values must be unique over all documents in the collection, and the primary key must be provided to retrieve a document.

func (*URLOpener) OpenCollectionURL

func (o *URLOpener) OpenCollectionURL(ctx context.Context, u *url.URL) (*docstore.Collection, error)

OpenCollectionURL opens a docstore.Collection based on u.