Cloud Firestore V1 API - Class Google::Cloud::Firestore::V1::StructuredQuery (v1.2.0)

Reference documentation and code samples for the Cloud Firestore V1 API class Google::Cloud::Firestore::V1::StructuredQuery.

A Firestore query.

The query stages are executed in the following order:

from
where
select
order_by + start_at + end_at
offset
limit

Inherits

Object

Extended By

Google::Protobuf::MessageExts::ClassMethods

Includes

Google::Protobuf::MessageExts

Methods

#end_at

def end_at() -> ::Google::Cloud::Firestore::V1::Cursor

Returns

(::Google::Cloud::Firestore::V1::Cursor) —
A potential prefix of a position in the result set to end the query at.

This is similar to START_AT but with it controlling the end position rather than the start position.

Requires:
- The number of values cannot be greater than the number of fields specified in the ORDER BY clause.

#end_at=

def end_at=(value) -> ::Google::Cloud::Firestore::V1::Cursor

Parameter

value (::Google::Cloud::Firestore::V1::Cursor) —
A potential prefix of a position in the result set to end the query at.

This is similar to START_AT but with it controlling the end position rather than the start position.

Requires:
- The number of values cannot be greater than the number of fields specified in the ORDER BY clause.

Returns

(::Google::Cloud::Firestore::V1::Cursor) —
A potential prefix of a position in the result set to end the query at.

This is similar to START_AT but with it controlling the end position rather than the start position.

Requires:
- The number of values cannot be greater than the number of fields specified in the ORDER BY clause.

#find_nearest

def find_nearest() -> ::Google::Cloud::Firestore::V1::StructuredQuery::FindNearest

Returns

(::Google::Cloud::Firestore::V1::StructuredQuery::FindNearest) — Optional. A potential nearest neighbors search.

Applies after all other filters and ordering.

Finds the closest vector embeddings to the given query vector.

#find_nearest=

def find_nearest=(value) -> ::Google::Cloud::Firestore::V1::StructuredQuery::FindNearest

Parameter

value (::Google::Cloud::Firestore::V1::StructuredQuery::FindNearest) — Optional. A potential nearest neighbors search.

Applies after all other filters and ordering.

Finds the closest vector embeddings to the given query vector.

Returns

(::Google::Cloud::Firestore::V1::StructuredQuery::FindNearest) — Optional. A potential nearest neighbors search.

Applies after all other filters and ordering.

Finds the closest vector embeddings to the given query vector.

#from

def from() -> ::Array<::Google::Cloud::Firestore::V1::StructuredQuery::CollectionSelector>

Returns

(::Array<::Google::Cloud::Firestore::V1::StructuredQuery::CollectionSelector>) — The collections to query.

#from=

def from=(value) -> ::Array<::Google::Cloud::Firestore::V1::StructuredQuery::CollectionSelector>

Parameter

value (::Array<::Google::Cloud::Firestore::V1::StructuredQuery::CollectionSelector>) — The collections to query.

Returns

(::Array<::Google::Cloud::Firestore::V1::StructuredQuery::CollectionSelector>) — The collections to query.

#limit

def limit() -> ::Google::Protobuf::Int32Value

Returns

(::Google::Protobuf::Int32Value) —
The maximum number of results to return.

Applies after all other constraints.

Requires:
- The value must be greater than or equal to zero if specified.

#limit=

def limit=(value) -> ::Google::Protobuf::Int32Value

Parameter

value (::Google::Protobuf::Int32Value) —
The maximum number of results to return.

Applies after all other constraints.

Requires:
- The value must be greater than or equal to zero if specified.

Returns

(::Google::Protobuf::Int32Value) —
The maximum number of results to return.

Applies after all other constraints.

Requires:
- The value must be greater than or equal to zero if specified.

#offset

def offset() -> ::Integer

Returns

(::Integer) —
The number of documents to skip before returning the first result.

This applies after the constraints specified by the WHERE, START AT, & END AT but before the LIMIT clause.

Requires:
- The value must be greater than or equal to zero if specified.

#offset=

def offset=(value) -> ::Integer

Parameter

