db

Low-level database API and data query layer.

server.db.Delete(keys, **kwargs)

Deletes one or more entities from the data store.

Warning:Permanently deletes entities, use with care!

Deletes the given entity or entities from the data store. You can only delete entities from your app. If there is an error, the function raises a subclass of datastore_errors.Error.

Parameters:
  • keys (Key | str | list of Key | list of str) – Key, str or list of keys or strings to be deleted.
  • config (dict) – Optional configuration to use for this request. This must be specified as a keyword argument.
Raises:

TransactionFailedError, if the deletion could not be committed.

server.db.DeleteAsync(keys, **kwargs)

Asynchronously deletes one or more entities from the data store.

This function is identical to server.db.Delete(), except that it returns an asynchronous object. Call get_result() on the return value to block on the call and get the results.

server.db.Entity
server.db.Get(keys, **kwargs)

Retrieve one or more entities from the data store.

Retrieves the entity or entities with the given key(s) from the data store and returns them as fully populated server.db.Entity objects.

If there is an error, the function raises a subclass of datastore_errors.Error.

If keys is a single key or str, an Entity will be returned, or EntityNotFoundError will be raised if no existing entity matches the key.

However, if keys is a list or tuple, a list of entities will be returned that corresponds to the sequence of keys. It will include entities for keys that were found and None placeholders for keys that were not found.

Parameters:
  • keys (Key | str | list of Key | list of str) – Key, str or list of keys or strings to be retrieved.
  • config (dict) – Optional configuration to use for this request. This must be specified as a keyword argument.
Returns:

Entity or list of Entity objects corresponding to the specified key(s).

Return type:

server.db.Entity | list of server.db.Entity

server.db.GetAsync(keys, **kwargs)

Asynchronously retrieves one or more entities from the data store.

This function is identical to server.db.Get(), except that it returns an asynchronous object. Call get_result() on the return value to block on the call and get the results.

server.db.GetOrInsert(key, kindName=None, parent=None, **kwargs)

Either creates a new entity with the given key, or returns the existing one.

Its guaranteed that there is no race-condition here; it will never overwrite an previously created entity. Extra keyword arguments passed to this function will be used to populate the entity if it has to be created; otherwise they are ignored.

Parameters:
  • key (server.db.Key | String) – The key which will be fetched or created. If key is a string, it will be used as the name for the new entity, therefore the collectionName is required in this case.
  • kindName (str) – The data kind to use for that entity. Ignored if key is a db.Key.
  • parent (db.Key or None) – The parent entity of the entity.
Returns:

Returns the wanted Entity.

Return type:

server.db.Entity

server.db.Put(entities, **kwargs)

Store one or more entities in the data store.

The entities may be new or previously existing. For new entities, Put() will fill in the app id and key assigned by the data store.

Parameters:
  • entities (server.db.Entity | list of server.db.Entity) – Entity or list of entities to be stored.
  • config (dict) – Optional configuration to use for this request. This must be specified as a keyword argument.
Returns:

If the argument entities is a single server.db.Entity, a single Key is returned. If the argument is a list of server.db.Entity, a list of Keys will be returned.

Return type:

Key | list of keys

Raises:

TransactionFailedError, if the action could not be committed.

server.db.PutAsync(entities, **kwargs)

Asynchronously store one or more entities in the data store.

This function is identical to server.db.Put(), except that it returns an asynchronous object. Call get_result() on the return value to block on the call and get the results.

class server.db.Query(kind, srcSkelClass=None, *args, **kwargs)

Bases: object

Thin wrapper around datastore.Query to provide a consistent (camelCase) API.

__weakref__

list of weak references to the object (if defined)

ancestor(ancestor)

Sets an ancestor for this query.

This restricts the query to only return result entities that are descended from a given entity. In other words, all of the results will have the ancestor as their parent, or parent’s parent, and so on.

Raises BadArgumentError or BadKeyError if parent is not an existing Entity or Key in the data store.

Parameters:ancestor (server.db.Entity | Key) – Entity or Key. The key must be complete.
Returns:Returns the query itself for chaining.
Return type:server.db.Query
clone(keysOnly=None)

