def select(self, field_paths):
"""Project documents matching query to a limited set of fields.
See :meth:`~.firestore_v1beta1.client.Client.field_path` for
more information on **field paths**.
If the current query already has a projection set (i.e. has already
called :meth:`~.firestore_v1beta1.query.Query.select`), this
will overwrite it.
Args:
field_paths (Iterable[str, ...]): An iterable of field paths
(``.``-delimited list of field names) to use as a projection
of document fields in the query results.
Returns:
~.firestore_v1beta1.query.Query: A "projected" query. Acts as
a copy of the current query, modified with the newly added
projection.
Raises:
ValueError: If any ``field_path`` is invalid.
"""
field_paths = list(field_paths)
for field_path in field_paths:
field_path_module.split_field_path(field_path) # raises
new_projection = query_pb2.StructuredQuery.Projection(
fields=[
query_pb2.StructuredQuery.FieldReference(field_path=field_path)
for field_path in field_paths
]
)
return self.__class__(
self._parent,
projection=new_projection,
field_filters=self._field_filters,
orders=self._orders,
limit=self._limit,
offset=self._offset,
start_at=self._start_at,
end_at=self._end_at,
)
def order_by(self, field_path, direction=ASCENDING):
"""Modify the query to add an order clause on a specific field.
See :meth:`~.firestore_v1beta1.client.Client.field_path` for
more information on **field paths**.
Successive :meth:`~.firestore_v1beta1.query.Query.order_by` calls
will further refine the ordering of results returned by the query
(i.e. the new "order by" fields will be added to existing ones).
Args:
field_path (str): A field path (``.``-delimited list of
field names) on which to order the query results.
direction (Optional[str]): The direction to order by. Must be one
of :attr:`ASCENDING` or :attr:`DESCENDING`, defaults to
:attr:`ASCENDING`.
Returns:
~.firestore_v1beta1.query.Query: An ordered query. Acts as a
copy of the current query, modified with the newly added
"order by" constraint.
Raises:
ValueError: If ``field_path`` is invalid.
ValueError: If ``direction`` is not one of :attr:`ASCENDING` or
:attr:`DESCENDING`.
"""
field_path_module.split_field_path(field_path) # raises
order_pb = self._make_order(field_path, direction)
new_orders = self._orders + (order_pb, )
return self.__class__(
self._parent,
projection=self._projection,
field_filters=self._field_filters,
orders=new_orders,
limit=self._limit,
offset=self._offset,
start_at=self._start_at,
end_at=self._end_at,
)
def order_by(self, field_path, direction=ASCENDING):
"""Modify the query to add an order clause on a specific field.
See :meth:`~google.cloud.firestore_v1beta1.client.Client.field_path`
for more information on **field paths**.
Successive :meth:`~google.cloud.firestore_v1beta1.query.Query.order_by` calls
will further refine the ordering of results returned by the query
(i.e. the new "order by" fields will be added to existing ones).
Args:
field_path (str): A field path (``.``-delimited list of
field names) on which to order the query results.
direction (Optional[str]): The direction to order by. Must be one
of :attr:`ASCENDING` or :attr:`DESCENDING`, defaults to
:attr:`ASCENDING`.
Returns:
~.firestore_v1beta1.query.Query: An ordered query. Acts as a
copy of the current query, modified with the newly added
"order by" constraint.
Raises:
ValueError: If ``field_path`` is invalid.
ValueError: If ``direction`` is not one of :attr:`ASCENDING` or
:attr:`DESCENDING`.
"""
field_path_module.split_field_path(field_path) # raises
order_pb = self._make_order(field_path, direction)
new_orders = self._orders + (order_pb,)
return self.__class__(
self._parent,
projection=self._projection,
field_filters=self._field_filters,
orders=new_orders,
limit=self._limit,
offset=self._offset,
start_at=self._start_at,
end_at=self._end_at,
)
def select(self, field_paths):
"""Project documents matching query to a limited set of fields.
See :meth:`~google.cloud.firestore_v1beta1.client.Client.field_path`
for more information on **field paths**.
If the current query already has a projection set (i.e. has already
called :meth:`~google.cloud.firestore_v1beta1.query.Query.select`),
this will overwrite it.
Args:
field_paths (Iterable[str, ...]): An iterable of field paths
(``.``-delimited list of field names) to use as a projection
of document fields in the query results.
Returns:
~.firestore_v1beta1.query.Query: A "projected" query. Acts as
a copy of the current query, modified with the newly added
projection.
Raises:
ValueError: If any ``field_path`` is invalid.
"""
field_paths = list(field_paths)
for field_path in field_paths:
field_path_module.split_field_path(field_path) # raises
new_projection = query_pb2.StructuredQuery.Projection(
fields=[
query_pb2.StructuredQuery.FieldReference(field_path=field_path)
for field_path in field_paths
]
)
return self.__class__(
self._parent,
projection=new_projection,
field_filters=self._field_filters,
orders=self._orders,
limit=self._limit,
offset=self._offset,
start_at=self._start_at,
end_at=self._end_at,
)
def _call_fut(path):
from google.cloud.firestore_v1beta1 import field_path
return field_path.split_field_path(path)
def where(self, field_path, op_string, value):
"""Filter the query on a field.
See :meth:`~.firestore_v1beta1.client.Client.field_path` for
more information on **field paths**.
Returns a new :class:`~.firestore_v1beta1.query.Query` that
filters on a specific field path, according to an operation (e.g.
``==`` or "equals") and a particular value to be paired with that
operation.
Args:
field_path (str): A field path (``.``-delimited list of
field names) for the field to filter on.
op_string (str): A comparison operation in the form of a string.
Acceptable values are ``<``, ``<=``, ``==``, ``>=``
and ``>``.
value (Any): The value to compare the field against in the filter.
If ``value`` is :data:`None` or a NaN, then ``==`` is the only
allowed operation.
Returns:
~.firestore_v1beta1.query.Query: A filtered query. Acts as a
copy of the current query, modified with the newly added filter.
Raises:
ValueError: If ``field_path`` is invalid.
ValueError: If ``value`` is a NaN or :data:`None` and
``op_string`` is not ``==``.
"""
field_path_module.split_field_path(field_path) # raises
if value is None:
if op_string != _EQ_OP:
raise ValueError(_BAD_OP_NAN_NULL)
filter_pb = query_pb2.StructuredQuery.UnaryFilter(
field=query_pb2.StructuredQuery.FieldReference(
field_path=field_path),
op=enums.StructuredQuery.UnaryFilter.Operator.IS_NULL,
)
elif _isnan(value):
if op_string != _EQ_OP:
raise ValueError(_BAD_OP_NAN_NULL)
filter_pb = query_pb2.StructuredQuery.UnaryFilter(
field=query_pb2.StructuredQuery.FieldReference(
field_path=field_path),
op=enums.StructuredQuery.UnaryFilter.Operator.IS_NAN,
)
elif isinstance(value, (transforms.Sentinel, transforms._ValueList)):
raise ValueError(_INVALID_WHERE_TRANSFORM)
else:
filter_pb = query_pb2.StructuredQuery.FieldFilter(
field=query_pb2.StructuredQuery.FieldReference(
field_path=field_path),
op=_enum_from_op_string(op_string),
value=_helpers.encode_value(value),
)
new_filters = self._field_filters + (filter_pb, )
return self.__class__(
self._parent,
projection=self._projection,
field_filters=new_filters,
orders=self._orders,
limit=self._limit,
offset=self._offset,
start_at=self._start_at,
end_at=self._end_at,
)
def _call_fut(path):
from google.cloud.firestore_v1beta1 import field_path
return field_path.split_field_path(path)
def where(self, field_path, op_string, value):
"""Filter the query on a field.
See :meth:`~google.cloud.firestore_v1beta1.client.Client.field_path`
for more information on **field paths**.
Returns a new :class:`~google.cloud.firestore_v1beta1.query.Query`
that filters on a specific field path, according to an operation
(e.g. ``==`` or "equals") and a particular value to be paired with
that operation.
Args:
field_path (str): A field path (``.``-delimited list of
field names) for the field to filter on.
op_string (str): A comparison operation in the form of a string.
Acceptable values are ``<``, ``<=``, ``==``, ``>=``
and ``>``.
value (Any): The value to compare the field against in the filter.
If ``value`` is :data:`None` or a NaN, then ``==`` is the only
allowed operation.
Returns:
~.firestore_v1beta1.query.Query: A filtered query. Acts as a
copy of the current query, modified with the newly added filter.
Raises:
ValueError: If ``field_path`` is invalid.
ValueError: If ``value`` is a NaN or :data:`None` and
``op_string`` is not ``==``.
"""
field_path_module.split_field_path(field_path) # raises
if value is None:
if op_string != _EQ_OP:
raise ValueError(_BAD_OP_NAN_NULL)
filter_pb = query_pb2.StructuredQuery.UnaryFilter(
field=query_pb2.StructuredQuery.FieldReference(field_path=field_path),
op=enums.StructuredQuery.UnaryFilter.Operator.IS_NULL,
)
elif _isnan(value):
if op_string != _EQ_OP:
raise ValueError(_BAD_OP_NAN_NULL)
filter_pb = query_pb2.StructuredQuery.UnaryFilter(
field=query_pb2.StructuredQuery.FieldReference(field_path=field_path),
op=enums.StructuredQuery.UnaryFilter.Operator.IS_NAN,
)
elif isinstance(value, (transforms.Sentinel, transforms._ValueList)):
raise ValueError(_INVALID_WHERE_TRANSFORM)
else:
filter_pb = query_pb2.StructuredQuery.FieldFilter(
field=query_pb2.StructuredQuery.FieldReference(field_path=field_path),
op=_enum_from_op_string(op_string),
value=_helpers.encode_value(value),
)
new_filters = self._field_filters + (filter_pb,)
return self.__class__(
self._parent,
projection=self._projection,
field_filters=new_filters,
orders=self._orders,
limit=self._limit,
offset=self._offset,
start_at=self._start_at,
end_at=self._end_at,
)
