Cloud Firestore V1 Client - Class StructuredQuery (1.47.2)

Reference documentation and code samples for the Cloud Firestore V1 Client class StructuredQuery.

A Firestore query.

The query stages are executed in the following order:

  1. from
  2. where
  3. select
  4. order_by + start_at + end_at
  5. offset
  6. limit

Generated from protobuf message google.firestore.v1.StructuredQuery

Namespace

Google \ Cloud \ Firestore \ V1

Methods

__construct

Constructor.

Parameters
Name Description
data array

Optional. Data for populating the Message object.
↳ select 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.
↳ from array<StructuredQuery\CollectionSelector>

The collections to query.
↳ where StructuredQuery\Filter

The filter to apply.
↳ order_by array<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
↳ start_at 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.
↳ end_at 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.
↳ offset int

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.
↳ limit 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.
↳ find_nearest 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.

getSelect

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
Type Description
StructuredQuery\Projection|null

hasSelect

clearSelect

setSelect

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.

Parameter
Name Description
var StructuredQuery\Projection
Returns
Type Description
$this

getFrom

The collections to query.

Returns
Type Description
Google\Protobuf\Internal\RepeatedField

setFrom

The collections to query.

Parameter
Name Description
var array<StructuredQuery\CollectionSelector>
Returns
Type Description
$this

getWhere

The filter to apply.

Returns
Type Description
StructuredQuery\Filter|null

hasWhere

clearWhere

setWhere

The filter to apply.

Parameter
Name Description
var StructuredQuery\Filter
Returns
Type Description
$this

getOrderBy

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
Type Description
Google\Protobuf\Internal\RepeatedField

setOrderBy

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
Parameter
Name Description
var array<StructuredQuery\Order>
Returns
Type Description
$this

getStartAt

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
Type Description
Cursor|null

hasStartAt

clearStartAt

setStartAt

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.
Parameter
Name Description
var Cursor
Returns
Type Description
$this

getEndAt

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
Type Description
Cursor|null

hasEndAt

clearEndAt

setEndAt

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.
Parameter
Name Description
var Cursor
Returns
Type Description
$this

getOffset

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
Type Description
int

setOffset

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.
Parameter
Name Description
var int
Returns
Type Description
$this

getLimit

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
Type Description
Google\Protobuf\Int32Value|null

hasLimit

clearLimit

getLimitValue

Returns the unboxed value from getLimit()

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
Type Description
int|null

setLimit

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.
Parameter
Name Description
var Google\Protobuf\Int32Value
Returns
Type Description
$this

setLimitValue

Sets the field by wrapping a primitive type in a Google\Protobuf\Int32Value object.

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.
Parameter
Name Description
var int|null
Returns
Type Description
$this

getFindNearest

Optional. A potential nearest neighbors search.

Applies after all other filters and ordering. Finds the closest vector embeddings to the given query vector.

Returns
Type Description
StructuredQuery\FindNearest|null

hasFindNearest

clearFindNearest

setFindNearest

Optional. A potential nearest neighbors search.

Applies after all other filters and ordering. Finds the closest vector embeddings to the given query vector.

Parameter
Name Description
var StructuredQuery\FindNearest
Returns
Type Description
$this