datastore

package
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 10, 2017 License: Apache-2.0 Imports: 27 Imported by: 0

Documentation

Overview

Package datastore provides a client for Google Cloud Datastore.

Note: This package is in beta. Some backwards-incompatible changes may occur.

Basic Operations

Entities are the unit of storage and are associated with a key. A key consists of an optional parent key, a string application ID, a string kind (also known as an entity type), and either a StringID or an IntID. A StringID is also known as an entity name or key name.

It is valid to create a key with a zero StringID and a zero IntID; this is called an incomplete key, and does not refer to any saved entity. Putting an entity into the datastore under an incomplete key will cause a unique key to be generated for that entity, with a non-zero IntID.

An entity's contents are a mapping from case-sensitive field names to values. Valid value types are:

  • signed integers (int, int8, int16, int32 and int64),
  • bool,
  • string,
  • float32 and float64,
  • []byte (up to 1 megabyte in length),
  • any type whose underlying type is one of the above predeclared types,
  • *Key,
  • GeoPoint,
  • time.Time (stored with microsecond precision),
  • structs whose fields are all valid value types,
  • pointers to structs whose fields are all valid value types,
  • slices of any of the above.

Slices of structs are valid, as are structs that contain slices.

The Get and Put functions load and save an entity's contents. An entity's contents are typically represented by a struct pointer.

Example code: 

type Entity struct {
	Value string
}

func main() {
	ctx := context.Background()

	// Create a datastore client. In a typical application, you would create
	// a single client which is reused for every datastore operation.
	dsClient, err := datastore.NewClient(ctx, "my-project")
	if err != nil {
		// Handle error.
	}

	k := datastore.NameKey("Entity", "stringID", nil)
	e := new(Entity)
	if err := dsClient.Get(ctx, k, e); err != nil {
		// Handle error.
	}

	old := e.Value
	e.Value = "Hello World!"

	if _, err := dsClient.Put(ctx, k, e); err != nil {
		// Handle error.
	}

	fmt.Printf("Updated value from %q to %q\n", old, e.Value)
}

GetMulti, PutMulti and DeleteMulti are batch versions of the Get, Put and Delete functions. They take a []*Key instead of a *Key, and may return a datastore.MultiError when encountering partial failure.

Properties

An entity's contents can be represented by a variety of types. These are typically struct pointers, but can also be any type that implements the PropertyLoadSaver interface. If using a struct pointer, you do not have to explicitly implement the PropertyLoadSaver interface; the datastore will automatically convert via reflection. If a struct pointer does implement that interface then those methods will be used in preference to the default behavior for struct pointers. Struct pointers are more strongly typed and are easier to use; PropertyLoadSavers are more flexible.

The actual types passed do not have to match between Get and Put calls or even across different calls to datastore. It is valid to put a *PropertyList and get that same entity as a *myStruct, or put a *myStruct0 and get a *myStruct1. Conceptually, any entity is saved as a sequence of properties, and is loaded into the destination value on a property-by-property basis. When loading into a struct pointer, an entity that cannot be completely represented (such as a missing field) will result in an ErrFieldMismatch error but it is up to the caller whether this error is fatal, recoverable or ignorable.

By default, for struct pointers, all properties are potentially indexed, and the property name is the same as the field name (and hence must start with an upper case letter).

Fields may have a `datastore:"name,options"` tag. The tag name is the property name, which must be one or more valid Go identifiers joined by ".", but may start with a lower case letter. An empty tag name means to just use the field name. A "-" tag name means that the datastore will ignore that field.

The only valid options are "omitempty", "noindex" and "flatten".

If the options include "omitempty" and the value of the field is empty, then the field will be omitted on Save. The empty values are false, 0, any nil interface value, and any array, slice, map, or string of length zero. Struct field values will never be empty.

If options include "noindex" then the field will not be indexed. All fields are indexed by default. Strings or byte slices longer than 1500 bytes cannot be indexed; fields used to store long strings and byte slices must be tagged with "noindex" or they will cause Put operations to fail.

For a nested struct field, the options may also include "flatten". This indicates that the immediate fields and any nested substruct fields of the nested struct should be flattened. See below for examples.

To use multiple options together, separate them by a comma. The order does not matter.

If the options is "" then the comma may be omitted.

Example code: 

// A and B are renamed to a and b.
// A, C and J are not indexed.
// D's tag is equivalent to having no tag at all (E).
// I is ignored entirely by the datastore.
// J has tag information for both the datastore and json packages.
type TaggedStruct struct {
	A int `datastore:"a,noindex"`
	B int `datastore:"b"`
	C int `datastore:",noindex"`
	D int `datastore:""`
	E int
	I int `datastore:"-"`
	J int `datastore:",noindex" json:"j"`
}

Key Field

If the struct contains a *datastore.Key field tagged with the name "__key__", its value will be ignored on Put. When reading the Entity back into the Go struct, the field will be populated with the *datastore.Key value used to query for the Entity.

Example code: 

type MyEntity struct {
	A int
	K *datastore.Key `datastore:"__key__"`
}

k := datastore.NameKey("Entity", "stringID", nil)
e := MyEntity{A: 12}
k, err = dsClient.Put(ctx, k, e)
if err != nil {
	// Handle error.
}

var entities []MyEntity
q := datastore.NewQuery("Entity").Filter("A =", 12).Limit(1)
_, err := dsClient.GetAll(ctx, q, &entities)
if err != nil {
	// Handle error
}

log.Println(entities[0])
// Prints {12 /Entity,stringID}

Structured Properties

If the struct pointed to contains other structs, then the nested or embedded structs are themselves saved as Entity values. For example, given these definitions: 

type Inner struct {
	W int32
	X string
}

type Outer struct {
	I Inner
}

then an Outer would have one property, Inner, encoded as an Entity value.

If an outer struct is tagged "noindex" then all of its implicit flattened fields are effectively "noindex".

If the Inner struct contains a *Key field with the name "__key__", like so: 

type Inner struct {
	W int32
	X string
	K *datastore.Key `datastore:"__key__"`
}

type Outer struct {
	I Inner
}

then the value of K will be used as the Key for Inner, represented as an Entity value in datastore.

If any nested struct fields should be flattened, instead of encoded as Entity values, the nested struct field should be tagged with the "flatten" option. For example, given the following: 

type Inner1 struct {
	W int32
	X string
}

type Inner2 struct {
	Y float64
}

type Inner3 struct {
	Z bool
}

type Inner4 struct {
	WW int
}

type Inner5 struct {
	X Inner4
}

type Outer struct {
	A int16
	I []Inner1 `datastore:",flatten"`
	J Inner2   `datastore:",flatten"`
	K Inner5   `datastore:",flatten"`
	Inner3     `datastore:",flatten"`
}

an Outer's properties would be equivalent to those of: 

type OuterEquivalent struct {
	A          int16
	IDotW      []int32  `datastore:"I.W"`
	IDotX      []string `datastore:"I.X"`
	JDotY      float64  `datastore:"J.Y"`
	KDotXDotWW int      `datastore:"K.X.WW"`
	Z          bool
}

Note that the "flatten" option cannot be used for Entity value fields. The server will reject any dotted field names for an Entity value.

The PropertyLoadSaver Interface

An entity's contents can also be represented by any type that implements the PropertyLoadSaver interface. This type may be a struct pointer, but it does not have to be. The datastore package will call Load when getting the entity's contents, and Save when putting the entity's contents. Possible uses include deriving non-stored fields, verifying fields, or indexing a field only if its value is positive.

Example code: 

type CustomPropsExample struct {
	I, J int
	// Sum is not stored, but should always be equal to I + J.
	Sum int `datastore:"-"`
}

func (x *CustomPropsExample) Load(ps []datastore.Property) error {
	// Load I and J as usual.
	if err := datastore.LoadStruct(x, ps); err != nil {
		return err
	}
	// Derive the Sum field.
	x.Sum = x.I + x.J
	return nil
}

func (x *CustomPropsExample) Save() ([]datastore.Property, error) {
	// Validate the Sum field.
	if x.Sum != x.I + x.J {
		return nil, errors.New("CustomPropsExample has inconsistent sum")
	}
	// Save I and J as usual. The code below is equivalent to calling
	// "return datastore.SaveStruct(x)", but is done manually for
	// demonstration purposes.
	return []datastore.Property{
		{
			Name:  "I",
			Value: int64(x.I),
		},
		{
			Name:  "J",
			Value: int64(x.J),
		},
	}, nil
}

The *PropertyList type implements PropertyLoadSaver, and can therefore hold an arbitrary entity's contents.

Queries

Queries retrieve entities based on their properties or key's ancestry. Running a query yields an iterator of results: either keys or (key, entity) pairs. Queries are re-usable and it is safe to call Query.Run from concurrent goroutines. Iterators are not safe for concurrent use.

Queries are immutable, and are either created by calling NewQuery, or derived from an existing query by calling a method like Filter or Order that returns a new query value. A query is typically constructed by calling NewQuery followed by a chain of zero or more such methods. These methods are:

  • Ancestor and Filter constrain the entities returned by running a query.
  • Order affects the order in which they are returned.
  • Project constrains the fields returned.
  • Distinct de-duplicates projected entities.
  • KeysOnly makes the iterator return only keys, not (key, entity) pairs.
  • Start, End, Offset and Limit define which sub-sequence of matching entities to return. Start and End take cursors, Offset and Limit take integers. Start and Offset affect the first result, End and Limit affect the last result. If both Start and Offset are set, then the offset is relative to Start. If both End and Limit are set, then the earliest constraint wins. Limit is relative to Start+Offset, not relative to End. As a special case, a negative limit means unlimited.

Example code: 

type Widget struct {
	Description string
	Price       int
}

func printWidgets(ctx context.Context, client *datastore.Client) {
	q := datastore.NewQuery("Widget").
		Filter("Price <", 1000).
		Order("-Price")
	for t := client.Run(ctx, q); ; {
		var x Widget
		key, err := t.Next(&x)
		if err == iterator.Done {
			break
		}
		if err != nil {
			// Handle error.
		}
		fmt.Printf("Key=%v\nWidget=%#v\n\n", key, x)
	}
}

Transactions

Client.RunInTransaction runs a function in a transaction.

Example code: 

type Counter struct {
	Count int
}

func incCount(ctx context.Context, client *datastore.Client) {
	var count int
	key := datastore.NameKey("Counter", "singleton", nil)
	_, err := client.RunInTransaction(ctx, func(tx *datastore.Transaction) error {
		var x Counter
		if err := tx.Get(key, &x); err != nil && err != datastore.ErrNoSuchEntity {
			return err
		}
		x.Count++
		if _, err := tx.Put(key, &x); err != nil {
			return err
		}
		count = x.Count
		return nil
	})
	if err != nil {
		// Handle error.
	}
	// The value of count is only valid once the transaction is successful
	// (RunInTransaction has returned nil).
	fmt.Printf("Count=%d\n", count)
}

Google Cloud Datastore Emulator

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

To install and set up the emulator and its environment variables, see the documentation at https://cloud.google.com/datastore/docs/tools/datastore-emulator.

Authentication

See examples of authorization and authentication at https://godoc.org/cloud.google.com/go#pkg-examples.

Index

Examples

Constants

View Source 
const ScopeDatastore = "https://www.googleapis.com/auth/datastore"

ScopeDatastore grants permissions to view and/or manage datastore entities

Variables

View Source 
var (
	// ErrInvalidEntityType is returned when functions like Get or Next are
	// passed a dst or src argument of invalid type.
	ErrInvalidEntityType = errors.New("datastore: invalid entity type")
	// ErrInvalidKey is returned when an invalid key is presented.
	ErrInvalidKey = errors.New("datastore: invalid key")
	// ErrNoSuchEntity is returned when no entity was found for a given key.
	ErrNoSuchEntity = errors.New("datastore: no such entity")
)
View Source 
var ErrConcurrentTransaction = errors.New("datastore: concurrent transaction")

ErrConcurrentTransaction is returned when a transaction is rolled back due to a conflict with a concurrent transaction.

Functions

func LoadStruct 

func LoadStruct(dst interface{}, p []Property) error

LoadStruct loads the properties from p to dst. dst must be a struct pointer.

The values of dst's unmatched struct fields are not modified, and matching slice-typed fields are not reset before appending to them. In particular, it is recommended to pass a pointer to a zero valued struct on each LoadStruct call.

Example 
package main

import (
	"fmt"

	"cloud.google.com/go/datastore"
)

func main() {
	type Player struct {
		User  string
		Score int
	}
	// Normally LoadStruct would only be used inside a custom implementation of
	// PropertyLoadSaver; this is for illustrative purposes only.
	props := []datastore.Property{
		{Name: "User", Value: "Alice"},
		{Name: "Score", Value: int64(97)},
	}

	var p Player
	if err := datastore.LoadStruct(&p, props); err != nil {
		// TODO: Handle error.
	}
	fmt.Println(p)
}

Output:

{Alice 97}

Types

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is a client for reading and writing data in a datastore dataset.

func NewClient 

func NewClient(ctx context.Context, projectID string, opts ...option.ClientOption) (*Client, error)

NewClient creates a new Client for a given dataset. If the project ID is empty, it is derived from the DATASTORE_PROJECT_ID environment variable. If the DATASTORE_EMULATOR_HOST environment variable is set, client will use its value to connect to a locally-running datastore emulator.

Example 
package main

import (
	"cloud.google.com/go/datastore"
	"golang.org/x/net/context"
)

func main() {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	_ = client // TODO: Use client.
}

Output:

func (*Client) AllocateIDs 

func (c *Client) AllocateIDs(ctx context.Context, keys []*Key) ([]*Key, error)

AllocateIDs accepts a slice of incomplete keys and returns a slice of complete keys that are guaranteed to be valid in the datastore.

Example 
package main

import (
	"cloud.google.com/go/datastore"
	"golang.org/x/net/context"
)

func main() {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	var keys []*datastore.Key
	for i := 0; i < 10; i++ {
		keys = append(keys, datastore.IncompleteKey("Article", nil))
	}
	keys, err = client.AllocateIDs(ctx, keys)
	if err != nil {
		// TODO: Handle error.
	}
	_ = keys // TODO: Use keys.
}

Output:

func (*Client) Close 

func (c *Client) Close() error

Close closes the Client.

func (*Client) Count 

func (c *Client) Count(ctx context.Context, q *Query) (int, error)

Count returns the number of results for the given query.

The running time and number of API calls made by Count scale linearly with with the sum of the query's offset and limit. Unless the result count is expected to be small, it is best to specify a limit; otherwise Count will continue until it finishes counting or the provided context expires.

Example 
package main

import (
	"fmt"

	"cloud.google.com/go/datastore"
	"golang.org/x/net/context"
)

func main() {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	// Count the number of the post entities.
	q := datastore.NewQuery("Post")
	n, err := client.Count(ctx, q)
	if err != nil {
		// TODO: Handle error.
	}
	fmt.Printf("There are %d posts.", n)
}

Output:

func (*Client) Delete 

func (c *Client) Delete(ctx context.Context, key *Key) error

Delete deletes the entity for the given key.

Example 
package main

import (
	"cloud.google.com/go/datastore"
	"golang.org/x/net/context"
)

func main() {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}

	key := datastore.NameKey("Article", "articled1", nil)
	if err := client.Delete(ctx, key); err != nil {
		// TODO: Handle error.
	}
}

Output:

func (*Client) DeleteMulti 

func (c *Client) DeleteMulti(ctx context.Context, keys []*Key) error

DeleteMulti is a batch version of Delete.

Example 
package main

import (
	"cloud.google.com/go/datastore"
	"golang.org/x/net/context"
)

func main() {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	var keys []*datastore.Key
	for i := 1; i <= 10; i++ {
		keys = append(keys, datastore.IDKey("Article", int64(i), nil))
	}
	if err := client.DeleteMulti(ctx, keys); err != nil {
		// TODO: Handle error.
	}
}

Output:

func (*Client) Get 

func (c *Client) Get(ctx context.Context, key *Key, dst interface{}) error

Get loads the entity stored for key into dst, which must be a struct pointer or implement PropertyLoadSaver. If there is no such entity for the key, Get returns ErrNoSuchEntity.

The values of dst's unmatched struct fields are not modified, and matching slice-typed fields are not reset before appending to them. In particular, it is recommended to pass a pointer to a zero valued struct on each Get call.

ErrFieldMismatch is returned when a field is to be loaded into a different type than the one it was stored from, or when a field is missing or unexported in the destination struct. ErrFieldMismatch is only returned if dst is a struct pointer.

Example 
package main

import (
	"time"

	"cloud.google.com/go/datastore"
	"golang.org/x/net/context"
)

func main() {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}

	type Article struct {
		Title       string
		Description string
		Body        string `datastore:",noindex"`
		Author      *datastore.Key
		PublishedAt time.Time
	}
	key := datastore.NameKey("Article", "articled1", nil)
	article := &Article{}
	if err := client.Get(ctx, key, article); err != nil {
		// TODO: Handle error.
	}
}

Output:

func (*Client) GetAll 

func (c *Client) GetAll(ctx context.Context, q *Query, dst interface{}) ([]*Key, error)

GetAll runs the provided query in the given context and returns all keys that match that query, as well as appending the values to dst.

dst must have type *[]S or *[]*S or *[]P, for some struct type S or some non- interface, non-pointer type P such that P or *P implements PropertyLoadSaver.

As a special case, *PropertyList is an invalid type for dst, even though a PropertyList is a slice of structs. It is treated as invalid to avoid being mistakenly passed when *[]PropertyList was intended.

The keys returned by GetAll will be in a 1-1 correspondence with the entities added to dst.

If q is a “keys-only” query, GetAll ignores dst and only returns the keys.

The running time and number of API calls made by GetAll scale linearly with with the sum of the query's offset and limit. Unless the result count is expected to be small, it is best to specify a limit; otherwise GetAll will continue until it finishes collecting results or the provided context expires.

Example 
package main

import (
	"fmt"
	"time"

	"cloud.google.com/go/datastore"
	"golang.org/x/net/context"
)

type Post struct {
	Title       string
	PublishedAt time.Time
	Comments    int
}

func main() {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	var posts []*Post
	keys, err := client.GetAll(ctx, datastore.NewQuery("Post"), &posts)
	for i, key := range keys {
		fmt.Println(key)
		fmt.Println(posts[i])
	}
}

Output:

func (*Client) GetMulti 

func (c *Client) GetMulti(ctx context.Context, keys []*Key, dst interface{}) error

GetMulti is a batch version of Get.

dst must be a []S, []*S, []I or []P, for some struct type S, some interface type I, or some non-interface non-pointer type P such that P or *P implements PropertyLoadSaver. If an []I, each element must be a valid dst for Get: it must be a struct pointer or implement PropertyLoadSaver.

As a special case, PropertyList is an invalid type for dst, even though a PropertyList is a slice of structs. It is treated as invalid to avoid being mistakenly passed when []PropertyList was intended.

Example 
package main

import (
	"time"

	"cloud.google.com/go/datastore"
	"golang.org/x/net/context"
)

type Post struct {
	Title       string
	PublishedAt time.Time
	Comments    int
}

func main() {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}

	keys := []*datastore.Key{
		datastore.NameKey("Post", "post1", nil),
		datastore.NameKey("Post", "post2", nil),
		datastore.NameKey("Post", "post3", nil),
	}
	posts := make([]Post, 3)
	if err := client.GetMulti(ctx, keys, posts); err != nil {
		// TODO: Handle error.
	}
}

Output:

func (*Client) NewTransaction 

func (c *Client) NewTransaction(ctx context.Context, opts ...TransactionOption) (*Transaction, error)

NewTransaction starts a new transaction.

Example 
package main

import (
	"cloud.google.com/go/datastore"
	"golang.org/x/net/context"
)

func main() {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	const retries = 3

	// Increment a counter.
	// See https://cloud.google.com/appengine/articles/sharding_counters for
	// a more scalable solution.
	type Counter struct {
		Count int
	}

	key := datastore.NameKey("counter", "CounterA", nil)
	var tx *datastore.Transaction
	for i := 0; i < retries; i++ {
		tx, err = client.NewTransaction(ctx)
		if err != nil {
			break
		}

		var c Counter
		if err = tx.Get(key, &c); err != nil && err != datastore.ErrNoSuchEntity {
			break
		}
		c.Count++
		if _, err = tx.Put(key, &c); err != nil {
			break
		}

		// Attempt to commit the transaction. If there's a conflict, try again.
		if _, err = tx.Commit(); err != datastore.ErrConcurrentTransaction {
			break
		}
	}
	if err != nil {
		// TODO: Handle error.
	}
}

Output:

func (*Client) Put 

func (c *Client) Put(ctx context.Context, key *Key, src interface{}) (*Key, error)

Put saves the entity src into the datastore with key k. src must be a struct pointer or implement PropertyLoadSaver; if a struct pointer then any unexported fields of that struct will be skipped. If k is an incomplete key, the returned key will be a unique key generated by the datastore.

Example 
package main

import (
	"time"

	"cloud.google.com/go/datastore"
	"golang.org/x/net/context"
)

func main() {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}

	type Article struct {
		Title       string
		Description string
		Body        string `datastore:",noindex"`
		Author      *datastore.Key
		PublishedAt time.Time
	}
	newKey := datastore.IncompleteKey("Article", nil)
	_, err = client.Put(ctx, newKey, &Article{
		Title:       "The title of the article",
		Description: "The description of the article...",
		Body:        "...",
		Author:      datastore.NameKey("Author", "jbd", nil),
		PublishedAt: time.Now(),
	})
	if err != nil {
		// TODO: Handle error.
	}
}

Output:
Example (Flatten) 
package main

import (
	"log"

	"cloud.google.com/go/datastore"
	"golang.org/x/net/context"
)

func main() {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, "project-id")
	if err != nil {
		log.Fatal(err)
	}

	type Animal struct {
		Name  string
		Type  string
		Breed string
	}

	type Human struct {
		Name   string
		Height int
		Pet    Animal `datastore:",flatten"`
	}

	newKey := datastore.IncompleteKey("Human", nil)
	_, err = client.Put(ctx, newKey, &Human{
		Name:   "Susan",
		Height: 67,
		Pet: Animal{
			Name:  "Fluffy",
			Type:  "Cat",
			Breed: "Sphynx",
		},
	})
	if err != nil {
		log.Fatal(err)
	}
}

Output:

func (*Client) PutMulti 

func (c *Client) PutMulti(ctx context.Context, keys []*Key, src interface{}) ([]*Key, error)

PutMulti is a batch version of Put.

src must satisfy the same conditions as the dst argument to GetMulti.

Example (InterfaceSlice) 
package main

import (
	"time"

	"cloud.google.com/go/datastore"
	"golang.org/x/net/context"
)

type Post struct {
	Title       string
	PublishedAt time.Time
	Comments    int
}

func main() {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}

	keys := []*datastore.Key{
		datastore.NameKey("Post", "post1", nil),
		datastore.NameKey("Post", "post2", nil),
	}

	// PutMulti with an empty interface slice.
	posts := []interface{}{
		&Post{Title: "Post 1", PublishedAt: time.Now()},
		&Post{Title: "Post 2", PublishedAt: time.Now()},
	}
	if _, err := client.PutMulti(ctx, keys, posts); err != nil {
		// TODO: Handle error.
	}
}

Output:
Example (Slice) 
package main

import (
	"time"

	"cloud.google.com/go/datastore"
	"golang.org/x/net/context"
)

type Post struct {
	Title       string
	PublishedAt time.Time
	Comments    int
}

func main() {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}

	keys := []*datastore.Key{
		datastore.NameKey("Post", "post1", nil),
		datastore.NameKey("Post", "post2", nil),
	}

	// PutMulti with a Post slice.
	posts := []*Post{
		{Title: "Post 1", PublishedAt: time.Now()},
		{Title: "Post 2", PublishedAt: time.Now()},
	}
	if _, err := client.PutMulti(ctx, keys, posts); err != nil {
		// TODO: Handle error.
	}
}

Output:

func (*Client) Run 

func (c *Client) Run(ctx context.Context, q *Query) *Iterator

Run runs the given query in the given context.

Example 
package main

import (
	"time"

	"cloud.google.com/go/datastore"
	"golang.org/x/net/context"
)

func main() {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	// List the posts published since yesterday.
	yesterday := time.Now().Add(-24 * time.Hour)
	q := datastore.NewQuery("Post").Filter("PublishedAt >", yesterday)
	it := client.Run(ctx, q)
	_ = it // TODO: iterate using Next.
}

Output:

func (*Client) RunInTransaction 

func (c *Client) RunInTransaction(ctx context.Context, f func(tx *Transaction) error, opts ...TransactionOption) (*Commit, error)

RunInTransaction runs f in a transaction. f is invoked with a Transaction that f should use for all the transaction's datastore operations.

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

If f returns nil, RunInTransaction commits the transaction, returning the Commit and a nil error if it succeeds. If the commit fails due to a conflicting transaction, RunInTransaction retries f with a new Transaction. It gives up and returns ErrConcurrentTransaction after three failed attempts (or as configured with MaxAttempts).

If f returns non-nil, then the transaction will be rolled back and RunInTransaction 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 RunInTransaction returns nil.

Since f may be called multiple times, f should usually be idempotent – that is, it should have the same result when called multiple times. Note that Transaction.Get will append when unmarshalling slice fields, so it is not necessarily idempotent.

Example 
package main

import (
	"fmt"

	"cloud.google.com/go/datastore"
	"golang.org/x/net/context"
)

func main() {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}

	// Increment a counter.
	// See https://cloud.google.com/appengine/articles/sharding_counters for
	// a more scalable solution.
	type Counter struct {
		Count int
	}

	var count int
	key := datastore.NameKey("Counter", "singleton", nil)
	_, err = client.RunInTransaction(ctx, func(tx *datastore.Transaction) error {
		var x Counter
		if err := tx.Get(key, &x); err != nil && err != datastore.ErrNoSuchEntity {
			return err
		}
		x.Count++
		if _, err := tx.Put(key, &x); err != nil {
			return err
		}
		count = x.Count
		return nil
	})
	if err != nil {
		// TODO: Handle error.
	}
	// The value of count is only valid once the transaction is successful
	// (RunInTransaction has returned nil).
	fmt.Printf("Count=%d\n", count)
}

Output:

type Commit 

type Commit struct{}

Commit represents the result of a committed transaction.

func (*Commit) Key 

func (c *Commit) Key(p *PendingKey) *Key

Key resolves a pending key handle into a final key.

Example 
package main

import (
	"fmt"
	"time"

	"cloud.google.com/go/datastore"
	"golang.org/x/net/context"
)

type Post struct {
	Title       string
	PublishedAt time.Time
	Comments    int
}

func main() {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, "")
	if err != nil {
		// TODO: Handle error.
	}
	var pk1, pk2 *datastore.PendingKey
	// Create two posts in a single transaction.
	commit, err := client.RunInTransaction(ctx, func(tx *datastore.Transaction) error {
		var err error
		pk1, err = tx.Put(datastore.IncompleteKey("Post", nil), &Post{Title: "Post 1", PublishedAt: time.Now()})
		if err != nil {
			return err
		}
		pk2, err = tx.Put(datastore.IncompleteKey("Post", nil), &Post{Title: "Post 2", PublishedAt: time.Now()})
		if err != nil {
			return err
		}
		return nil
	})
	if err != nil {
		// TODO: Handle error.
	}
	// Now pk1, pk2 are valid PendingKeys. Let's convert them into real keys
	// using the Commit object.
	k1 := commit.Key(pk1)
	k2 := commit.Key(pk2)
	fmt.Println(k1, k2)
}

Output:

type Cursor 

type Cursor struct {
	// contains filtered or unexported fields
}

Cursor is an iterator's position. It can be converted to and from an opaque string. A cursor can be used from different HTTP requests, but only with a query with the same kind, ancestor, filter and order constraints.

The zero Cursor can be used to indicate that there is no start and/or end constraint for a query.

func DecodeCursor 

func DecodeCursor(s string) (Cursor, error)

Decode decodes a cursor from its base-64 string representation.

Example 
package main

import (
	"cloud.google.com/go/datastore"
)

func main() {
	// See Query.Start for a fuller example of DecodeCursor.
	// getCursor represents a function that returns a cursor from a previous
	// iteration in string form.
	cursorString := getCursor()
	cursor, err := datastore.DecodeCursor(cursorString)
	if err != nil {
		// TODO: Handle error.
	}
	_ = cursor // TODO: Use the cursor with Query.Start or Query.End.
}

