README

Cloud Datastore Go Reference

Example Usage

First create a datastore.Client to use throughout your application:

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

Then use that client to interact with the API:

type Post struct {
	Title       string
	Body        string `datastore:",noindex"`
	PublishedAt time.Time
}
keys := []*datastore.Key{
	datastore.NameKey("Post", "post1", nil),
	datastore.NameKey("Post", "post2", nil),
}
posts := []*Post{
	{Title: "Post 1", Body: "...", PublishedAt: time.Now()},
	{Title: "Post 2", Body: "...", PublishedAt: time.Now()},
}
if _, err := client.PutMulti(ctx, keys, posts); err != nil {
	log.Fatal(err)
}
Expand ▾ Collapse ▴

Documentation

Overview

Package datastore provides a client for Google Cloud Datastore.

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

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, retrieved as local time)
- Structs whose fields are all valid value types
- Pointers to structs whose fields are all valid value types
- Slices of any of the above
- Pointers to a signed integer, bool, string, float32, or float64

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.
	}
	defer dsClient.Close()

	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.

Mutate generalizes PutMulti and DeleteMulti to a sequence of any Datastore mutations. It takes a series of mutations created with NewInsert, NewUpdate, NewUpsert and NewDelete and applies them. Datastore.Mutate uses non-transactional mode; if atomicity is required, use Transaction.Mutate instead.

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 PropertyLoadSaver 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 a zero value, then the field will be omitted on Save. Zero values are best defined in the golang spec (https://golang.org/ref/spec#The_zero_value). Struct field values will never be empty, except for nil pointers.

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

Slice Fields

A field of slice type corresponds to a Datastore array property, except for []byte, which corresponds to a Datastore blob.

Zero-length slice fields are not saved. Slice fields of length 1 or greater are saved as Datastore arrays. When a zero-length Datastore array is loaded into a slice field, the slice field remains unchanged.

If a non-array value is loaded into a slice field, the result will be a slice with one element, containing the value.

Loading Nulls

Loading a Datastore Null into a basic type (int, float, etc.) results in a zero value. Loading a Null into a slice of basic type results in a slice of size 1 containing the zero value. Loading a Null into a pointer field results in nil. Loading a Null into a field of struct type is an error.

Pointer Fields

A struct field can be a pointer to a signed integer, floating-point number, string or bool. Putting a non-nil pointer will store its dereferenced value. Putting a nil pointer will store a Datastore Null property, unless the field is marked omitempty, in which case no property will be stored.

Loading a Null into a pointer field sets the pointer to nil. Loading any other value allocates new storage with the value, and sets the field to point to it.

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__"`
}

func main() {
	ctx := context.Background()
	dsClient, err := datastore.NewClient(ctx, "my-project")
	if err != nil {
		// Handle error.
	}
	defer dsClient.Close()

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

	var entities []MyEntity
	q := datastore.NewQuery("Entity").Filter("A =", 12).Limit(1)
	if _, err := dsClient.GetAll(ctx, q, &entities); 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.

Note: embedded struct fields must be named to be encoded as an Entity. For example, in case of a type Outer with an embedded field Inner:

type Outer struct {
	Inner
}

all the Inner struct fields will be treated as fields of Outer itself.

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 or PropertyLoadSaver implementers. 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.

The KeyLoader Interface

If a type implements the PropertyLoadSaver interface, it may also want to implement the KeyLoader interface. The KeyLoader interface exists to allow implementations of PropertyLoadSaver to also load an Entity's Key into the Go type. This type may be a struct pointer, but it does not have to be. The datastore package will call LoadKey when getting the entity's contents, after calling Load.

Example code:

type WithKeyExample struct {
	I int
	Key   *datastore.Key
}

func (x *WithKeyExample) LoadKey(k *datastore.Key) error {
	x.Key = k
	return nil
}

func (x *WithKeyExample) Load(ps []datastore.Property) error {
	// Load I as usual.
	return datastore.LoadStruct(x, ps)
}

func (x *WithKeyExample) Save() ([]datastore.Property, error) {
	// Save I as usual.
	return datastore.SaveStruct(x)
}

To load a Key into a struct which does not implement the PropertyLoadSaver interface, see the "Key Field" section above.

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

	t := client.Run(ctx, q)
	for {
		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)
}

Pass the ReadOnly option to RunInTransaction if your transaction is used only for Get, GetMulti or queries. Read-only transactions are more efficient.

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.

Index

Examples

Constants

View Source
const DetectProjectID = "*detect-project-id*"

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

    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
          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. DetectProjectID can be passed as the projectID argument to instruct NewClient to detect the project ID from the credentials. Call (*Client).Close() when done with the client.

              Example
              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
                Output:
                
                

                func (*Client) Close

                func (c *Client) Close() error

                  Close closes the Client. Call Close to clean up resources when done with the Client.

                  func (*Client) Count

                  func (c *Client) Count(ctx context.Context, q *Query) (n int, err 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 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
                    Output:
                    
                    

                    func (*Client) Delete

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

                      Delete deletes the entity for the given key.

                      Example
                      Output:
                      
                      

                      func (*Client) DeleteMulti

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

                        DeleteMulti is a batch version of Delete.

                        err may be a MultiError. See ExampleMultiError to check it.

                        Example
                        Output:
                        
                        

                        func (*Client) Get

                        func (c *Client) Get(ctx context.Context, key *Key, dst interface{}) (err 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
                          Output:
                          
                          

                          func (*Client) GetAll

                          func (c *Client) GetAll(ctx context.Context, q *Query, dst interface{}) (keys []*Key, err 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
                            Output:
                            
                            

                            func (*Client) GetMulti

                            func (c *Client) GetMulti(ctx context.Context, keys []*Key, dst interface{}) (err 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.

                              err may be a MultiError. See ExampleMultiError to check it.

                              Example
                              Output:
                              
                              

                              func (*Client) Mutate

                              func (c *Client) Mutate(ctx context.Context, muts ...*Mutation) (ret []*Key, err error)

                                Mutate applies one or more mutations. Mutations are applied in non-transactional mode. If you need atomicity, use Transaction.Mutate. It returns the keys of the argument Mutations, in the same order.

                                If any of the mutations are invalid, Mutate returns a MultiError with the errors. Mutate returns a MultiError in this case even if there is only one Mutation. See ExampleMultiError to check it.

                                Example
                                Output:
                                
                                

                                func (*Client) NewTransaction

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

                                  NewTransaction starts a new transaction.

                                  Example
                                  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 the given key. src must be a struct pointer or implement PropertyLoadSaver; if the struct pointer has any unexported fields they will be skipped. If the key is incomplete, the returned key will be a unique key generated by the datastore.

                                    Example
                                    Output:
                                    
                                    
                                    Example (Flatten)
                                    Output:
                                    
                                    

                                    func (*Client) PutMulti

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

                                      PutMulti is a batch version of Put.

                                      src must satisfy the same conditions as the dst argument to GetMulti. err may be a MultiError. See ExampleMultiError to check it.

                                      Example (InterfaceSlice)
                                      Output:
                                      
                                      
                                      Example (Slice)
                                      Output:
                                      
                                      

                                      func (*Client) Run

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

                                        Run runs the given query in the given context.

                                        Example
                                        Output:
                                        
                                        

                                        func (*Client) RunInTransaction

                                        func (c *Client) RunInTransaction(ctx context.Context, f func(tx *Transaction) error, opts ...TransactionOption) (cmt *Commit, err 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
                                          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
                                              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)

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

                                                  Example
                                                  Output:
                                                  
                                                  

                                                  func (Cursor) String

                                                  func (c Cursor) String() string

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

                                                    type Entity

                                                    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.

                                                              It is not safe for concurrent use.

                                                              func (*Iterator) Cursor

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

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

                                                                Example
                                                                Output:
                                                                
                                                                

                                                                func (*Iterator) Next

                                                                func (t *Iterator) Next(dst interface{}) (k *Key, err 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
                                                                  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
                                                                      Output:
                                                                      
                                                                      /Article,1
                                                                      

                                                                      func IDKey

                                                                      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
                                                                        Output:
                                                                        
                                                                        

                                                                        func IncompleteKey

                                                                        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
                                                                          Output:
                                                                          
                                                                          

                                                                          func NameKey

                                                                          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
                                                                            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
                                                                              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 KeyLoader

                                                                                            type KeyLoader interface {
                                                                                            	// PropertyLoadSaver is embedded because a KeyLoader
                                                                                            	// must also always implement PropertyLoadSaver.
                                                                                            	PropertyLoadSaver
                                                                                            	LoadKey(k *Key) error
                                                                                            }

                                                                                              KeyLoader can store 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.

                                                                                                Example
                                                                                                Output:
                                                                                                
                                                                                                

                                                                                                func (MultiError) Error

                                                                                                func (m MultiError) Error() string

                                                                                                type Mutation

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

                                                                                                  A Mutation represents a change to a Datastore entity.

                                                                                                  func NewDelete

                                                                                                  func NewDelete(k *Key) *Mutation

                                                                                                    NewDelete creates a Mutation that deletes the entity with key k.

                                                                                                    func NewInsert

                                                                                                    func NewInsert(k *Key, src interface{}) *Mutation

                                                                                                      NewInsert creates a Mutation that will save the entity src into the datastore with key k. If k already exists, calling Mutate with the Mutation will lead to a gRPC codes.AlreadyExists error.

                                                                                                      func NewUpdate

                                                                                                      func NewUpdate(k *Key, src interface{}) *Mutation

                                                                                                        NewUpdate creates a Mutation that replaces the entity in the datastore with key k. If k does not exist, calling Mutate with the Mutation will lead to a gRPC codes.NotFound error. See Client.Put for valid values of src.

                                                                                                        func NewUpsert

                                                                                                        func NewUpsert(k *Key, src interface{}) *Mutation

                                                                                                          NewUpsert creates a Mutation that saves the entity src into the datastore with key k, whether or not k exists. See Client.Put for valid values of src.

                                                                                                          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 (retrieved as local 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
                                                                                                                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
                                                                                                                            Output:
                                                                                                                            
                                                                                                                            
                                                                                                                            Example (Options)
                                                                                                                            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

                                                                                                                                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

                                                                                                                                            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
                                                                                                                                                      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() (c *Commit, err 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) (err error)

                                                                                                                                                                DeleteMulti is a batch version of Delete. TODO(jba): rewrite in terms of Mutate.

                                                                                                                                                                func (*Transaction) Get

                                                                                                                                                                func (t *Transaction) Get(key *Key, dst interface{}) (err 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{}) (err error)

                                                                                                                                                                    GetMulti is a batch version of Get.

                                                                                                                                                                    func (*Transaction) Mutate

                                                                                                                                                                    func (t *Transaction) Mutate(muts ...*Mutation) ([]*PendingKey, error)

                                                                                                                                                                      Mutate adds the mutations to the transaction. They will all be applied atomically upon calling Commit. Mutate returns a PendingKey for each Mutation in the argument list, in the same order. PendingKeys for Delete mutations are always nil.

                                                                                                                                                                      If any of the mutations are invalid, Mutate returns a MultiError with the errors. Mutate returns a MultiError in this case even if there is only one Mutation.

                                                                                                                                                                      For an example, see Client.Mutate.

                                                                                                                                                                      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{}) (ret []*PendingKey, err error)

                                                                                                                                                                          PutMulti is a batch version of Put. One PendingKey is returned for each element of src in the same order. TODO(jba): rewrite in terms of Mutate.

                                                                                                                                                                          func (*Transaction) Rollback

                                                                                                                                                                          func (t *Transaction) Rollback() (err error)

                                                                                                                                                                            Rollback abandons a pending transaction.

                                                                                                                                                                            type TransactionOption

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

                                                                                                                                                                              TransactionOption configures the way a transaction is executed.

                                                                                                                                                                              var ReadOnly TransactionOption

                                                                                                                                                                                ReadOnly is a TransactionOption that marks the transaction as read-only.

                                                                                                                                                                                func MaxAttempts

                                                                                                                                                                                func MaxAttempts(attempts int) TransactionOption

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

                                                                                                                                                                                  Directories

                                                                                                                                                                                  Path Synopsis
                                                                                                                                                                                  admin
                                                                                                                                                                                  apiv1
                                                                                                                                                                                  Package admin is an auto-generated package for the Cloud Datastore API.
                                                                                                                                                                                  Package admin is an auto-generated package for the Cloud Datastore API.
                                                                                                                                                                                  internal
                                                                                                                                                                                  gaepb
                                                                                                                                                                                  Package gaepb is a subset of protobufs, copied from google.golang.org/appengine/internal/datastore.
                                                                                                                                                                                  Package gaepb is a subset of protobufs, copied from google.golang.org/appengine/internal/datastore.