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`. """ _helpers.split_field_path(field_path) # raises order_pb = query_pb2.StructuredQuery.Order( field=query_pb2.StructuredQuery.FieldReference( field_path=field_path), direction=_enum_from_direction(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:`~.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: _helpers.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 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 ``==``. """ _helpers.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, )