func getCursor() string { return "" }

Output:

func (Cursor) String 

func (c Cursor) String() string

String returns a base-64 string representation of a cursor.

type Entity added in v0.2.0 

type Entity struct {
	Key        *Key
	Properties []Property
}

An Entity is the value type for a nested struct. This type is only used for a Property's Value.

type ErrFieldMismatch 

type ErrFieldMismatch struct {
	StructType reflect.Type
	FieldName  string
	Reason     string
}

ErrFieldMismatch is returned when a field is to be loaded into a different type than the one it was stored from, or when a field is missing or unexported in the destination struct. StructType is the type of the struct pointed to by the destination argument passed to Get or to Iterator.Next.

func (*ErrFieldMismatch) Error 

func (e *ErrFieldMismatch) Error() string

type GeoPoint 

type GeoPoint struct {
	Lat, Lng float64
}

GeoPoint represents a location as latitude/longitude in degrees.

func (GeoPoint) Valid 

func (g GeoPoint) Valid() bool

Valid returns whether a GeoPoint is within [-90, 90] latitude and [-180, 180] longitude.

type Iterator 

type Iterator struct {
	// contains filtered or unexported fields
}

Iterator is the result of running a query.

func (*Iterator) Cursor 

func (t *Iterator) Cursor() (Cursor, error)

Cursor returns a cursor for the iterator's current location.

Example 
package main

import (
	"fmt"
	"time"

	"cloud.google.com/go/datastore"
	"golang.org/x/net/context"
	"google.golang.org/api/iterator"
)

type Post struct {
	Title       string
	PublishedAt time.Time
	Comments    int
}

func main() {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	it := client.Run(ctx, datastore.NewQuery("Post"))
	for {
		var p Post
		_, err := it.Next(&p)
		if err == iterator.Done {
			break
		}
		if err != nil {
			// TODO: Handle error.
		}
		fmt.Println(p)
		cursor, err := it.Cursor()
		if err != nil {
			// TODO: Handle error.
		}
		// When printed, a cursor will display as a string that can be passed
		// to datastore.NewCursor.
		fmt.Printf("to resume with this post, use cursor %s\n", cursor)
	}
}

Output:

func (*Iterator) Next 

func (t *Iterator) Next(dst interface{}) (*Key, error)

Next returns the key of the next result. When there are no more results, iterator.Done is returned as the error.

If the query is not keys only and dst is non-nil, it also loads the entity stored for that key into the struct pointer or PropertyLoadSaver dst, with the same semantics and possible errors as for the Get function.

Example 
package main

import (
	"fmt"
	"time"

	"cloud.google.com/go/datastore"
	"golang.org/x/net/context"
	"google.golang.org/api/iterator"
)

type Post struct {
	Title       string
	PublishedAt time.Time
	Comments    int
}

func main() {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	it := client.Run(ctx, datastore.NewQuery("Post"))
	for {
		var p Post
		key, err := it.Next(&p)
		if err == iterator.Done {
			break
		}
		if err != nil {
			// TODO: Handle error.
		}
		fmt.Println(key, p)
	}
}

Output:

type Key 

type Key struct {
	// Kind cannot be empty.
	Kind string
	// Either ID or Name must be zero for the Key to be valid.
	// If both are zero, the Key is incomplete.
	ID   int64
	Name string
	// Parent must either be a complete Key or nil.
	Parent *Key

	// Namespace provides the ability to partition your data for multiple
	// tenants. In most cases, it is not necessary to specify a namespace.
	// See docs on datastore multitenancy for details:
	// https://cloud.google.com/datastore/docs/concepts/multitenancy
	Namespace string
}

Key represents the datastore key for a stored entity.

func DecodeKey 

func DecodeKey(encoded string) (*Key, error)

DecodeKey decodes a key from the opaque representation returned by Encode.

Example 
package main

import (
	"fmt"

	"cloud.google.com/go/datastore"
)

func main() {
	const encoded = "EgsKB0FydGljbGUQAQ"
	key, err := datastore.DecodeKey(encoded)
	if err != nil {
		// TODO: Handle error.
	}
	fmt.Println(key)
}

Output:

/Article,1

func IDKey added in v0.4.0 

func IDKey(kind string, id int64, parent *Key) *Key

IDKey creates a new key with an ID. The supplied kind cannot be empty. The supplied parent must either be a complete key or nil. The namespace of the new key is empty.

Example 
package main

import (
	"cloud.google.com/go/datastore"
)

func main() {
	// Key with numeric ID.
	k := datastore.IDKey("Article", 1, nil)
	_ = k // TODO: Use key.
}

Output:

func IncompleteKey added in v0.4.0 

func IncompleteKey(kind string, parent *Key) *Key

IncompleteKey creates a new incomplete key. The supplied kind cannot be empty. The namespace of the new key is empty.

Example 
package main

import (
	"cloud.google.com/go/datastore"
)

func main() {
	k := datastore.IncompleteKey("Article", nil)
	_ = k // TODO: Use incomplete key.
}

Output:

func NameKey added in v0.4.0 

func NameKey(kind, name string, parent *Key) *Key

NameKey creates a new key with a name. The supplied kind cannot be empty. The supplied parent must either be a complete key or nil. The namespace of the new key is empty.

Example 
package main

import (
	"cloud.google.com/go/datastore"
)

func main() {
	// Key with string ID.
	k := datastore.NameKey("Article", "article8", nil)
	_ = k // TODO: Use key.
}

Output:

func (*Key) Encode 

func (k *Key) Encode() string

Encode returns an opaque representation of the key suitable for use in HTML and URLs. This is compatible with the Python and Java runtimes.

Example 
package main

import (
	"fmt"

	"cloud.google.com/go/datastore"
)

