gcpfirestore

func CollectionResourceID ¶

func CollectionResourceID(projectID, collPath string) string

CollectionResourceID constructs a resource ID for a collection from the project ID and the collection path. See the OpenCollection example for use.

func CollectionResourceIDWithDatabase ¶ added in v0.35.0

func CollectionResourceIDWithDatabase(projectID, databaseID, collPath string) string

CollectResoureceIDWithDatabase constructs a resource ID for a collection from the project ID, database ID, and the collection path. See the OpenCollection example for use.

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. If the 'FIRESTORE_EMULATOR_HOST' environment variable is set the client connects to the GCP firestore emulator by overriding the default endpoint.

func OpenCollection ¶

func OpenCollection(client *vkit.Client, collResourceID, nameField string, opts *Options) (*docstore.Collection, error)

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

collResourceID must be of the form "project/<projectID>/databases/(default)/documents/<collPath>". <collPath> may be a top-level collection, like "States", or it may be a path to a nested collection, like "States/Wisconsin/Cities". See https://cloud.google.com/firestore/docs/reference/rest/ for more detail.

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

package main

import (
	"context"
	"log"

	"gocloud.dev/docstore/gcpfirestore"
	"gocloud.dev/gcp"
)

func main() {
	// PRAGMA: This example is used on gocloud.dev; PRAGMA comments adjust how it is shown and can be ignored.
	// PRAGMA: On gocloud.dev, hide lines until the next blank line.
	ctx := context.Background()

	creds, err := gcp.DefaultCredentials(ctx)
	if err != nil {
		log.Fatal(err)
	}
	client, _, err := gcpfirestore.Dial(ctx, creds.TokenSource)
	if err != nil {
		log.Fatal(err)
	}
	resourceID := gcpfirestore.CollectionResourceID("my-project", "my-collection")
	coll, err := gcpfirestore.OpenCollection(client, resourceID, "userID", nil)
	if err != nil {
		log.Fatal(err)
	}
	defer coll.Close()
}

Output:

func OpenCollectionWithNameFunc ¶

func OpenCollectionWithNameFunc(client *vkit.Client, collResourceID string, nameFunc func(docstore.Document) string, opts *Options) (*docstore.Collection, error)

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

collResourceID must be of the form "project/<projectID>/databases/(default)/documents/<collPath>". <collPath> may be 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.

Providing a function to construct the primary key is useful in two situations: if your desired primary key field is not a string, or if there is more than one field you want to use as a primary key.

For the collection to be usable with Query.Delete and Query.Update, nameFunc must work with both map and struct types representing the same underlying data structure. See gocloud.dev/docstore/drivertest.HighScoreKey for an example.

package main

import (
	"context"
	"log"

	"gocloud.dev/docstore"
	"gocloud.dev/docstore/gcpfirestore"
	"gocloud.dev/gcp"
)

func main() {
	// PRAGMA: This example is used on gocloud.dev; PRAGMA comments adjust how it is shown and can be ignored.
	// PRAGMA: On gocloud.dev, hide lines until the next blank line.
	ctx := context.Background()
	type HighScore struct {
		Game   string
		Player string
	}

	creds, err := gcp.DefaultCredentials(ctx)
	if err != nil {
		log.Fatal(err)
	}
	client, _, err := gcpfirestore.Dial(ctx, creds.TokenSource)
	if err != nil {
		log.Fatal(err)
	}

	// The name of a document is constructed from the Game and Player fields.
	nameFromDocument := func(doc docstore.Document) string {
		hs := doc.(*HighScore)
		return hs.Game + "|" + hs.Player
	}

	resourceID := gcpfirestore.CollectionResourceID("my-project", "my-collection")
	coll, err := gcpfirestore.OpenCollectionWithNameFunc(client, resourceID, nameFromDocument, nil)
	if err != nil {
		log.Fatal(err)
	}
	defer coll.Close()
}

Output: