Documentation
¶
Index ¶
- Constants
- Variables
- func Delete(ctx context.Context, key *Key) error
- func DeleteMulti(ctx context.Context, keys []*Key) error
- func Get(ctx context.Context, key *Key, dst interface{}) error
- func GetMulti(ctx context.Context, key []*Key, dst interface{}) error
- func LoadStruct(dst interface{}, p []Property) error
- func RunInTransaction(ctx context.Context, f func(context.Context) error) error
- type ByteString
- type ContextKey
- type Cursor
- type ErrFieldMismatch
- type ErrHTTP
- type Iterator
- type Key
- func AllocateIDs(ctx context.Context, keys []*Key) ([]*Key, error)
- func DecodeKey(encoded string) (*Key, error)
- func NewIncompleteKey(ctx context.Context, kind string, parent *Key) *Key
- func NewKey(ctx context.Context, kind, name string, id int64, parent *Key) *Key
- func Put(ctx context.Context, key *Key, src interface{}) (*Key, error)
- func PutMulti(ctx context.Context, keys []*Key, src interface{}) ([]*Key, error)
- func (k *Key) Encode() string
- func (k *Key) Equal(o *Key) bool
- func (k *Key) GobDecode(buf []byte) error
- func (k *Key) GobEncode() ([]byte, error)
- func (k *Key) ID() int64
- func (k *Key) Incomplete() bool
- func (k *Key) Kind() string
- func (k *Key) MarshalJSON() ([]byte, error)
- func (k *Key) Name() string
- func (k *Key) Namespace() string
- func (k *Key) Parent() *Key
- func (k *Key) SetParent(v *Key)
- func (k *Key) String() string
- func (k *Key) UnmarshalJSON(buf []byte) error
- type MultiError
- type Property
- type PropertyList
- type PropertyLoadSaver
- type Query
- func (q *Query) Ancestor(ancestor *Key) *Query
- func (q *Query) Count(ctx context.Context) (int, error)
- func (q *Query) Distinct() *Query
- func (q *Query) End(c Cursor) *Query
- func (q *Query) EventualConsistency() *Query
- func (q *Query) Filter(filterStr string, value interface{}) *Query
- func (q *Query) GetAll(ctx context.Context, dst interface{}) ([]*Key, error)
- func (q *Query) KeysOnly() *Query
- func (q *Query) Limit(limit int) *Query
- func (q *Query) Offset(offset int) *Query
- func (q *Query) Order(fieldName string) *Query
- func (q *Query) Project(fieldNames ...string) *Query
- func (q *Query) Run(ctx context.Context) *Iterator
- func (q *Query) Start(c Cursor) *Query
Constants ¶
const ( // ScopeDatastore grants permissions to view and/or manage datastore entities ScopeDatastore = "https://www.googleapis.com/auth/datastore" // ScopeUserEmail grants permission to view the user's email address. // It is required to access the datastore ScopeUserEmail = "https://www.googleapis.com/auth/userinfo.email" )
Variables ¶
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") )
var Done = errors.New("datastore: query has no more results")
Done is returned when a query iteration has completed.
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 DeleteMulti ¶
DeleteMulti is a batch version of Delete.
func Get ¶
Get loads the entity stored for k 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.
func GetMulti ¶
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.
func LoadStruct ¶
LoadStruct loads the properties from p to dst. dst must be a struct pointer.
func RunInTransaction ¶
RunInTransaction runs f in a transaction. It calls f with a transaction context tc that f should use for all App Engine operations.
If f returns nil, RunInTransaction attempts to commit the transaction, returning nil if it succeeds. If the commit fails due to a conflicting transaction, RunInTransaction retries f, each time with a new transaction context. It gives up and returns ErrConcurrentTransaction after three failed attempts.
If f returns non-nil, then any datastore changes will not be applied and RunInTransaction returns that same error. The function f is not retried.
Note that when f returns, the transaction is not yet committed. Calling code must be careful not to assume that any of f's changes have been committed until RunInTransaction returns nil.
Nested transactions are not supported; c may not be a transaction context.
Types ¶
type ByteString ¶
type ByteString []byte
ByteString is a short byte slice (up to 500 bytes) that can be indexed.
type ContextKey ¶
type ContextKey string
ContextKey represents a context key specific to the datastore
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.
func DecodeCursor ¶
Decode decodes a cursor from its base-64 string representation.
type ErrFieldMismatch ¶
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 Iterator ¶
type Iterator struct {
// contains filtered or unexported fields
}
Iterator is the result of running a query.
func (*Iterator) Next ¶
Next returns the key of the next result. When there are no more results, 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.
type Key ¶
type Key struct {
// contains filtered or unexported fields
}
Key represents the datastore key for a stored entity, and is immutable.
func AllocateIDs ¶
AllocateIDs accepts a slice of incomplete keys and returns a slice of complete keys that are guaranteed to be valid in the datastore
func NewIncompleteKey ¶
NewIncompleteKey creates a new incomplete key. kind cannot be empty.
func NewKey ¶
NewKey creates a new key. kind cannot be empty. Either one or both of stringID and intID must be zero. If both are zero, the key returned is incomplete. parent must either be a complete key or nil.
func Put ¶
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.
func PutMulti ¶
PutMulti is a batch version of Put.
src must satisfy the same conditions as the dst argument to GetMulti.
func (*Key) Encode ¶
Encode returns an opaque representation of the key suitable for use in HTML and URLs. This is compatible with the Python and Java runtimes.
func (*Key) Incomplete ¶
Complete returns whether the key does not refer to a stored entity.
func (*Key) MarshalJSON ¶
func (*Key) UnmarshalJSON ¶
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 Property ¶
type Property struct {
// Name is the property name.
Name string
// Value is the property value. The valid types are:
// - int64
// - bool
// - string
// - float64
// - ByteString
// - *Key
// - time.Time
// - []byte (up to 1 megabyte in length)
// This set is smaller than the set of valid struct field types that the
// datastore can load and save. A Property Value cannot be a slice (apart
// from []byte); use multiple Properties instead. Also, 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.
NoIndex bool
// Multiple is whether the entity can have multiple properties with
// the same name. Even if a particular instance only has one property with
// a certain name, Multiple should be true if a struct would best represent
// it as a field of type []T instead of type T.
Multiple bool
}
Property is a name/value pair plus some metadata. A datastore entity's contents are loaded and saved as a sequence of Properties. An entity can have multiple Properties with the same name, provided that p.Multiple is true on all of that entity's Properties with that name.
func SaveStruct ¶
SaveStruct returns the properties from src as a slice of Properties. src must be a struct pointer.
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 or Properties.
type PropertyLoadSaver ¶
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 ¶
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.
func (*Query) Ancestor ¶
Ancestor returns a derivative query with an ancestor filter. The ancestor should not be nil.
func (*Query) Distinct ¶
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.
func (*Query) EventualConsistency ¶
EventualConsistency returns a derivative query that returns eventually consistent results. It only has an effect on ancestor queries.
func (*Query) Filter ¶
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.
func (*Query) GetAll ¶
GetAll runs the 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.
func (*Query) KeysOnly ¶
KeysOnly returns a derivative query that yields only keys, not keys and entities. It cannot be used with projection queries.
func (*Query) Limit ¶
Limit returns a derivative query that has a limit on the number of results returned. A negative value means unlimited.
func (*Query) Offset ¶
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 ¶
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 (-).
func (*Query) Project ¶
Project returns a derivative query that yields only the given fields. It cannot be used with KeysOnly.
Source Files