Documentation ¶
Index ¶
- Variables
- func AddRawFilters(c context.Context, filts ...RawFilter) context.Context
- func GetMetaDefault(getter MetaGetter, key string, dflt interface{}) interface{}
- func GetPLS(obj interface{}) interface{ ... }
- func SetRaw(c context.Context, rds RawInterface) context.Context
- func SetRawFactory(c context.Context, rdsf RawFactory) context.Context
- func UpconvertUnderlyingType(o interface{}) interface{}
- type Cursor
- type CursorCB
- type DeleteMultiCB
- type ErrFieldMismatch
- type FinalizedQuery
- func (q *FinalizedQuery) Ancestor() *Key
- func (q *FinalizedQuery) Bounds() (start, end Cursor)
- func (q *FinalizedQuery) Distinct() bool
- func (q *FinalizedQuery) EqFilters() map[string]PropertySlice
- func (q *FinalizedQuery) EventuallyConsistent() bool
- func (q *FinalizedQuery) GQL() string
- func (q *FinalizedQuery) IneqFilterHigh() (field, op string, val Property)
- func (q *FinalizedQuery) IneqFilterLow() (field, op string, val Property)
- func (q *FinalizedQuery) IneqFilterProp() string
- func (q *FinalizedQuery) KeysOnly() bool
- func (q *FinalizedQuery) Kind() string
- func (q *FinalizedQuery) Limit() (int32, bool)
- func (q *FinalizedQuery) Offset() (int32, bool)
- func (q *FinalizedQuery) Orders() []IndexColumn
- func (q *FinalizedQuery) Original() *Query
- func (q *FinalizedQuery) Project() []string
- func (q *FinalizedQuery) String() string
- func (q *FinalizedQuery) Valid(aid, ns string) error
- type GeoPoint
- type GetMultiCB
- type IndexColumn
- type IndexDefinition
- func (id *IndexDefinition) Builtin() bool
- func (id *IndexDefinition) Compound() bool
- func (id *IndexDefinition) Equal(o *IndexDefinition) bool
- func (id *IndexDefinition) Flip() *IndexDefinition
- func (id *IndexDefinition) GetFullSortOrder() []IndexColumn
- func (id *IndexDefinition) Less(o *IndexDefinition) bool
- func (id *IndexDefinition) Normalize() *IndexDefinition
- func (id *IndexDefinition) PrepForIdxTable() *IndexDefinition
- func (id *IndexDefinition) String() string
- func (id *IndexDefinition) YAMLString() (string, error)
- type IndexSetting
- type Interface
- type Key
- func (k *Key) AppID() string
- func (k *Key) Encode() string
- func (k *Key) Equal(other *Key) (ret bool)
- func (k *Key) EstimateSize() int64
- func (k *Key) GQL() string
- func (k *Key) GobDecode(buf []byte) error
- func (k *Key) GobEncode() ([]byte, error)
- func (k *Key) HasAncestor(other *Key) bool
- func (k *Key) Incomplete() bool
- func (k *Key) IntID() int64
- func (k *Key) Kind() string
- func (k *Key) LastTok() KeyTok
- func (k *Key) Less(other *Key) bool
- func (k *Key) MarshalJSON() ([]byte, error)
- func (k *Key) Namespace() string
- func (k *Key) Parent() *Key
- func (k *Key) PartialValid(aid, ns string) bool
- func (k *Key) Root() *Key
- func (k *Key) Split() (appID, namespace string, toks []KeyTok)
- func (k *Key) String() string
- func (k *Key) StringID() string
- func (k *Key) UnmarshalJSON(buf []byte) error
- func (k *Key) Valid(allowSpecial bool, aid, ns string) bool
- type KeyTok
- type MetaGetter
- type MetaGetterSetter
- type MultiMetaGetter
- type Property
- func (p *Property) Equal(other *Property) bool
- func (p *Property) EstimateSize() int64
- func (p Property) ForIndex() Property
- func (p *Property) GQL() string
- func (p *Property) IndexSetting() IndexSetting
- func (p *Property) Less(other *Property) bool
- func (p *Property) Project(to PropertyType) (interface{}, error)
- func (p *Property) SetValue(value interface{}, is IndexSetting) (err error)
- func (p *Property) Type() PropertyType
- func (p *Property) Value() interface{}
- type PropertyConverter
- type PropertyLoadSaver
- type PropertyMap
- func (pm PropertyMap) EstimateSize() int64
- func (pm PropertyMap) GetAllMeta() PropertyMap
- func (pm PropertyMap) GetMeta(key string) (interface{}, bool)
- func (pm PropertyMap) Load(props PropertyMap) error
- func (pm PropertyMap) Problem() error
- func (pm PropertyMap) Save(withMeta bool) (PropertyMap, error)
- func (pm PropertyMap) SetMeta(key string, val interface{}) bool
- type PropertySlice
- type PropertyType
- type PutMultiCB
- type Query
- func (q *Query) Ancestor(ancestor *Key) *Query
- func (q *Query) ClearFilters() *Query
- func (q *Query) ClearOrder() *Query
- func (q *Query) ClearProject() *Query
- func (q *Query) Distinct(on bool) *Query
- func (q *Query) End(c Cursor) *Query
- func (q *Query) Eq(field string, values ...interface{}) *Query
- func (q *Query) EventualConsistency(on bool) *Query
- func (q *Query) Finalize() (*FinalizedQuery, error)
- func (q *Query) Gt(field string, value interface{}) *Query
- func (q *Query) Gte(field string, value interface{}) *Query
- func (q *Query) KeysOnly(on bool) *Query
- func (q *Query) Kind(kind string) *Query
- func (q *Query) Limit(limit int32) *Query
- func (q *Query) Lt(field string, value interface{}) *Query
- func (q *Query) Lte(field string, value interface{}) *Query
- func (q *Query) Offset(offset int32) *Query
- func (q *Query) Order(fieldNames ...string) *Query
- func (q *Query) Project(fieldNames ...string) *Query
- func (q *Query) Start(c Cursor) *Query
- func (q *Query) String() string
- type RawFactory
- type RawFilter
- type RawInterface
- type RawRunCB
- type Testable
- type TestingSnapshot
- type Toggle
- type TransactionOptions
Constants ¶
This section is empty.
Variables ¶
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.
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 ¶
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 CursorCB ¶
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 ¶
DeleteMultiCB is the callback signature provided to RawInterface.DeleteMulti
- err is an error associated with deleting this entity.
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 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.
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 ¶
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.
type Key ¶
type Key struct {
// contains filtered or unexported fields
}
Key is the type used for all datastore operations.
func MakeKey ¶
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 ¶
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 ¶
NewKeyEncoded decodes and returns a *Key
func NewKeyToks ¶
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) Encode ¶
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) EstimateSize ¶
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 ¶
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) HasAncestor ¶
HasAncestor returns true iff other is an ancestor of k (or if other == k).
func (*Key) Incomplete ¶
Incomplete returns true iff k doesn't have an id yet.
func (*Key) LastTok ¶
LastTok returns the last KeyTok in this Key. Non-nil Keys are always guaranteed to have at least one token.
func (*Key) MarshalJSON ¶
MarshalJSON allows this key to be automatically marshaled by encoding/json.
func (*Key) Parent ¶
Parent returns the parent Key of this *Key, or nil. The parent will always have the concrete type of *Key.
func (*Key) PartialValid ¶
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) Split ¶
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 ¶
String returns a human-readable representation of the key in the form of
AID:NS:/Kind,id/Kind,id/...
func (*Key) UnmarshalJSON ¶
UnmarshalJSON allows this key to be automatically unmarshaled by encoding/json.
type KeyTok ¶
KeyTok is a single token from a multi-part Key.
func (KeyTok) Incomplete ¶
Incomplete returns true iff this token doesn't define either a StringID or an IntID.
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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().
type PropertyConverter ¶
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 ¶
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 ¶
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 ¶
NewQuery returns a new Query for the given kind. If kind may be empty to begin a kindless query.
func (*Query) Ancestor ¶
Ancestor sets the ancestor filter for this query.
If ancestor is nil, then this removes the Ancestor restriction from the query.
func (*Query) ClearFilters ¶
ClearFilters clears all equality and inequality filters from the Query. It does not clear the Ancestor filter if one is defined.
func (*Query) ClearOrder ¶
ClearOrder removes all orders from this Query.
func (*Query) ClearProject ¶
ClearProject removes all projected fields from this Query.
func (*Query) Distinct ¶
Distinct makes a projection query only return distinct values. This has no effect on non-projection queries.
func (*Query) End ¶
End sets the ending cursor. The cursor is implementation-defined by the particular 'impl' you have installed.
func (*Query) Eq ¶
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 ¶
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 ¶
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 ¶
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 ¶
KeysOnly makes this into a query which only returns keys (but doesn't fetch values). It's incompatible with projection queries.
func (*Query) Limit ¶
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 ¶
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 ¶
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 ¶
Offset sets the offset (number of items to skip) for this query. If offset < 0, this removes the offset from the query entirely.
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.
These are the allowed values for Toggle. Any other values are invalid.
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 ¶
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. |