value (::Integer) —
The number of documents to skip before returning the first result.

This applies after the constraints specified by the WHERE, START AT, & END AT but before the LIMIT clause.

Requires:
- The value must be greater than or equal to zero if specified.

Returns

(::Integer) —
The number of documents to skip before returning the first result.

This applies after the constraints specified by the WHERE, START AT, & END AT but before the LIMIT clause.

Requires:
- The value must be greater than or equal to zero if specified.

#order_by

def order_by() -> ::Array<::Google::Cloud::Firestore::V1::StructuredQuery::Order>

Returns

(::Array<::Google::Cloud::Firestore::V1::StructuredQuery::Order>) —
The order to apply to the query results.

Firestore allows callers to provide a full ordering, a partial ordering, or no ordering at all. In all cases, Firestore guarantees a stable ordering through the following rules:
- The order_by is required to reference all fields used with an inequality filter.
- All fields that are required to be in the order_by but are not already present are appended in lexicographical ordering of the field name.
- If an order on __name__ is not specified, it is appended by default.
Fields are appended with the same sort direction as the last order specified, or 'ASCENDING' if no order was specified. For example:
- ORDER BY a becomes ORDER BY a ASC, __name__ ASC
- ORDER BY a DESC becomes ORDER BY a DESC, __name__ DESC
- WHERE a > 1 becomes WHERE a > 1 ORDER BY a ASC, __name__ ASC
- WHERE __name__ > ... AND a > 1 becomes WHERE __name__ > ... AND a > 1 ORDER BY a ASC, __name__ ASC

#order_by=

def order_by=(value) -> ::Array<::Google::Cloud::Firestore::V1::StructuredQuery::Order>

Parameter

value (::Array<::Google::Cloud::Firestore::V1::StructuredQuery::Order>) —
The order to apply to the query results.

Firestore allows callers to provide a full ordering, a partial ordering, or no ordering at all. In all cases, Firestore guarantees a stable ordering through the following rules:
- The order_by is required to reference all fields used with an inequality filter.
- All fields that are required to be in the order_by but are not already present are appended in lexicographical ordering of the field name.
- If an order on __name__ is not specified, it is appended by default.
Fields are appended with the same sort direction as the last order specified, or 'ASCENDING' if no order was specified. For example:
- ORDER BY a becomes ORDER BY a ASC, __name__ ASC
- ORDER BY a DESC becomes ORDER BY a DESC, __name__ DESC
- WHERE a > 1 becomes WHERE a > 1 ORDER BY a ASC, __name__ ASC
- WHERE __name__ > ... AND a > 1 becomes WHERE __name__ > ... AND a > 1 ORDER BY a ASC, __name__ ASC

Returns

(::Array<::Google::Cloud::Firestore::V1::StructuredQuery::Order>) —
The order to apply to the query results.

Firestore allows callers to provide a full ordering, a partial ordering, or no ordering at all. In all cases, Firestore guarantees a stable ordering through the following rules:
- The order_by is required to reference all fields used with an inequality filter.
- All fields that are required to be in the order_by but are not already present are appended in lexicographical ordering of the field name.
- If an order on __name__ is not specified, it is appended by default.
Fields are appended with the same sort direction as the last order specified, or 'ASCENDING' if no order was specified. For example:
- ORDER BY a becomes ORDER BY a ASC, __name__ ASC
- ORDER BY a DESC becomes ORDER BY a DESC, __name__ DESC
- WHERE a > 1 becomes WHERE a > 1 ORDER BY a ASC, __name__ ASC
- WHERE __name__ > ... AND a > 1 becomes WHERE __name__ > ... AND a > 1 ORDER BY a ASC, __name__ ASC

#select

def select() -> ::Google::Cloud::Firestore::V1::StructuredQuery::Projection

Returns

(::Google::Cloud::Firestore::V1::StructuredQuery::Projection) — Optional sub-set of the fields to return.

This acts as a DocumentMask over the documents returned from a query. When not set, assumes that the caller wants all fields returned.

#select=

def select=(value) -> ::Google::Cloud::Firestore::V1::StructuredQuery::Projection

Parameter