func main() {
	key := datastore.IDKey("Article", 1, nil)
	encoded := key.Encode()
	fmt.Println(encoded)
}

Output:

EgsKB0FydGljbGUQAQ

func (*Key) Equal 

func (k *Key) Equal(o *Key) bool

Equal reports whether two keys are equal. Two keys are equal if they are both nil, or if their kinds, IDs, names, namespaces and parents are equal.

func (*Key) GobDecode 

func (k *Key) GobDecode(buf []byte) error

GobDecode unmarshals a sequence of bytes using an encoding/gob.Decoder.

func (*Key) GobEncode 

func (k *Key) GobEncode() ([]byte, error)

GobEncode marshals the key into a sequence of bytes using an encoding/gob.Encoder.

func (*Key) Incomplete 

func (k *Key) Incomplete() bool

Incomplete reports whether the key does not refer to a stored entity.

func (*Key) MarshalJSON 

func (k *Key) MarshalJSON() ([]byte, error)

MarshalJSON marshals the key into JSON.

func (*Key) String 

func (k *Key) String() string

String returns a string representation of the key.

func (*Key) UnmarshalJSON 

func (k *Key) UnmarshalJSON(buf []byte) error

UnmarshalJSON unmarshals a key JSON object into a Key.

type MultiError 

type MultiError []error

MultiError is returned by batch operations when there are errors with particular elements. Errors will be in a one-to-one correspondence with the input elements; successful elements will have a nil entry.

func (MultiError) Error 

func (m MultiError) Error() string

type PendingKey 

type PendingKey struct {
	// contains filtered or unexported fields
}

PendingKey represents the key for newly-inserted entity. It can be resolved into a Key by calling the Key method of Commit.

type Property 

type Property struct {
	// Name is the property name.
	Name string
	// Value is the property value. The valid types are:
	//	- int64
	//	- bool
	//	- string
	//	- float64
	//	- *Key
	//	- time.Time
	//	- GeoPoint
	//	- []byte (up to 1 megabyte in length)
	//	- *Entity (representing a nested struct)
	// Value can also be:
	//	- []interface{} where each element is one of the above types
	// This set is smaller than the set of valid struct field types that the
	// datastore can load and save. A Value's type must be explicitly on
	// the list above; it is not sufficient for the underlying type to be
	// on that list. For example, a Value of "type myInt64 int64" is
	// invalid. Smaller-width integers and floats are also invalid. Again,
	// this is more restrictive than the set of valid struct field types.
	//
	// A Value will have an opaque type when loading entities from an index,
	// such as via a projection query. Load entities into a struct instead
	// of a PropertyLoadSaver when using a projection query.
	//
	// A Value may also be the nil interface value; this is equivalent to
	// Python's None but not directly representable by a Go struct. Loading
	// a nil-valued property into a struct will set that field to the zero
	// value.
	Value interface{}
	// NoIndex is whether the datastore cannot index this property.
	// If NoIndex is set to false, []byte and string values are limited to
	// 1500 bytes.
	NoIndex bool
}

Property is a name/value pair plus some metadata. A datastore entity's contents are loaded and saved as a sequence of Properties. Each property name must be unique within an entity.

func SaveStruct 

func SaveStruct(src interface{}) ([]Property, error)

SaveStruct returns the properties from src as a slice of Properties. src must be a struct pointer.

Example 
package main

import (
	"fmt"

	"cloud.google.com/go/datastore"
)

func main() {
	type Player struct {
		User  string
		Score int
	}

	p := &Player{
		User:  "Alice",
		Score: 97,
	}
	props, err := datastore.SaveStruct(p)
	if err != nil {
		// TODO: Handle error.
	}
	fmt.Println(props)
	// TODO(jba): make this output stable: Output: [{User Alice false} {Score 97 false}]
}

Output:

type PropertyList 

type PropertyList []Property

PropertyList converts a []Property to implement PropertyLoadSaver.

func (*PropertyList) Load 

func (l *PropertyList) Load(p []Property) error

Load loads all of the provided properties into l. It does not first reset *l to an empty slice.

func (*PropertyList) Save 

func (l *PropertyList) Save() ([]Property, error)

Save saves all of l's properties as a slice of Properties.

type PropertyLoadSaver 

type PropertyLoadSaver interface {
	Load([]Property) error
	Save() ([]Property, error)
}

PropertyLoadSaver can be converted from and to a slice of Properties.

type Query 

type Query struct {
	// contains filtered or unexported fields
}

Query represents a datastore query.

func NewQuery 

func NewQuery(kind string) *Query

NewQuery creates a new Query for a specific entity kind.

An empty kind means to return all entities, including entities created and managed by other App Engine features, and is called a kindless query. Kindless queries cannot include filters or sort orders on property values.

Example 
package main

import (
	"cloud.google.com/go/datastore"
)

func main() {
	// Query for Post entities.
	q := datastore.NewQuery("Post")
	_ = q // TODO: Use the query with Client.Run.
}

Output:
Example (Options) 
package main

import (
	"cloud.google.com/go/datastore"
)

func main() {
	// Query to order the posts by the number of comments they have recieved.
	q := datastore.NewQuery("Post").Order("-Comments")
	// Start listing from an offset and limit the results.
	q = q.Offset(20).Limit(10)
	_ = q // TODO: Use the query.
}

Output:

func (*Query) Ancestor 

func (q *Query) Ancestor(ancestor *Key) *Query

Ancestor returns a derivative query with an ancestor filter. The ancestor should not be nil.

func (*Query) Distinct 

func (q *Query) Distinct() *Query

Distinct returns a derivative query that yields de-duplicated entities with respect to the set of projected fields. It is only used for projection queries. Distinct cannot be used with DistinctOn.

func (*Query) DistinctOn added in v0.7.0 

func (q *Query) DistinctOn(fieldNames ...string) *Query

