def get_entity(self, key_or_path):
"""Retrieves entity from the dataset, along with its attributes.
:type key_or_path: :class:`gcloud.datastore.key.Key` or path
:param key_or_path: The name of the item to retrieve or sequence
of even length, where the first of each pair
is a string representing the 'kind' of the
path element, and the second of the pair is
either a string (for the path element's name)
or an integer (for its id).
:rtype: :class:`gcloud.datastore.entity.Entity` or ``None``
:return: The requested entity, or ``None`` if there was no match found.
"""
if isinstance(key_or_path, Key):
entities = self.get_entities([key_or_path])
else:
key = Key.from_path(*key_or_path)
entities = self.get_entities([key])
if entities:
return entities[0]
def get_entity(self, key_or_path):
"""Retrieves entity from the dataset, along with its attributes.
:type key_or_path: :class:`gcloud.datastore.key.Key` or path
:param key_or_path: The name of the item to retrieve or sequence
of even length, where the first of each pair
is a string representing the 'kind' of the
path element, and the second of the pair is
either a string (for the path element's name)
or an integer (for its id).
:rtype: :class:`gcloud.datastore.entity.Entity` or ``None``
:return: The requested entity, or ``None`` if there was no match found.
"""
if isinstance(key_or_path, Key):
entities = self.get_entities([key_or_path])
else:
key = Key.from_path(*key_or_path)
entities = self.get_entities([key])
if entities:
return entities[0]
def ancestor(self, ancestor):
"""Filter the query based on an ancestor.
This will return a clone of the current :class:`Query`
filtered by the ancestor provided.
For example::
>>> parent_key = Key.from_path('Person', '1')
>>> query = dataset.query('Person')
>>> filtered_query = query.ancestor(parent_key)
If you don't have a :class:`gcloud.datastore.key.Key` but just
know the path, you can provide that as well::
>>> query = dataset.query('Person')
>>> filtered_query = query.ancestor(['Person', '1'])
Each call to ``.ancestor()`` returns a cloned :class:`Query`,
however a query may only have one ancestor at a time.
:type ancestor: :class:`gcloud.datastore.key.Key` or list
:param ancestor: Either a Key or a path of the form
``['Kind', 'id or name', 'Kind', 'id or name', ...]``.
:rtype: :class:`Query`
:returns: A Query filtered by the ancestor provided.
"""
clone = self._clone()
# If an ancestor filter already exists, remove it.
for i, filter in enumerate(clone._pb.filter.composite_filter.filter):
property_filter = filter.property_filter
if (property_filter.operator ==
datastore_pb.PropertyFilter.HAS_ANCESTOR):
del clone._pb.filter.composite_filter.filter[i]
# If we just deleted the last item, make sure to clear out the
# filter property all together.
if not clone._pb.filter.composite_filter.filter:
clone._pb.ClearField('filter')
# If the ancestor is None, just return (we already removed the filter).
if not ancestor:
return clone
# If a list was provided, turn it into a Key.
if isinstance(ancestor, list):
ancestor = Key.from_path(*ancestor)
# If we don't have a Key value by now, something is wrong.
if not isinstance(ancestor, Key):
raise TypeError('Expected list or Key, got %s.' % type(ancestor))
# Get the composite filter and add a new property filter.
composite_filter = clone._pb.filter.composite_filter
composite_filter.operator = datastore_pb.CompositeFilter.AND
# Filter on __key__ HAS_ANCESTOR == ancestor.
ancestor_filter = composite_filter.filter.add().property_filter
ancestor_filter.property.name = '__key__'
ancestor_filter.operator = datastore_pb.PropertyFilter.HAS_ANCESTOR
ancestor_filter.value.key_value.CopyFrom(ancestor.to_protobuf())
return clone
def ancestor(self, ancestor):
"""Filter the query based on an ancestor.
This will return a clone of the current :class:`Query`
filtered by the ancestor provided.
For example::
>>> parent_key = Key.from_path('Person', '1')
>>> query = dataset.query('Person')
>>> filtered_query = query.ancestor(parent_key)
If you don't have a :class:`gcloud.datastore.key.Key` but just
know the path, you can provide that as well::
>>> query = dataset.query('Person')
>>> filtered_query = query.ancestor(['Person', '1'])
Each call to ``.ancestor()`` returns a cloned :class:`Query:,
however a query may only have one ancestor at a time.
:type ancestor: :class:`gcloud.datastore.key.Key` or list
:param ancestor: Either a Key or a path of the form
``['Kind', 'id or name', 'Kind', 'id or name', ...]``.
:rtype: :class:`Query`
:returns: A Query filtered by the ancestor provided.
"""
clone = self._clone()
# If an ancestor filter already exists, remove it.
for i, filter in enumerate(clone._pb.filter.composite_filter.filter):
property_filter = filter.property_filter
if property_filter.operator == datastore_pb.PropertyFilter.HAS_ANCESTOR:
del clone._pb.filter.composite_filter.filter[i]
# If we just deleted the last item, make sure to clear out the filter
# property all together.
if not clone._pb.filter.composite_filter.filter:
clone._pb.ClearField('filter')
# If the ancestor is None, just return (we already removed the filter).
if not ancestor:
return clone
# If a list was provided, turn it into a Key.
if isinstance(ancestor, list):
ancestor = Key.from_path(*ancestor)
# If we don't have a Key value by now, something is wrong.
if not isinstance(ancestor, Key):
raise TypeError('Expected list or Key, got %s.' % type(ancestor))
# Get the composite filter and add a new property filter.
composite_filter = clone._pb.filter.composite_filter
composite_filter.operator = datastore_pb.CompositeFilter.AND
# Filter on __key__ HAS_ANCESTOR == ancestor.
ancestor_filter = composite_filter.filter.add().property_filter
ancestor_filter.property.name = '__key__'
ancestor_filter.operator = datastore_pb.PropertyFilter.HAS_ANCESTOR
ancestor_filter.value.key_value.CopyFrom(ancestor.to_protobuf())
return clone