Returns a deep copy of the current query.

Parameters:keysOnly (bool) – If the query should be used to retrieve entity keys only in the new query.
Returns:The cloned query.
Return type:server.db.Query
count(limit=1000, **kwargs)

Returns the number of entities that this query matches.

Parameters:
  • limit (int) – Limits the query to the defined maximum entities count. If there are more results than this limit, stop short and just return this number. Providing this argument makes the count operation more efficient.
  • config (dict) – Optional configuration to use for this request. This must be specified as a keyword argument.
Returns:

The number of results.

Return type:

int

cursor(cursor, endCursor=None)

Sets the start cursor for this query.

The result set will only include results behind that cursor. The cursor is generated by an earlier query with exactly the same configuration.

Its safe to use client-supplied cursors, a cursor can’t be abused to access entities which don’t match the current filters.

Parameters:cursor (str | datastore_query.Cursor) – The cursor key to set to the Query.
Returns:Returns the query itself for chaining.
Return type:server.db.Query
fetch(limit=-1, **kwargs)

Run this query and fetch results as server.skeleton.SkelList.

This function is similar to server.db.Query.run(), but returns a server.skeleton.SkelList instance instead of Entities.

Warning:The query must be limited!

If queried data is wanted as instances of Entity, server.db.Query.run() should be used.

Parameters:limit (int) – Limits the query to the defined maximum entities. A maxiumum value of 99 entries can be fetched at once.
Raises:BadFilterError if a filter string is invalid
Raises:BadValueError if a filter value is invalid.
Raises:BadQueryError if an IN filter in combination with a sort order on another property is provided
filter(filter, value=None)

Adds a filter to this query. #fixme: Better description required here...

The following examples are equivalent: filter( "name", "John" ) and filter( {"name": "John"} ).

See also server.db.Query.mergeExternalFilter() for a safer filter implementation.

Parameters:
  • filter (dict | str) – A dictionary to read the filters from, or a string (name of that filter)
  • value – The value of that filter. Only valid, if key is a string.
Type:

value: int | long | float | bytes | string | list | datetime

Returns:

Returns the query itself for chaining.

Return type:

server.db.Query

get()

Returns only the first entity of the current query.

Returns:dict on success, or None if the result-set is empty.
Return type:dict
getAncestor()

Returns the ancestor of this query (if any).

Return type:str | None
getCursor()

Get a valid cursor from the last run of this query.

The source of this cursor varies depending on what the last call was: - server.db.Query.run(): A cursor that points immediatelly behind the last result pulled off the returned iterator. - server.db.Query.get():: A cursor that points immediatelly behind the last result in the returned list. - server.db.Query.count(): A cursor that points immediatelly behind the last result counted.

Returns:A cursor that can be used in subsequent query requests.
Return type:datastore_query.Cursor
Raises:AssertionError if the query has not yet been run or cannot be compiled.
getFilter()

Returns the filters applied to the current query as dictionary.

Returns:Filter as dictionary.
Return type:dict
getKind()

Returns the kind of this query.

Return type:str
getOrder()

Gets a datastore_query.Order for the current instance.

Returns:The sort orders set on the current query, or None.
Return type:datastore_query.Order or None
getOrders()

Returns a list of orders applied to this query.

Every element in the list returned (if any), is a tuple of (property,direction).

Property is the name of the property used to sort, direction a bool (false => ascending, True => descending).

Returns:List of orderings, in tuples (property,direction).
Return type:list
getQuery()

Returns a datastore_query.Query for the current instance.

Return type:datastore_query.Query
getQueryOptions()

Returns a datastore_query.QueryOptions for the current instance.

Return type:datastore_query.QueryOptions
getSkel()

Returns a matching server.db.skeleton.Skeleton instance for the current query.

Its only possible to use this function if this query has been created using server.skeleton.Skeleton.all().

Returns:The Skeleton or None if the result-set is empty.
Return type:server.skeleton.Skeleton
isKeysOnly()

Returns True if this query is configured as keys only, False otherwise.