DistinctOn returns a derivative query that yields de-duplicated entities with respect to the set of the specified fields. It is only used for projection queries. The field list should be a subset of the projected field list. DistinctOn cannot be used with Distinct.

func (*Query) End 

func (q *Query) End(c Cursor) *Query

End returns a derivative query with the given end point.

func (*Query) EventualConsistency 

func (q *Query) EventualConsistency() *Query

EventualConsistency returns a derivative query that returns eventually consistent results. It only has an effect on ancestor queries.

func (*Query) Filter 

func (q *Query) Filter(filterStr string, value interface{}) *Query

Filter returns a derivative query with a field-based filter. The filterStr argument must be a field name followed by optional space, followed by an operator, one of ">", "<", ">=", "<=", or "=". Fields are compared against the provided value using the operator. Multiple filters are AND'ed together. Field names which contain spaces, quote marks, or operator characters should be passed as quoted Go string literals as returned by strconv.Quote or the fmt package's %q verb.

func (*Query) KeysOnly 

func (q *Query) KeysOnly() *Query

KeysOnly returns a derivative query that yields only keys, not keys and entities. It cannot be used with projection queries.

func (*Query) Limit 

func (q *Query) Limit(limit int) *Query

Limit returns a derivative query that has a limit on the number of results returned. A negative value means unlimited.

func (*Query) Namespace added in v0.5.0 

func (q *Query) Namespace(ns string) *Query

Namespace returns a derivative query that is associated with the given namespace.

A namespace may be used to partition data for multi-tenant applications. For details, see https://cloud.google.com/datastore/docs/concepts/multitenancy.

func (*Query) Offset 

func (q *Query) Offset(offset int) *Query

Offset returns a derivative query that has an offset of how many keys to skip over before returning results. A negative value is invalid.

func (*Query) Order 

func (q *Query) Order(fieldName string) *Query

Order returns a derivative query with a field-based sort order. Orders are applied in the order they are added. The default order is ascending; to sort in descending order prefix the fieldName with a minus sign (-). Field names which contain spaces, quote marks, or the minus sign should be passed as quoted Go string literals as returned by strconv.Quote or the fmt package's %q verb.

func (*Query) Project 

func (q *Query) Project(fieldNames ...string) *Query

Project returns a derivative query that yields only the given fields. It cannot be used with KeysOnly.

func (*Query) Start 

func (q *Query) Start(c Cursor) *Query

Start returns a derivative query with the given start point.

Example 
package main

import (
	"cloud.google.com/go/datastore"
	"golang.org/x/net/context"
)

func getCursor() string { return "" }

func main() {
	// This example demonstrates how to use cursors and Query.Start
	// to resume an iteration.
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, "project-id")
	if err != nil {
		// TODO: Handle error.
	}
	// getCursor represents a function that returns a cursor from a previous
	// iteration in string form.
	cursorString := getCursor()
	cursor, err := datastore.DecodeCursor(cursorString)
	if err != nil {
		// TODO: Handle error.
	}
	it := client.Run(ctx, datastore.NewQuery("Post").Start(cursor))
	_ = it // TODO: Use iterator.
}

Output:

func (*Query) Transaction 

func (q *Query) Transaction(t *Transaction) *Query

Transaction returns a derivative query that is associated with the given transaction.

All reads performed as part of the transaction will come from a single consistent snapshot. Furthermore, if the transaction is set to a serializable isolation level, another transaction cannot concurrently modify the data that is read or modified by this transaction.

type Transaction 

type Transaction struct {
	// contains filtered or unexported fields
}

Transaction represents a set of datastore operations to be committed atomically.

Operations are enqueued by calling the Put and Delete methods on Transaction (or their Multi-equivalents). These operations are only committed when the Commit method is invoked. To ensure consistency, reads must be performed by using Transaction's Get method or by using the Transaction method when building a query.

A Transaction must be committed or rolled back exactly once.

func (*Transaction) Commit 

func (t *Transaction) Commit() (*Commit, error)

Commit applies the enqueued operations atomically.

func (*Transaction) Delete 

func (t *Transaction) Delete(key *Key) error

Delete is the transaction-specific version of the package function Delete. Delete enqueues the deletion of the entity for the given key, to be committed atomically upon calling Commit.

func (*Transaction) DeleteMulti 

func (t *Transaction) DeleteMulti(keys []*Key) error

DeleteMulti is a batch version of Delete.

func (*Transaction) Get 

func (t *Transaction) Get(key *Key, dst interface{}) error

Get is the transaction-specific version of the package function Get. All reads performed during the transaction will come from a single consistent snapshot. Furthermore, if the transaction is set to a serializable isolation level, another transaction cannot concurrently modify the data that is read or modified by this transaction.

func (*Transaction) GetMulti 

func (t *Transaction) GetMulti(keys []*Key, dst interface{}) error

GetMulti is a batch version of Get.

func (*Transaction) Put 

func (t *Transaction) Put(key *Key, src interface{}) (*PendingKey, error)

Put is the transaction-specific version of the package function Put.

Put returns a PendingKey which can be resolved into a Key using the return value from a successful Commit. If key is an incomplete key, the returned pending key will resolve to a unique key generated by the datastore.

func (*Transaction) PutMulti 

func (t *Transaction) PutMulti(keys []*Key, src interface{}) ([]*PendingKey, error)

PutMulti is a batch version of Put. One PendingKey is returned for each element of src in the same order.

func (*Transaction) Rollback 

func (t *Transaction) Rollback() error

Rollback abandons a pending transaction.

type TransactionOption 

type TransactionOption interface {
	// contains filtered or unexported methods
}

TransactionOption configures the way a transaction is executed.

func MaxAttempts added in v0.2.0 

func MaxAttempts(attempts int) TransactionOption

MaxAttempts returns a TransactionOption that overrides the default 3 attempt times.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.