value (::Google::Cloud::Firestore::V1::StructuredQuery::Projection) — Optional sub-set of the fields to return.

This acts as a DocumentMask over the documents returned from a query. When not set, assumes that the caller wants all fields returned.

Returns

(::Google::Cloud::Firestore::V1::StructuredQuery::Projection) — Optional sub-set of the fields to return.

This acts as a DocumentMask over the documents returned from a query. When not set, assumes that the caller wants all fields returned.

#start_at

def start_at() -> ::Google::Cloud::Firestore::V1::Cursor

Returns

(::Google::Cloud::Firestore::V1::Cursor) —
A potential prefix of a position in the result set to start the query at.

The ordering of the result set is based on the ORDER BY clause of the original query.

SELECT * FROM k WHERE a = 1 AND b > 2 ORDER BY b ASC, __name__ ASC;

This query's results are ordered by (b ASC, __name__ ASC).

Cursors can reference either the full ordering or a prefix of the location, though it cannot reference more fields than what are in the provided ORDER BY.

Continuing off the example above, attaching the following start cursors will have varying impact:
- START BEFORE (2, /k/123): start the query right before a = 1 AND b > 2 AND __name__ > /k/123.
- START AFTER (10): start the query right after a = 1 AND b > 10.
Unlike OFFSET which requires scanning over the first N results to skip, a start cursor allows the query to begin at a logical position. This position is not required to match an actual result, it will scan forward from this position to find the next document.

Requires:
- The number of values cannot be greater than the number of fields specified in the ORDER BY clause.

#start_at=

def start_at=(value) -> ::Google::Cloud::Firestore::V1::Cursor

Parameter

value (::Google::Cloud::Firestore::V1::Cursor) —
A potential prefix of a position in the result set to start the query at.

The ordering of the result set is based on the ORDER BY clause of the original query.

SELECT * FROM k WHERE a = 1 AND b > 2 ORDER BY b ASC, __name__ ASC;

This query's results are ordered by (b ASC, __name__ ASC).

Cursors can reference either the full ordering or a prefix of the location, though it cannot reference more fields than what are in the provided ORDER BY.

Continuing off the example above, attaching the following start cursors will have varying impact:
- START BEFORE (2, /k/123): start the query right before a = 1 AND b > 2 AND __name__ > /k/123.
- START AFTER (10): start the query right after a = 1 AND b > 10.
Unlike OFFSET which requires scanning over the first N results to skip, a start cursor allows the query to begin at a logical position. This position is not required to match an actual result, it will scan forward from this position to find the next document.

Requires:
- The number of values cannot be greater than the number of fields specified in the ORDER BY clause.

Returns

(::Google::Cloud::Firestore::V1::Cursor) —
A potential prefix of a position in the result set to start the query at.

The ordering of the result set is based on the ORDER BY clause of the original query.

SELECT * FROM k WHERE a = 1 AND b > 2 ORDER BY b ASC, __name__ ASC;

This query's results are ordered by (b ASC, __name__ ASC).

Cursors can reference either the full ordering or a prefix of the location, though it cannot reference more fields than what are in the provided ORDER BY.

Continuing off the example above, attaching the following start cursors will have varying impact:
- START BEFORE (2, /k/123): start the query right before a = 1 AND b > 2 AND __name__ > /k/123.
- START AFTER (10): start the query right after a = 1 AND b > 10.
Unlike OFFSET which requires scanning over the first N results to skip, a start cursor allows the query to begin at a logical position. This position is not required to match an actual result, it will scan forward from this position to find the next document.

Requires:
- The number of values cannot be greater than the number of fields specified in the ORDER BY clause.

#where

def where() -> ::Google::Cloud::Firestore::V1::StructuredQuery::Filter

Returns

(::Google::Cloud::Firestore::V1::StructuredQuery::Filter) — The filter to apply.

#where=

def where=(value) -> ::Google::Cloud::Firestore::V1::StructuredQuery::Filter

Parameter

value (::Google::Cloud::Firestore::V1::StructuredQuery::Filter) — The filter to apply.

Returns

(::Google::Cloud::Firestore::V1::StructuredQuery::Filter) — The filter to apply.