datastore

package
v0.0.0-...-e6cee59 Latest Latest
Warning

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

 Go to latest Published: Dec 29, 2015 License: BSD-3-Clause Imports: 22 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrInvalidKey            = datastore.ErrInvalidKey
	ErrNoSuchEntity          = datastore.ErrNoSuchEntity
	ErrConcurrentTransaction = datastore.ErrConcurrentTransaction

	// Stop is an alias for "github.com/luci/gae".Stop
	Stop = gae.Stop
)

These errors are returned by various datastore.Interface methods.

View Source 
var (
	// ErrMultipleInequalityFilter is returned from Query.Finalize if you build a
	// query which has inequality filters on multiple fields.
	ErrMultipleInequalityFilter = errors.New(
		"inequality filters on multiple properties in the same Query is not allowed")

	// ErrNullQuery is returned from Query.Finalize if you build a query for which
	// there cannot possibly be any results.
	ErrNullQuery = errors.New(
		"the query is overconstrained and can never have results")
)

Functions

func AddRawFilters 

func AddRawFilters(c context.Context, filts ...RawFilter) context.Context

AddRawFilters adds RawInterface filters to the context.

func GetMetaDefault 

func GetMetaDefault(getter MetaGetter, key string, dflt interface{}) interface{}

GetMetaDefault is a helper for GetMeta, allowing a default value.

If the metadata key is not available, or its type doesn't equal the homogenized type of dflt, then dflt will be returned.

Type homogenization: 

signed integer types -> int64
bool                 -> Toggle fields (bool)

Example: 

pls.GetMetaDefault("foo", 100).(int64)

func GetPLS 

func GetPLS(obj interface{}) interface {
	PropertyLoadSaver
	MetaGetterSetter
}

GetPLS resolves obj into default struct PropertyLoadSaver and MetaGetterSetter implementation.

obj must be a non-nil pointer to a struct of some sort.

By default, exported fields will be serialized to/from the datastore. If the field is not exported, it will be skipped by the serialization routines.

If a field is of a non-supported type (see Property for the list of supported property types), this function will panic. Other problems include duplicate field names (due to tagging), recursively defined structs, nested structures with multiple slices (e.g. slices of slices, either directly `[][]type` or indirectly `[]Embedded` where Embedded contains a slice.)

GetPLS supports the following struct tag syntax: 

`gae:"fieldName[,noindex]"` -- an alternate fieldname for an exportable
   field.  When the struct is serialized or deserialized, fieldName will be
   associated with the struct field instead of the field's Go name. This is
   useful when writing Go code which interfaces with appengine code written
   in other languages (like python) which use lowercase as their default
   datastore field names.

   A fieldName of "-" means that gae will ignore the field for all
   serialization/deserialization.

   if noindex is specified, then this field will not be indexed in the
   datastore, even if it was an otherwise indexable type. If fieldName is
   blank, and noindex is specifed, then fieldName will default to the
   field's actual name. Note that by default, all fields (with indexable
   types) are indexed.

`gae:"$metaKey[,<value>]` -- indicates a field is metadata. Metadata
   can be used to control filter behavior, or to store key data when using
   the Interface.KeyForObj* methods. The supported field types are:
     - Key
     - int64
     - string
     - Toggle (GetMeta and SetMeta treat the field as if it were bool)
   Additionally, int64, string and Toggle allow setting a default value
   in the struct field tag (the "<value>" portion).

   Only exported fields allow SetMeta, but all fields of appropriate type
   allow tagged defaults. See Examples.

`gae:"[-],extra"` -- indicates that any extra, unrecognized or mismatched
   property types (type in datastore doesn't match your struct's field
   type) should be loaded into and saved from this field. The precise type
   of the field must be PropertyMap. This form allows you to control the
   behavior of reads and writes when your schema changes, or to implement
   something like ndb.Expando with a mix of structured and unstructured
   fields.

   If the `-` is present, then datastore write operations will not put
   elements of this map into the datastore.

   If the field is non-exported, then read operations from the datastore
   will not populate the members of this map, but extra fields or
   structural differences encountered when reading into this struct will be
   silently ignored. This is useful if you want to just ignore old fields.

   If there is a conflict between a field in the struct and a same-named
   Property in the extra field, the field in the struct takes precedence.

   Recursive structs are supported, but all extra properties go to the
   topmost structure's Extra field. This is a bit non-intuitive, but the
   implementation complexity was deemed not worth it, since that sort of
   thing is generally only useful on schema changes, which should be
   transient.

   Examples:
     // "black hole": ignore mismatches, ignore on write
     _ PropertyMap `gae:"-,extra"

     // "expando": full content is read/written
     Expando PropertyMap `gae:",extra"

     // "convert": content is read from datastore, but lost on writes. This
     // is useful for doing conversions from an old schema to a new one,
     // since you can retrieve the old data and populate it into new fields,
     // for example. Probably should be used in conjunction with an
     // implementation of the PropertyLoadSaver interface so that you can
     // transparently upconvert to the new schema on load.
     Convert PropertyMap `gae:"-,extra"

Example "special" structure. This is supposed to be some sort of datastore singleton object. 

struct secretFoo {
  // _id and _kind are not exported, so setting their values will not be
  // reflected by GetMeta.
  _id   int64  `gae:"$id,1"`
  _kind string `gae:"$kind,InternalFooSingleton"`

  // Value is exported, so can be read and written by the PropertyLoadSaver,
  // but secretFoo is shared with a python appengine module which has
  // stored this field as 'value' instead of 'Value'.
  Value int64  `gae:"value"`
}

Example "normal" structure that you might use in a go-only appengine app. 

struct User {
  ID string `gae:"$id"`
  // "kind" is automatically implied by the struct name: "User"
  // "parent" is nil... Users are root entities

  // 'Name' will serialized to the datastore in the field 'Name'
  Name string
}

struct Comment {
  ID int64 `gae:"$id"`
  // "kind" is automatically implied by the struct name: "Comment"

  // Parent will be enforced by the application to be a User key.
  Parent Key `gae:"$parent"`

  // 'Lines' will serialized to the datastore in the field 'Lines'
  Lines []string
}

A pointer-to-struct may also implement MetaGetterSetter to provide more sophistocated metadata values. Explicitly defined fields (as shown above) always take precedence over fields manipulated by the MetaGetterSetter methods. So if your GetMeta handles "kind", but you explicitly have a $kind field, the $kind field will take precedence and your GetMeta implementation will not be called for "kind".

A struct overloading any of the PropertyLoadSaver or MetaGetterSetter interfaces may evoke the default struct behavior by using GetPLS on itself. For example: 

struct Special {
  Name string

  foo string
}

func (s *Special) Load(props PropertyMap) error {
  if foo, ok := props["foo"]; ok && len(foo) == 1 {
    s.foo = foo
    delete(props, "foo")
  }
  return GetPLS(s).Load(props)
}

func (s *Special) Save(withMeta bool) (PropertyMap, error) {
  props, err := GetPLS(s).Save(withMeta)
  if err != nil {
    return nil, err
  }
  props["foo"] = []Property{MkProperty(s.foo)}
  return props, nil
}

func (s *Special) Problem() error {
  return GetPLS(s).Problem()
}

Additionally, any field ptr-to-type may implement the PropertyConverter interface to allow a single field to, for example, implement some alternate encoding (json, gzip), or even just serialize to/from a simple string field. This applies to normal fields, as well as metadata fields. It can be useful for storing struct '$id's which have multi-field meanings. For example, the Person struct below could be initialized in go as `&Person{Name{"Jane", "Doe"}}`, retaining Jane's name as manipulable Go fields. However, in the datastore, it would have a key of `/Person,"Jane|Doe"`, and loading the struct from the datastore as part of a Query, for example, would correctly populate Person.Name.First and Person.Name.Last. 

type Name struct {
  First string
  Last string
}

func (n *Name) ToProperty() (Property, error) {
  return fmt.Sprintf("%s|%s", n.First, n.Last)
}

func (n *Name) FromProperty(p Property) error {
  // check p to be a PTString
  // split on "|"
  // assign to n.First, n.Last
}

type Person struct {
  ID Name `gae:"$id"`
}

func SetRaw 

func SetRaw(c context.Context, rds RawInterface) context.Context

SetRaw sets the current Datastore object in the context. Useful for testing with a quick mock. This is just a shorthand SetRawFactory invocation to set a factory which always returns the same object.

func SetRawFactory 

func SetRawFactory(c context.Context, rdsf RawFactory) context.Context

SetRawFactory sets the function to produce Datastore instances, as returned by the GetRaw method.

func UpconvertUnderlyingType 

func UpconvertUnderlyingType(o interface{}) interface{}

UpconvertUnderlyingType takes an object o, and attempts to convert it to its native datastore-compatible type. e.g. int16 will convert to int64, and `type Foo string` will convert to `string`.

Types

type Cursor 

type Cursor interface {
	fmt.Stringer
}

Cursor wraps datastore.Cursor.

type CursorCB 

type CursorCB func() (Cursor, error)

CursorCB is used to obtain a Cursor while Run'ing a query on either Interface or RawInterface.

it can be invoked to obtain the current cursor.

type DeleteMultiCB 

type DeleteMultiCB func(err error) error

DeleteMultiCB is the callback signature provided to RawInterface.DeleteMulti

  • err is an error associated with deleting this entity.

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 FinalizedQuery 

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

FinalizedQuery is the representation of a Query which has been normalized.

It contains only fully-specified, non-redundant, non-conflicting information pertaining to the Query to run. It can only represent a valid query.

func (*FinalizedQuery) Ancestor 

func (q *FinalizedQuery) Ancestor() *Key

Ancestor returns the ancestor filter key, if any. This is a convenience function for getting the value from EqFilters()["__ancestor__"].

func (*FinalizedQuery) Bounds 

func (q *FinalizedQuery) Bounds() (start, end Cursor)

Bounds returns the start and end Cursors. One or both may be nil. The Cursors returned are implementation-specific depending on the actual RawInterface implementation and the filters installed (if the filters interfere with Cursor production).

func (*FinalizedQuery) Distinct 

func (q *FinalizedQuery) Distinct() bool

Distinct returnst true iff this is a distinct projection query. It will never be true for non-projection queries.

func (*FinalizedQuery) EqFilters 

func (q *FinalizedQuery) EqFilters() map[string]PropertySlice

EqFilters returns all the equality filters. The map key is the field name and the PropertySlice is the values that field should equal.

This includes a special equality filter on "__ancestor__". If "__ancestor__" is present in the result, it's guaranteed to have 1 value in the PropertySlice which is of type *Key.

func (*FinalizedQuery) EventuallyConsistent 

func (q *FinalizedQuery) EventuallyConsistent() bool

EventuallyConsistent returns true iff this query will be eventually consistent. This is true when the query is a non-ancestor query, or when it's an ancestory query with the 'EventualConsistency(true)' option set.

func (*FinalizedQuery) GQL 

func (q *FinalizedQuery) GQL() string

GQL returns a correctly formatted Cloud Datastore GQL expression which is equivalent to this query.

The flavor of GQL that this emits is defined here: 

https://cloud.google.com/datastore/docs/apis/gql/gql_reference

NOTE: Cursors are omitted because currently there's currently no syntax for literal cursors.

NOTE: GeoPoint values are emitted with speculated future syntax. There is currently no syntax for literal GeoPoint values.

func (*FinalizedQuery) IneqFilterHigh 

func (q *FinalizedQuery) IneqFilterHigh() (field, op string, val Property)

IneqFilterHigh returns the field name, operator and value for the high-side inequality filter. If the returned field name is "", it means that there's now upper inequality bound on this query.

If field is non-empty, op may have the values "<" or "<=".

func (*FinalizedQuery) IneqFilterLow 

func (q *FinalizedQuery) IneqFilterLow() (field, op string, val Property)

IneqFilterLow returns the field name, operator and value for the low-side inequality filter. If the returned field name is "", it means that there's now lower inequality bound on this query.

If field is non-empty, op may have the values ">" or ">=".

func (*FinalizedQuery) IneqFilterProp 

func (q *FinalizedQuery) IneqFilterProp() string

IneqFilterProp returns the inequality filter property name, if one is used for this filter. An empty return value means that this query does not contain any inequality filters.

func (*FinalizedQuery) KeysOnly 

func (q *FinalizedQuery) KeysOnly() bool

KeysOnly returns true iff this query will only return keys (as opposed to a normal or projection query).

func (*FinalizedQuery) Kind 

func (q *FinalizedQuery) Kind() string

Kind returns the datastore 'Kind' over which this query operates. It may be empty for a kindless query.

func (*FinalizedQuery) Limit 

func (q *FinalizedQuery) Limit() (int32, bool)

Limit returns the maximum number of responses this query will retrieve, and a boolean indicating if the limit is set.

func (*FinalizedQuery) Offset 

func (q *FinalizedQuery) Offset() (int32, bool)

Offset returns the number of responses this query will skip before returning data, and a boolean indicating if the offset is set.

func (*FinalizedQuery) Orders 

func (q *FinalizedQuery) Orders() []IndexColumn

Orders returns the sort orders that this query will use, including all orders implied by the projections, and the implicit __key__ order at the end.

func (*FinalizedQuery) Original 

func (q *FinalizedQuery) Original() *Query

Original returns the original Query object from which this FinalizedQuery was derived.

func (*FinalizedQuery) Project 

func (q *FinalizedQuery) Project() []string

Project is the list of fields that this query projects on, or empty if this is not a projection query.

func (*FinalizedQuery) String 

func (q *FinalizedQuery) String() string

func (*FinalizedQuery) Valid 

func (q *FinalizedQuery) Valid(aid, ns string) error

Valid returns true iff this FinalizedQuery is valid in the provided appID and namespace.

This checks the ancestor filter (if any), as well as the inequality filters if they filter on '__key__'.

In particular, it does NOT validate equality filters which happen to have values of type PTKey, nor does it validate inequality filters that happen to have values of type PTKey (but don't filter on the magic '__key__' field).

type GeoPoint 

type GeoPoint struct {
	Lat, Lng float64
}

GeoPoint represents a location as latitude/longitude in degrees.

You probably shouldn't use these, but their inclusion here is so that the datastore service can interact (and round-trip) correctly with other datastore API implementations.

func (GeoPoint) Valid 

func (g GeoPoint) Valid() bool

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

type GetMultiCB 

type GetMultiCB func(val PropertyMap, err error) error

GetMultiCB is the callback signature provided to RawInterface.GetMulti

  • val is the data of the entity
  • It may be nil if some of the keys to the GetMulti were bad, since all keys are validated before the RPC occurs!
  • err is an error associated with this entity (e.g. ErrNoSuchEntity).

type IndexColumn 

type IndexColumn struct {
	Property   string
	Descending bool
}

IndexColumn represents a sort order for a single entity field.

func ParseIndexColumn 

func ParseIndexColumn(spec string) (IndexColumn, error)

ParseIndexColumn takes a spec in the form of /\s*-?\s*.+\s*/, and returns an IndexColumn. Examples are: 

`- Field `:  IndexColumn{Property: "Field", Descending: true}
`Something`: IndexColumn{Property: "Something", Descending: false}

`+Field` is invalid. “ is invalid.

func (IndexColumn) GQL 

func (i IndexColumn) GQL() string

GQL returns a correctly formatted Cloud Datastore GQL literal which is valid for the `ORDER BY` clause.

The flavor of GQL that this emits is defined here: 

https://cloud.google.com/datastore/docs/apis/gql/gql_reference

func (IndexColumn) String 

func (i IndexColumn) String() string

String returns a human-readable version of this IndexColumn which is compatible with ParseIndexColumn.

type IndexDefinition 

type IndexDefinition struct {
	Kind     string
	Ancestor bool
	SortBy   []IndexColumn
}

IndexDefinition holds the parsed definition of a datastore index definition.

func (*IndexDefinition) Builtin 

func (id *IndexDefinition) Builtin() bool

Builtin returns true iff the IndexDefinition is one of the automatic built-in indexes.

func (*IndexDefinition) Compound 

func (id *IndexDefinition) Compound() bool

Compound returns true iff this IndexDefinition is a valid compound index definition.

NOTE: !Builtin() does not imply Compound().

func (*IndexDefinition) Equal 

func (id *IndexDefinition) Equal(o *IndexDefinition) bool

Equal returns true if the two IndexDefinitions are equivalent.

func (*IndexDefinition) Flip 

func (id *IndexDefinition) Flip() *IndexDefinition

Flip returns an IndexDefinition with its SortBy field in reverse order.

func (*IndexDefinition) GetFullSortOrder 

func (id *IndexDefinition) GetFullSortOrder() []IndexColumn

GetFullSortOrder gets the full sort order for this IndexDefinition, including an extra "__ancestor__" column at the front if this index has Ancestor set to true.

func (*IndexDefinition) Less 

func (id *IndexDefinition) Less(o *IndexDefinition) bool

Less returns true iff id is ordered before o.

func (*IndexDefinition) Normalize 

func (id *IndexDefinition) Normalize() *IndexDefinition

Normalize returns an IndexDefinition which has a normalized SortBy field.

This is just appending __key__ if it's not explicitly the last field in this IndexDefinition.

func (*IndexDefinition) PrepForIdxTable 

func (id *IndexDefinition) PrepForIdxTable() *IndexDefinition

PrepForIdxTable normalize and then flips the IndexDefinition.

func (*IndexDefinition) String 

func (id *IndexDefinition) String() string

func (*IndexDefinition) YAMLString 

func (id *IndexDefinition) YAMLString() (string, error)

YAMLString returns the YAML representation of this IndexDefinition.

If the index definition is Builtin() or not Compound(), this will return an error.

type IndexSetting 

type IndexSetting bool

IndexSetting indicates whether or not a Property should be indexed by the datastore. 

const (
	ShouldIndex IndexSetting = false
	NoIndex     IndexSetting = true
)

ShouldIndex is the default, which is why it must assume the zero value, even though it's werid :(.

func (IndexSetting) String 

func (i IndexSetting) String() string

type Interface 

type Interface interface {
	// AllocateIDs allows you to allocate IDs from the datastore without putting
	// any data. `incomplete` must be a PartialValid Key. If there's no error,
	// a contiguous block of IDs of n length starting at `start` will be reserved
	// indefinitely for the user application code for use in new keys. The
	// appengine automatic ID generator will never automatically assign these IDs
	// for Keys of this type.
	AllocateIDs(incomplete *Key, n int) (start int64, err error)

	// KeyForObj extracts a key from src.
	//
	// It is the same as KeyForObjErr, except that if KeyForObjErr would have
	// returned an error, this method panics. It's safe to use if you know that
	// src statically meets the metadata constraints described by KeyForObjErr.
	KeyForObj(src interface{}) *Key

	// MakeKey is a convenience method for manufacturing a *Key. It should only be
	// used when elems... is known statically (e.g. in the code) to be correct.
	//
	// elems is pairs of (string, string|int|int32|int64) pairs, which correspond
	// to Kind/id pairs. Example:
	//   dstore.MakeKey("Parent", 1, "Child", "id")
	//
	// Would create the key:
	//   <current appID>:<current Namespace>:/Parent,1/Child,id
	//
	// If elems is not parsable (e.g. wrong length, wrong types, etc.) this method
	// will panic.
	MakeKey(elems ...interface{}) *Key

	// NewKey constructs a new key in the current appID/Namespace, using the
	// specified parameters.
	NewKey(kind, stringID string, intID int64, parent *Key) *Key

	// NewKeyToks constructs a new key in the current appID/Namespace, using the
	// specified key tokens.
	NewKeyToks([]KeyTok) *Key

	// KeyForObjErr extracts a key from src.
	//
	// src must be one of:
	//   - *S where S is a struct
	//   - a PropertyLoadSaver
	//
	// It is expected that the struct exposes the following metadata (as retrieved
	// by MetaGetter.GetMeta):
	//   - "key" (type: Key) - The full datastore key to use. Must not be nil.
	//     OR
	//   - "id" (type: int64 or string) - The id of the Key to create
	//   - "kind" (optional, type: string) - The kind of the Key to create. If
	//     blank or not present, KeyForObjErr will extract the name of the src
	//     object's type.
	//   - "parent" (optional, type: Key) - The parent key to use.
	//
	// By default, the metadata will be extracted from the struct and its tagged
	// properties. However, if the struct implements MetaGetterSetter it is
	// wholly responsible for exporting the required fields. A struct that
	// implements GetMeta to make some minor tweaks can evoke the defualt behavior
	// by using GetPLS(s).GetMeta.
	//
	// If a required metadata item is missing or of the wrong type, then this will
	// return an error.
	KeyForObjErr(src interface{}) (*Key, error)

	// RunInTransaction runs f inside of a transaction. See the appengine SDK's
	// documentation for full details on the behavior of transactions in the
	// datastore.
	//
	// Note that the behavior of transactions may change depending on what filters
	// have been installed. It's possible that we'll end up implementing things
	// like nested/buffered transactions as filters.
	RunInTransaction(f func(c context.Context) error, opts *TransactionOptions) error

	// Run executes the given query, and calls `cb` for each successfully
	// retrieved item.
	//
	// cb is a callback function whose signature is
	//   func(obj TYPE[, getCursor CursorCB]) [error]
	//
	// Where TYPE is one of:
	//   - S or *S where S is a struct
	//   - P or *P where *P is a concrete type implementing PropertyLoadSaver
	//   - *Key (implies a keys-only query)
	//
	// If the error is omitted from the signature, this will run until the query
	// returns all its results, or has an error/times out.
	//
	// If error is in the signature, the query will continue as long as the
	// callback returns nil. If it returns `Stop`, the query will stop and Run
	// will return nil. Otherwise, the query will stop and Run will return the
	// user's error.
	//
	// Run may also stop on the first datastore error encountered, which can occur
	// due to flakiness, timeout, etc. If it encounters such an error, it will
	// be returned.
	Run(q *Query, cb interface{}) error

	// Count executes the given query and returns the number of entries which
	// match it.
	Count(q *Query) (int64, error)

	// DecodeCursor converts a string returned by a Cursor into a Cursor instance.
	// It will return an error if the supplied string is not valid, or could not
	// be decoded by the implementation.
	DecodeCursor(string) (Cursor, error)

	// GetAll retrieves all of the Query results into dst.
	//
	// dst must be one of:
	//   - *[]S or *[]*S where S is a struct
	//   - *[]P or *[]*P where *P is a concrete type implementing
	//     PropertyLoadSaver
	//   - *[]*Key implies a keys-only query.
	GetAll(q *Query, dst interface{}) error

	// Does a Get for this key and returns true iff it exists. Will only return
	// an error if it's not ErrNoSuchEntity. This is slightly more efficient
	// than using Get directly, because it uses the underlying RawInterface to
	// avoid some reflection and copies.
	Exists(k *Key) (bool, error)

	// Does a GetMulti for thes keys and returns true iff they exist. Will only
	// return an error if it's not ErrNoSuchEntity. This is slightly more efficient
	// than using Get directly, because it uses the underlying RawInterface to
	// avoid some reflection and copies.
	ExistsMulti(k []*Key) ([]bool, error)

	// Get retrieves a single object from the datastore
	//
	// dst must be one of:
	//   - *S where S is a struct
	//   - *P where *P is a concrete type implementing PropertyLoadSaver
	Get(dst interface{}) error

	// Put inserts a single object into the datastore
	//
	// src must be one of:
	//   - *S where S is a struct
	//   - *P where *P is a concrete type implementing PropertyLoadSaver
	//
	// A *Key will be extracted from src via KeyForObj. If
	// extractedKey.Incomplete() is true, then Put will write the resolved (i.e.
	// automatic datastore-populated) *Key back to src.
	Put(src interface{}) error

	// Delete removes an item from the datastore.
	Delete(key *Key) error

	// GetMulti retrieves items from the datastore.
	//
	// dst must be one of:
	//   - []S or []*S where S is a struct
	//   - []P or []*P where *P is a concrete type implementing PropertyLoadSaver
	//   - []I where I is some interface type. Each element of the slice must
	//     be non-nil, and its underlying type must be either *S or *P.
	GetMulti(dst interface{}) error

	// PutMulti writes items to the datastore.
	//
	// src must be one of:
	//   - []S or []*S where S is a struct
	//   - []P or []*P where *P is a concrete type implementing PropertyLoadSaver
	//   - []I where i is some interface type. Each elemet of the slice must
	//     be non-nil, and its underlying type must be either *S or *P.
	//
	// If items in src resolve to Incomplete keys, PutMulti will write the
	// resolved keys back to the items in src.
	PutMulti(src interface{}) error

	// DeleteMulti removes items from the datastore.
	DeleteMulti(keys []*Key) error

	// Testable returns the Testable interface for the implementation, or nil if
	// there is none.
	Testable() Testable

	// Raw returns the underlying RawInterface. The Interface and RawInterface may
	// be used interchangably; there's no danger of interleaving access to the
	// datastore via the two.
	Raw() RawInterface
}

Interface is the 'user-friendly' interface to access the current filtered datastore service implementation.

Note that in exchange for userfriendliness, this interface ends up doing a lot of reflection.

Methods taking 'interface{}' objects describe what a valid type for that interface are in the comments.

Struct objects passed in will be converted to PropertyLoadSaver interfaces using this package's GetPLS function.

func Get 

func Get(c context.Context) Interface

Get gets the Interface implementation from context.

func GetNoTxn 

func GetNoTxn(c context.Context) Interface

GetNoTxn gets the Interface implementation from context. If there's a currently active transaction, this will return a non-transactional connection to the datastore, otherwise this is the same as GetRaw. Get gets the Interface implementation from context.

type Key 

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

Key is the type used for all datastore operations.

func MakeKey 

func MakeKey(aid, ns string, elems ...interface{}) *Key

MakeKey is a convenience function for manufacturing a *Key. It should only be used when elems... is known statically (e.g. in the code) to be correct.

elems is pairs of (string, string|int|int32|int64) pairs, which correspond to Kind/id pairs. Example: 

MakeKey("aid", "namespace", "Parent", 1, "Child", "id")

Would create the key: 

aid:namespace:/Parent,1/Child,id

If elems is not parsable (e.g. wrong length, wrong types, etc.) this method will panic.

See Interface.MakeKey for a version of this function which automatically provides aid and ns.

func NewKey 

func NewKey(aid, ns, kind, stringID string, intID int64, parent *Key) *Key

NewKey is a wrapper around NewToks which has an interface similar to NewKey in the SDK.

See Interface.NewKey for a version of this function which automatically provides aid and ns.

func NewKeyEncoded 

func NewKeyEncoded(encoded string) (ret *Key, err error)

NewKeyEncoded decodes and returns a *Key

func NewKeyToks 

func NewKeyToks(aid, ns string, toks []KeyTok) *Key

NewKeyToks creates a new Key. It is the Key implementation returned from the various PropertyMap serialization routines, as well as the native key implementation for the in-memory implementation of gae.

See Interface.NewKeyToks for a version of this function which automatically provides aid and ns.

func (*Key) AppID 

func (k *Key) AppID() string

AppID returns the application ID that this Key is for.

func (*Key) Encode 

func (k *Key) Encode() string

Encode encodes the provided key as a base64-encoded protobuf.

This encoding is compatible with the SDK-provided encoding and is agnostic to the underlying implementation of the Key.

It's encoded with the urlsafe base64 table without padding.

func (*Key) Equal 

func (k *Key) Equal(other *Key) (ret bool)

Equal returns true iff the two keys represent identical key values.

func (*Key) EstimateSize 

func (k *Key) EstimateSize() int64

EstimateSize estimates the size of a Key.

It uses https://cloud.google.com/appengine/articles/storage_breakdown?csw=1 as a guide for these values.

func (*Key) GQL 

func (k *Key) GQL() string

GQL returns a correctly formatted Cloud Datastore GQL key literal.

The flavor of GQL that this emits is defined here: 

https://cloud.google.com/datastore/docs/apis/gql/gql_reference

func (*Key) GobDecode 

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

GobDecode allows the Key to be decoded in a Gob struct.

func (*Key) GobEncode 

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

GobEncode allows the Key to be encoded in a Gob struct.

func (*Key) HasAncestor 

func (k *Key) HasAncestor(other *Key) bool

HasAncestor returns true iff other is an ancestor of k (or if other == k).

func (*Key) Incomplete 

func (k *Key) Incomplete() bool

Incomplete returns true iff k doesn't have an id yet.

func (*Key) IntID 

func (k *Key) IntID() int64

IntID returns the IntID of the child KeyTok

func (*Key) Kind 

func (k *Key) Kind() string

Kind returns the Kind of the child KeyTok

func (*Key) LastTok 

func (k *Key) LastTok() KeyTok

LastTok returns the last KeyTok in this Key. Non-nil Keys are always guaranteed to have at least one token.

func (*Key) Less 

func (k *Key) Less(other *Key) bool

Less returns true iff k would sort before other.

func (*Key) MarshalJSON 

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

MarshalJSON allows this key to be automatically marshaled by encoding/json.

func (*Key) Namespace 

func (k *Key) Namespace() string

Namespace returns the namespace that this Key is for.

func (*Key) Parent 

func (k *Key) Parent() *Key

Parent returns the parent Key of this *Key, or nil. The parent will always have the concrete type of *Key.

func (*Key) PartialValid 

func (k *Key) PartialValid(aid, ns string) bool

PartialValid returns true iff this key is suitable for use in a Put operation. This is the same as Valid(k, false, ...), but also allowing k to be Incomplete().

func (*Key) Root 

func (k *Key) Root() *Key

Root returns the entity root for the given key.

func (*Key) Split 

func (k *Key) Split() (appID, namespace string, toks []KeyTok)

Split componentizes the key into pieces (AppID, Namespace and tokens)

Each token represents one piece of they key's 'path'.

toks is guaranteed to be empty if and only if k is nil. If k is non-nil then it contains at least one token.

func (*Key) String 

func (k *Key) String() string

String returns a human-readable representation of the key in the form of 

AID:NS:/Kind,id/Kind,id/...

func (*Key) StringID 

func (k *Key) StringID() string

StringID returns the StringID of the child KeyTok

func (*Key) UnmarshalJSON 

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

UnmarshalJSON allows this key to be automatically unmarshaled by encoding/json.

func (*Key) Valid 

func (k *Key) Valid(allowSpecial bool, aid, ns string) bool

Valid determines if a key is valid, according to a couple rules:

  • k is not nil
  • every token of k:
  • (if !allowSpecial) token's kind doesn't start with '__'
  • token's kind and appid are non-blank
  • token is not incomplete
  • all tokens have the same namespace and appid

type KeyTok 

type KeyTok struct {
	Kind     string
	IntID    int64
	StringID string
}

KeyTok is a single token from a multi-part Key.

func (KeyTok) ID 

func (k KeyTok) ID() Property

ID returns the 'active' id as a Property (either the StringID or the IntID).

func (KeyTok) Incomplete 

func (k KeyTok) Incomplete() bool

Incomplete returns true iff this token doesn't define either a StringID or an IntID.

func (KeyTok) Less 

func (k KeyTok) Less(other KeyTok) bool

Less returns true iff k would sort before other.

func (KeyTok) Special 

func (k KeyTok) Special() bool

Special returns true iff this token begins and ends with "__"

type MetaGetter 

type MetaGetter interface {
	// GetMeta will get information about the field which has the struct tag in
	// the form of `gae:"$<key>[,<default>]?"`.
	//
	// It returns the value, if any, and true iff the value was retrieved.
	//
	// Supported metadata types are:
	//   int64  - may have default (ascii encoded base-10)
	//   string - may have default
	//   Toggle - MUST have default ("true" or "false")
	//   *Key    - NO default allowed
	//
	// Struct fields of type Toggle (which is an Auto/On/Off) require you to
	// specify a value of 'true' or 'false' for the default value of the struct
	// tag, and GetMeta will return the combined value as a regular boolean true
	// or false value.
	// Example:
	//   type MyStruct struct {
	//     CoolField int64 `gae:"$id,1"`
	//   }
	//   val, err := helper.GetPLS(&MyStruct{}).GetMeta("id")
	//   // val == 1
	//   // err == nil
	//
	//   val, err := helper.GetPLS(&MyStruct{10}).GetMeta("id")
	//   // val == 10
	//   // err == nil
	//
	//   type MyStruct struct {
	//     TFlag Toggle `gae:"$flag1,true"`  // defaults to true
	//     FFlag Toggle `gae:"$flag2,false"` // defaults to false
	//     // BadFlag  Toggle `gae:"$flag3"` // ILLEGAL
	//   }
	GetMeta(key string) (interface{}, bool)
}

MetaGetter is a subinterface of PropertyLoadSaver, but is also used to abstract the meta argument for RawInterface.GetMulti.

type MetaGetterSetter 

type MetaGetterSetter interface {
	MetaGetter

	// GetAllMeta returns a PropertyMap with all of the metadata in this
	// MetaGetterSetter. If a metadata field has an error during serialization,
	// it is skipped.
	//
	// If a *struct is implementing this, then it only needs to return the
	// metadata fields which would be returned by its GetMeta implementation, and
	// the `GetPLS` implementation will add any statically-defined metadata
	// fields. So if GetMeta provides $id, but there's a simple tagged field for
	// $kind, this method is only expected to return a PropertyMap with "$id".
	GetAllMeta() PropertyMap

	// SetMeta allows you to set the current value of the meta-keyed field.
	// It returns true iff the field was set.
	SetMeta(key string, val interface{}) bool
}

MetaGetterSetter is the subset of PropertyLoadSaver which pertains to getting and saving metadata.

A *struct may implement this interface to provide metadata which is supplimental to the variety described by GetPLS. For example, this could be used to implement a parsed-out $kind or $id.

type MultiMetaGetter 

type MultiMetaGetter []MetaGetter

MultiMetaGetter is a carrier for metadata, used with RawInterface.GetMulti

It's OK to default-construct this. GetMeta will just return (nil, ErrMetaFieldUnset) for every index.

func NewMultiMetaGetter 

func NewMultiMetaGetter(data []PropertyMap) MultiMetaGetter

NewMultiMetaGetter returns a new MultiMetaGetter object. data may be nil.

func (MultiMetaGetter) GetMeta 

func (m MultiMetaGetter) GetMeta(idx int, key string) (interface{}, bool)

GetMeta is like PropertyLoadSaver.GetMeta, but it also takes an index indicating which slot you want metadata for. If idx isn't there, this returns (nil, ErrMetaFieldUnset).

func (MultiMetaGetter) GetSingle 

func (m MultiMetaGetter) GetSingle(idx int) MetaGetter

GetSingle gets a single MetaGetter at the specified index.

type Property 

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

Property is a value plus an indicator of whether the value should be indexed. Name and Multiple are stored in the PropertyMap object.

func MkProperty 

func MkProperty(val interface{}) Property

MkProperty makes a new indexed* Property and returns it. If val is an invalid value, this panics (so don't do it). If you want to handle the error normally, use SetValue(..., ShouldIndex) instead.

*indexed if val is not an unindexable type like []byte.

func MkPropertyNI 

func MkPropertyNI(val interface{}) Property

MkPropertyNI makes a new Property (with noindex set to true), and returns it. If val is an invalid value, this panics (so don't do it). If you want to handle the error normally, use SetValue(..., NoIndex) instead.

func (*Property) Equal 

func (p *Property) Equal(other *Property) bool

Equal returns true iff p and other have identical index representations.

This uses datastore's index rules for sorting (e.g. []byte("hello") == "hello")

func (*Property) EstimateSize 

func (p *Property) EstimateSize() int64

EstimateSize estimates the amount of space that this Property would consume if it were committed as part of an entity in the real production datastore.

It uses https://cloud.google.com/appengine/articles/storage_breakdown?csw=1 as a guide for these values.

func (Property) ForIndex 

func (p Property) ForIndex() Property

ForIndex gets a new Property with its value and type converted as if it were being stored in a datastore index. See the doc on PropertyType for more info.

func (*Property) GQL 

func (p *Property) GQL() string

GQL returns a correctly formatted Cloud Datastore GQL literal which is valid for a comparison value in the `WHERE` clause.

The flavor of GQL that this emits is defined here: 

https://cloud.google.com/datastore/docs/apis/gql/gql_reference

NOTE: GeoPoint values are emitted with speculated future syntax. There is currently no syntax for literal GeoPoint values.

func (*Property) IndexSetting 

func (p *Property) IndexSetting() IndexSetting

IndexSetting says whether or not the datastore should create indicies for this value.

func (*Property) Less 

func (p *Property) Less(other *Property) bool

Less returns true iff p would sort before other.

This uses datastore's index rules for sorting (e.g. []byte("hello") == "hello")

func (*Property) Project 

func (p *Property) Project(to PropertyType) (interface{}, error)

Project can be used to project a Property retrieved from a Projection query into a different datatype. For example, if you have a PTInt property, you could Project(PTTime) to convert it to a time.Time. The following conversions are supported: 

PTXXX <-> PTXXX (i.e. identity)
PTInt <-> PTTime
PTString <-> PTBlobKey
PTString <-> PTBytes
PTNull <-> Anything

func (*Property) SetValue 

func (p *Property) SetValue(value interface{}, is IndexSetting) (err error)

SetValue sets the Value field of a Property, and ensures that its value conforms to the permissible types. That way, you're guaranteed that if you have a Property, its value is valid.

value is the property value. The valid types are:

  • int64
  • time.Time
  • bool
  • string (only the first 1500 bytes is indexable)
  • []byte (only the first 1500 bytes is indexable)
  • blobstore.Key (only the first 1500 bytes is indexable)
  • float64
  • *Key
  • GeoPoint

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

func (*Property) Type 

func (p *Property) Type() PropertyType

Type is the PT* type of the data contained in Value().

func (*Property) Value 

func (p *Property) Value() interface{}

Value returns the current value held by this property. It's guaranteed to be a valid value type (i.e. `p.SetValue(p.Value(), true)` will never return an error).

type PropertyConverter 

type PropertyConverter interface {
	ToProperty() (Property, error)
	FromProperty(Property) error
}

PropertyConverter may be implemented by the pointer-to a struct field which is serialized by the struct PropertyLoadSaver from GetPLS. Its ToProperty will be called on save, and it's FromProperty will be called on load (from datastore). The method may do arbitrary computation, and if it encounters an error, may return it. This error will be a fatal error (as defined by PropertyLoadSaver) for the struct conversion.

Example: 

type Complex complex
func (c *Complex) ToProperty() (ret Property, err error) {
  // something like:
  err = ret.SetValue(fmt.Sprint(*c), true)
  return
}
func (c *Complex) FromProperty(p Property) (err error) {
  ... load *c from p ...
}

type MyStruct struct {
  Complexity []Complex // acts like []complex, but can be serialized to DS
}

type PropertyLoadSaver 

type PropertyLoadSaver interface {
	// Load takes the values from the given map and attempts to save them into
	// the underlying object (usually a struct or a PropertyMap). If a fatal
	// error occurs, it's returned via error. If non-fatal conversion errors
	// occur, error will be a MultiError containing one or more ErrFieldMismatch
	// objects.
	Load(PropertyMap) error

	// Save returns the current property as a PropertyMap. if withMeta is true,
	// then the PropertyMap contains all the metadata (e.g. '$meta' fields)
	// which was held by this PropertyLoadSaver.
	Save(withMeta bool) (PropertyMap, error)
}

PropertyLoadSaver may be implemented by a user type, and Interface will use this interface to serialize the type instead of trying to automatically create a serialization codec for it with helper.GetPLS.

type PropertyMap 

type PropertyMap map[string][]Property

PropertyMap represents the contents of a datastore entity in a generic way. It maps from property name to a list of property values which correspond to that property name. It is the spiritual successor to PropertyList from the original SDK.

PropertyMap may contain "meta" values, which are keyed with a '$' prefix. Technically the datastore allows arbitrary property names, but all of the SDKs go out of their way to try to make all property names valid programming language tokens. Special values must correspond to a single Property... corresponding to 0 is equivalent to unset, and corresponding to >1 is an error. So: 

{
  "$id": {MkProperty(1)}, // GetProperty("id") -> 1, nil
  "$foo": {}, // GetProperty("foo") -> nil, ErrMetaFieldUnset
  // GetProperty("bar") -> nil, ErrMetaFieldUnset
  "$meep": {
    MkProperty("hi"),
    MkProperty("there")}, // GetProperty("meep") -> nil, error!
}

Additionally, Save returns a copy of the map with the meta keys omitted (e.g. these keys are not going to be serialized to the datastore).

func (PropertyMap) EstimateSize 

func (pm PropertyMap) EstimateSize() int64

EstimateSize estimates the size that it would take to encode this PropertyMap in the production Appengine datastore. The calculation excludes metadata fields in the map.

It uses https://cloud.google.com/appengine/articles/storage_breakdown?csw=1 as a guide for sizes.

func (PropertyMap) GetAllMeta 

func (pm PropertyMap) GetAllMeta() PropertyMap

GetAllMeta implements PropertyLoadSaver.GetAllMeta.

func (PropertyMap) GetMeta 

func (pm PropertyMap) GetMeta(key string) (interface{}, bool)

GetMeta implements PropertyLoadSaver.GetMeta, and returns the current value associated with the metadata key.

func (PropertyMap) Load 

func (pm PropertyMap) Load(props PropertyMap) error

Load implements PropertyLoadSaver.Load

func (PropertyMap) Problem 

func (pm PropertyMap) Problem() error

Problem implements PropertyLoadSaver.Problem. It ALWAYS returns nil.

func (PropertyMap) Save 

func (pm PropertyMap) Save(withMeta bool) (PropertyMap, error)

Save implements PropertyLoadSaver.Save by returning a copy of the current map data.

func (PropertyMap) SetMeta 

func (pm PropertyMap) SetMeta(key string, val interface{}) bool

SetMeta implements PropertyLoadSaver.SetMeta. It will only return an error if `val` has an invalid type (e.g. not one supported by Property).

type PropertySlice 

type PropertySlice []Property

PropertySlice is a slice of Properties. It implements sort.Interface.

func (PropertySlice) Len 

func (s PropertySlice) Len() int

func (PropertySlice) Less 

func (s PropertySlice) Less(i, j int) bool

func (PropertySlice) Swap 

func (s PropertySlice) Swap(i, j int)

type PropertyType 

type PropertyType byte

PropertyType is a single-byte representation of the type of data contained in a Property. The specific values of this type information are chosen so that the types sort according to the order of types as sorted by the datastore.

Note that indexes may only contain values of the following types: 

PTNull
PTInt
PTBool
PTFloat
PTString
PTGeoPoint
PTKey

The biggest impact of this is that if you do a Projection query, you'll only get back Properties with the above types (e.g. if you store a PTTime value, then Project on it, you'll get back a PTInt value). For convenience, Property has a Project(PropertyType) method which will side-cast to your intended type. If you project into a structure with the high-level Interface implementation, or use StructPLS, this conversion will be done for you automatically, using the type of the destination field to cast. 

const (
	// PTNull represents the 'nil' value. This is only directly visible when
	// reading/writing a PropertyMap. If a PTNull value is loaded into a struct
	// field, the field will be initialized with its zero value. If a struct with
	// a zero value is saved from a struct, it will still retain the field's type,
	// not the 'nil' type. This is in contrast to other GAE languages such as
	// python where 'None' is a distinct value than the 'zero' value (e.g. a
	// StringProperty can have the value "" OR None).
	//
	// PTNull is a Projection-query type
	PTNull PropertyType = iota

	// PTInt is always an int64.
	//
	// This is a Projection-query type, and may be projected to PTTime.
	PTInt
	PTTime

	// PTBool represents true or false
	//
	// This is a Projection-query type.
	PTBool

	// PTBytes represents []byte
	PTBytes

	// PTString is used to represent all strings (text).
	//
	// PTString is a Projection-query type and may be projected to PTBytes or
	// PTBlobKey.
	PTString

	// PTFloat is always a float64.
	//
	// This is a Projection-query type.
	PTFloat

	// PTGeoPoint is a Projection-query type.
	PTGeoPoint

	// PTKey represents a *Key object.
	//
	// PTKey is a Projection-query type.
	PTKey

	// PTBlobKey represents a blobstore.Key
	PTBlobKey

	// PTUnknown is a placeholder value which should never show up in reality.
	//
	// NOTE: THIS MUST BE LAST VALUE FOR THE init() ASSERTION BELOW TO WORK.
	PTUnknown
)

These constants are in the order described by 

https://cloud.google.com/appengine/docs/go/datastore/entities#Go_Value_type_ordering

with a slight divergence for the Int/Time split.

NOTE: this enum can only occupy 7 bits, because we use the high bit to encode indexed/non-indexed, and we additionally require that all valid values and all INVERTED valid values must never equal 0xFF or 0x00. The reason for this constraint is that we must always be able to create a byte that sorts before and after it.

See "./serialize".WriteProperty and "impl/memory".increment for more info.

func PropertyTypeOf 

func PropertyTypeOf(v interface{}, checkValid bool) (PropertyType, error)

PropertyTypeOf returns the PT* type of the given Property-compatible value v. If checkValid is true, this method will also ensure that time.Time and GeoPoint have valid values.

func (PropertyType) String 

func (i PropertyType) String() string

type PutMultiCB 

type PutMultiCB func(key *Key, err error) error

PutMultiCB is the callback signature provided to RawInterface.PutMulti

  • key is the new key for the entity (if the original was incomplete)
  • It may be nil if some of the keys/vals to the PutMulti were bad, since all keys are validated before the RPC occurs!
  • err is an error associated with putting this entity.

type Query 

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

Query is a builder-object for building a datastore query. It may represent an invalid query, but the error will only be observable when you call Finalize.

func NewQuery 

func NewQuery(kind string) *Query

NewQuery returns a new Query for the given kind. If kind may be empty to begin a kindless query.

func (*Query) Ancestor 

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

Ancestor sets the ancestor filter for this query.

If ancestor is nil, then this removes the Ancestor restriction from the query.

func (*Query) ClearFilters 

func (q *Query) ClearFilters() *Query

ClearFilters clears all equality and inequality filters from the Query. It does not clear the Ancestor filter if one is defined.

func (*Query) ClearOrder 

func (q *Query) ClearOrder() *Query

ClearOrder removes all orders from this Query.

func (*Query) ClearProject 

func (q *Query) ClearProject() *Query

ClearProject removes all projected fields from this Query.

func (*Query) Distinct 

func (q *Query) Distinct(on bool) *Query

Distinct makes a projection query only return distinct values. This has no effect on non-projection queries.

func (*Query) End 

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

End sets the ending cursor. The cursor is implementation-defined by the particular 'impl' you have installed.

func (*Query) Eq 

func (q *Query) Eq(field string, values ...interface{}) *Query

Eq adds one or more equality restrictions to the query.

Equality filters interact with multiply-defined properties by ensuring that the given field has /at least one/ value which is equal to the specified constraint.

So a query with `.Eq("thing", 1, 2)` will only return entities where the field "thing" is multiply defined and contains both a value of 1 and a value of 2.

`Eq("thing", 1).Eq("thing", 2)` and `.Eq("thing", 1, 2)` have identical meaning.

func (*Query) EventualConsistency 

func (q *Query) EventualConsistency(on bool) *Query

EventualConsistency changes the EventualConsistency setting for this query.

It only has an effect on Ancestor queries and is otherwise ignored.

func (*Query) Finalize 

func (q *Query) Finalize() (*FinalizedQuery, error)

Finalize converts this Query to a FinalizedQuery. If the Query has any inconsistencies or violates any of the query rules, that will be returned here.

func (*Query) Gt 

func (q *Query) Gt(field string, value interface{}) *Query

Gt imposes a 'greater-than' inequality restriction on the Query.

Inequality filters interact with multiply-defined properties by ensuring that the given field has /exactly one/ value which matches /all/ of the inequality constraints.

So a query with `.Gt("thing", 5).Lt("thing", 10)` will only return entities where the field "thing" has a single value where `5 < val < 10`.

func (*Query) Gte 

func (q *Query) Gte(field string, value interface{}) *Query

Gte imposes a 'greater-than-or-equal' inequality restriction on the Query.

Inequality filters interact with multiply-defined properties by ensuring that the given field has /exactly one/ value which matches /all/ of the inequality constraints.

So a query with `.Gt("thing", 5).Lt("thing", 10)` will only return entities where the field "thing" has a single value where `5 < val < 10`.

func (*Query) KeysOnly 

func (q *Query) KeysOnly(on bool) *Query

KeysOnly makes this into a query which only returns keys (but doesn't fetch values). It's incompatible with projection queries.

func (*Query) Kind 

func (q *Query) Kind(kind string) *Query

Kind alters the kind of this query.

func (*Query) Limit 

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

Limit sets the limit (max items to return) for this query. If limit < 0, this removes the limit from the query entirely.

func (*Query) Lt 

func (q *Query) Lt(field string, value interface{}) *Query

Lt imposes a 'less-than' inequality restriction on the Query.

Inequality filters interact with multiply-defined properties by ensuring that the given field has /exactly one/ value which matches /all/ of the inequality constraints.

So a query with `.Gt("thing", 5).Lt("thing", 10)` will only return entities where the field "thing" has a single value where `5 < val < 10`.

func (*Query) Lte 

func (q *Query) Lte(field string, value interface{}) *Query

Lte imposes a 'less-than-or-equal' inequality restriction on the Query.

Inequality filters interact with multiply-defined properties by ensuring that the given field has /exactly one/ value which matches /all/ of the inequality constraints.

So a query with `.Gt("thing", 5).Lt("thing", 10)` will only return entities where the field "thing" has a single value where `5 < val < 10`.

func (*Query) Offset 

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

Offset sets the offset (number of items to skip) for this query. If offset < 0, this removes the offset from the query entirely.

func (*Query) Order 

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

Order sets one or more orders for this query.

func (*Query) Project 

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

Project lists one or more field names to project.

func (*Query) Start 

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

Start sets a starting cursor. The cursor is implementation-defined by the particular 'impl' you have installed.

func (*Query) String 

func (q *Query) String() string

type RawFactory 

type RawFactory func(c context.Context, wantTxn bool) RawInterface

RawFactory is the function signature for factory methods compatible with SetRawFactory. wantTxn is true if the Factory should return the datastore in the current transaction, and false if the Factory should return the non-transactional (root) datastore.

type RawFilter 

type RawFilter func(context.Context, RawInterface) RawInterface

RawFilter is the function signature for a RawFilter implementation. It gets the current RDS implementation, and returns a new RDS implementation backed by the one passed in.

type RawInterface 

type RawInterface interface {
	// AllocateIDs allows you to allocate IDs from the datastore without putting
	// any data. `incomplete` must be a PartialValid Key. If there's no error,
	// a contiguous block of IDs of n length starting at `start` will be reserved
	// indefinitely for the user application code for use in new keys. The
	// appengine automatic ID generator will never automatically assign these IDs
	// for Keys of this type.
	AllocateIDs(incomplete *Key, n int) (start int64, err error)

	// RunInTransaction runs f in a transaction.
	//
	// opts may be nil.
	//
	// NOTE: Implementations and filters are guaranteed that:
	//   - f is not nil
	RunInTransaction(f func(c context.Context) error, opts *TransactionOptions) error

	// DecodeCursor converts a string returned by a Cursor into a Cursor instance.
	// It will return an error if the supplied string is not valid, or could not
	// be decoded by the implementation.
	DecodeCursor(s string) (Cursor, error)

	// Run executes the given query, and calls `cb` for each successfully item.
	//
	// NOTE: Implementations and filters are guaranteed that:
	//   - query is not nil
	//   - cb is not nil
	Run(q *FinalizedQuery, cb RawRunCB) error

	// Count executes the given query and returns the number of entries which
	// match it.
	Count(q *FinalizedQuery) (int64, error)

	// GetMulti retrieves items from the datastore.
	//
	// Callback execues once per key, in the order of keys. Callback may not
	// execute at all if there's a server error. If callback is nil, this
	// method does nothing.
	//
	// meta is used to propagate metadata from higher levels.
	//
	// NOTE: Implementations and filters are guaranteed that:
	//   - len(keys) > 0
	//   - all keys are Valid, !Incomplete, and in the current namespace
	//   - cb is not nil
	GetMulti(keys []*Key, meta MultiMetaGetter, cb GetMultiCB) error

	// PutMulti writes items to the datastore.
	//
	// Callback execues once per key/value pair, in the passed-in order. Callback
	// may not execute at all if there was a server error.
	//
	// NOTE: Implementations and filters are guaranteed that:
	//   - len(keys) > 0
	//   - len(keys) == len(vals)
	//   - all keys are Valid and in the current namespace
	//   - cb is not nil
	PutMulti(keys []*Key, vals []PropertyMap, cb PutMultiCB) error

	// DeleteMulti removes items from the datastore.
	//
	// Callback execues once per key, in the order of keys. Callback may not
	// execute at all if there's a server error.
	//
	// NOTE: Implementations and filters are guaranteed that
	//   - len(keys) > 0
	//   - all keys are Valid, !Incomplete, and in the current namespace
	//   - none keys of the keys are 'special' (use a kind prefixed with '__')
	//   - cb is not nil
	DeleteMulti(keys []*Key, cb DeleteMultiCB) error

	// Testable returns the Testable interface for the implementation, or nil if
	// there is none.
	Testable() Testable
}

RawInterface implements the datastore functionality without any of the fancy reflection stuff. This is so that Filters can avoid doing lots of redundant reflection work. See datastore.Interface for a more user-friendly interface.

func GetRaw 

func GetRaw(c context.Context) RawInterface

GetRaw gets the RawInterface implementation from context.

func GetRawNoTxn 

func GetRawNoTxn(c context.Context) RawInterface

GetRawNoTxn gets the RawInterface implementation from context. If there's a currently active transaction, this will return a non-transactional connection to the datastore, otherwise this is the same as GetRaw.

type RawRunCB 

type RawRunCB func(key *Key, val PropertyMap, getCursor CursorCB) error

RawRunCB is the callback signature provided to RawInterface.Run

  • key is the Key of the entity
  • val is the data of the entity (or nil, if the query was keys-only)

Return nil to continue iterating through the query results, or an error to stop. If you return the error `Stop`, then Run will stop the query and return nil.

type Testable 

type Testable interface {
	// AddIndex adds the provided index.
	// Blocks all datastore access while the index is built.
	// Panics if any of the IndexDefinition objects are not Compound()
	AddIndexes(...*IndexDefinition)

	// TakeIndexSnapshot allows you to take a snapshot of the current index
	// tables, which can be used later with SetIndexSnapshot.
	TakeIndexSnapshot() TestingSnapshot

	// SetIndexSnapshot allows you to set the state of the current index tables.
	// Note that this would allow you to create 'non-lienarities' in the precieved
	// index results (e.g. you could force the indexes to go back in time).
	//
	// SetIndexSnapshot takes a reference of the given TestingSnapshot. You're
	// still responsible for closing the snapshot after this call.
	SetIndexSnapshot(TestingSnapshot)

	// CatchupIndexes catches the index table up to the current state of the
	// datastore. This is equivalent to:
	//   idxSnap := TakeIndexSnapshot()
	//   SetIndexSnapshot(idxSnap)
	//
	// But depending on the implementation it may implemented with an atomic
	// operation.
	CatchupIndexes()

	// SetTransactionRetryCount set how many times RunInTransaction will retry
	// transaction body pretending transaction conflicts happens. 0 (default)
	// means commit succeeds on the first attempt (no retries).
	SetTransactionRetryCount(int)

	// Consistent controls the eventual consistency behavior of the testing
	// implementation. If it is called with true, then this datastore
	// implementation will be always-consistent, instead of eventually-consistent.
	//
	// By default the datastore is eventually consistent, and you must call
	// CatchupIndexes or use Take/SetIndexSnapshot to manipulate the index state.
	Consistent(always bool)

	// AutoIndex controls the index creation behavior. If it is set to true, then
	// any time the datastore encounters a missing index, it will silently create
	// one and allow the query to succeed. If it's false, then the query will
	// return an error describing the index which could be added with AddIndexes.
	//
	// By default this is false.
	AutoIndex(bool)

	// DisableSpecialEntities turns off maintenance of special __entity_group__
	// type entities. By default this mainenance is enabled, but it can be
	// disabled by calling this with true.
	//
	// If it's true:
	//   - AllocateIDs returns an error.
	//   - Put'ing incomplete Keys returns an error.
	//   - Transactions are disabled and will return an error.
	//
	// This is mainly only useful when using an embedded in-memory datastore as
	// a fully-consistent 'datastore-lite'. In particular, this is useful for the
	// txnBuf filter which uses it to fulfil queries in a buffered transaction,
	// but never wants the in-memory versions of these entities to bleed through
	// to the user code.
	DisableSpecialEntities(bool)
}

Testable is the testable interface for fake datastore implementations.

type TestingSnapshot 

type TestingSnapshot interface {
	ImATestingSnapshot()
}

TestingSnapshot is an opaque implementation-defined snapshot type.

type Toggle 

type Toggle byte

Toggle is a tri-state boolean (Auto/True/False), which allows structs to control boolean flags for metadata in a non-ambiguous way. 

const (
	Auto Toggle = iota
	On
	Off
)

These are the allowed values for Toggle. Any other values are invalid.

func (Toggle) String 

func (i Toggle) String() string

type TransactionOptions 

type TransactionOptions struct {
	// XG is whether the transaction can cross multiple entity groups. In
	// comparison, a single group transaction is one where all datastore keys
	// used have the same root key. Note that cross group transactions do not
	// have the same behavior as single group transactions. In particular, it
	// is much more likely to see partially applied transactions in different
	// entity groups, in global queries.
	// It is valid to set XG to true even if the transaction is within a
	// single entity group.
	XG bool
	// Attempts controls the number of retries to perform when commits fail
	// due to a conflicting transaction. If omitted, it defaults to 3.
	Attempts int
}

TransactionOptions are the options for running a transaction.

Source Files

View all Source files

Directories

Path Synopsis
internal
protos/datastore
Package datastore is a generated protocol buffer package.
 Package datastore is a generated protocol buffer package.
Package serialize provides methods for reading and writing concatenable, bytewise-sortable forms of the datatypes defined in the datastore package.
 Package serialize provides methods for reading and writing concatenable, bytewise-sortable forms of the datatypes defined in the datastore package.

Jump to

Keyboard shortcuts

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