Return type:bool
iter(keysOnly=False)

Run this query and return an iterator for the results.

The advantage of this function is, that it allows for iterating over a large result-set, as it hasn’t have to be pulled in advance from the data store.

The disadvantage is, that is supports no caching yet.

This function intentionally ignores a limit set by server.db.Query.limit().

Warning:If iterating over a large result set, make sure the query supports cursors. Otherwise, it might not return all results as the AppEngine doesn’t maintain the view for a query for more than ~30 seconds.
Parameters:keysOnly (bool) – If the query should be used to retrieve entity keys only.
limit(amount)

Sets the query limit to amount entities in the result.

Specifying an amount of 0 disables the limit (use with care!).

Parameters:amount (int) – The maximum number of entities.
Returns:Returns the query itself for chaining.
Return type:server.db.Query
mergeExternalFilter(filters)

Safely merges filters according to the data model.

Its only valid to call this function if the query has been created using server.skeleton.Skeleton.all().

Its safe to pass filters received from an external source (a user); unknown/invalid filters will be ignored, so the query-object is kept in a valid state even when processing malformed data.

If complex queries are needed (e.g. filter by relations), this function shall also be used.

See also server.db.Query.filter() for simple filters.

Parameters:filters (dict) – A dictionary of attributes and filter pairs.
Returns:Returns the query itself for chaining.
Return type:server.db.Query
order(*orderings)

Specify a query sorting.

Resulting entities will be sorted by the first property argument, then by the second, and so on.

The following example

query = Query( "Person" )
query.order( "bday", ( "age", Query.DESCENDING ) )

sorts every Person in order of their birthday, starting with January 1. People with the same birthday are sorted by age, oldest to youngest.

The direction for each sort property may be provided; if omitted, it defaults to ascending.

order() may be called multiple times. Each call resets the sort order from scratch.

If an inequality filter exists in this Query it must be the first property passed to order(). Any number of sort orders may be used after the inequality filter property. Without inequality filters, any number of filters with different orders may be specified.

Entities with multiple values for an order property are sorted by their lowest value.

Note that a sort order implies an existence filter! In other words, Entities without the sort order property are filtered out, and not included in the query results.

If the sort order property has different types in different entities - e.g. if bob[‘id’] is an int and fred[‘id’] is a string - the entities will be grouped first by the property type, then sorted within type. No attempt is made to compare property values across types.

Raises BadArgumentError if any argument is of the wrong format.

Parameters:
  • orderings – The properties to sort by, in sort order. Each argument may be either a string or (string, direction) 2-tuple.
  • orderings – str | tuple
Returns:

Returns the query itself for chaining.

Return type:

server.db.Query

run(limit=-1, keysOnly=False, **kwargs)

Run this query.

It is more efficient to use limit if the number of results is known.

If queried data is wanted as instances of Skeletons, server.db.Query.fetch() should be used.

Parameters:
  • limit (int) – Limits the query to the defined maximum entities.
  • keysOnly (bool) – If the query should be used to retrieve entity keys only.
  • kwargs – Any keyword arguments accepted by datastore_query.QueryOptions().
Returns:

An iterator that provides access to the query results iterator

Return type:

list

Raises:

BadFilterError if a filter string is invalid

Raises:

BadValueError if a filter value is invalid.

Raises:

BadQueryError if an IN filter in combination with a sort order on another property is provided

setFilterHook(hook)

Installs hook as a callback function for new filters.

hook will be called each time a new filter constrain is added to the query. This allows e. g. the relationalBone to rewrite constrains added after the initial processing of the query has been done (e. g. by listFilter() methods).

Parameters:hook (callable) – The function to register as callback. A value of None removes the currently active hook.
Returns:The previously registered hook (if any), or None.
setKind(newKind)

Sets the kind of this query.

Parameters:newKind (str) – New query kind.
setOrderHook(hook)

Installs hook as a callback function for new orderings.

hook will be called each time a db.Query.order() is called on this query.

Parameters:hook (callable) – The function to register as callback. A value of None removes the currently active hook.
Returns:The previously registered hook (if any), or None.