StructuredQuery

A Firestore query.

The query stages are executed in the following order: 1. from 2. where 3. select 4. orderBy + startAt + endAt 5. offset 6. limit 7. findNearest

JSON representation
{"select":{object (Projection)},"from":[{object (CollectionSelector)}],"where":{object (Filter)},"orderBy":[{object (Order)}],"startAt":{object (Cursor)},"endAt":{object (Cursor)},"offset":integer,"limit":integer,"findNearest":{object (FindNearest)}}
Fields
select

object (Projection)

Optional sub-set of the fields to return.

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

from[]

object (CollectionSelector)

The collections to query.

where

object (Filter)

The filter to apply.

orderBy[]

object (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:

  • TheorderBy is required to reference all fields used with an inequality filter.
  • All fields that are required to be in theorderBy 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 becomesORDER BY a ASC, __name__ ASC
  • ORDER BY a DESC becomesORDER BY a DESC, __name__ DESC
  • WHERE a > 1 becomesWHERE a > 1 ORDER BY a ASC, __name__ ASC
  • WHERE __name__ > ... AND a > 1 becomesWHERE __name__ > ... AND a > 1 ORDER BY a ASC, __name__ ASC
startAt

object (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 theORDER 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 providedORDER BY.

Continuing off the example above, attaching the following start cursors will have varying impact:

  • START BEFORE (2, /k/123): start the query right beforea = 1 AND b > 2 AND __name__ > /k/123.
  • START AFTER (10): start the query right aftera = 1 AND b > 10.

UnlikeOFFSET 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 theORDER BY clause.
endAt

object (Cursor)

A potential prefix of a position in the result set to end the query at.

This is similar toSTART_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 theORDER BY clause.
offset

integer

The number of documents to skip before returning the first result.

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

Requires:

  • The value must be greater than or equal to zero if specified.
limit

integer

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.
findNearest

object (FindNearest)

Optional. A potential nearest neighbors search.

Applies after all other filters and ordering.

Finds the closest vector embeddings to the given query vector.

Projection

The projection of document's fields to return.

JSON representation
{"fields":[{object (FieldReference)}]}
Fields
fields[]

object (FieldReference)

The fields to return.

If empty, all fields are returned. To only return the name of the document, use['__name__'].

CollectionSelector

A selection of a collection, such asmessages as m1.

JSON representation
{"collectionId":string,"allDescendants":boolean}
Fields
collectionId

string

The collection ID. When set, selects only collections with this ID.

allDescendants

boolean

When false, selects only collections that are immediate children of theparent specified in the containingRunQueryRequest. When true, selects all descendant collections.

Filter

A filter.

JSON representation
{// Union fieldfilter_type can be only one of the following:"compositeFilter":{object (CompositeFilter)},"fieldFilter":{object (FieldFilter)},"unaryFilter":{object (UnaryFilter)}// End of list of possible types for union fieldfilter_type.}
Fields
Union fieldfilter_type. The type of filter.filter_type can be only one of the following:
compositeFilter

object (CompositeFilter)

A composite filter.

fieldFilter

object (FieldFilter)

A filter on a document field.

unaryFilter

object (UnaryFilter)

A filter that takes exactly one argument.

CompositeFilter

A filter that merges multiple other filters using the given operator.

JSON representation
{"op":enum (Operator),"filters":[{object (Filter)}]}
Fields
op

enum (Operator)

The operator for combining multiple filters.

filters[]

object (Filter)

The list of filters to combine.

Requires:

  • At least one filter is present.

Operator

A composite filter operator.

Enums
OPERATOR_UNSPECIFIEDUnspecified. This value must not be used.
ANDDocuments are required to satisfy all of the combined filters.
ORDocuments are required to satisfy at least one of the combined filters.

FieldFilter

A filter on a specific field.

JSON representation
{"field":{object (FieldReference)},"op":enum (Operator),"value":{object (Value)}}
Fields
field

object (FieldReference)

The field to filter by.

op

enum (Operator)

The operator to filter by.

value

object (Value)

The value to compare to.

Operator

A field filter operator.

Enums
OPERATOR_UNSPECIFIEDUnspecified. This value must not be used.
LESS_THAN

The givenfield is less than the givenvalue.

Requires:

  • Thatfield come first inorderBy.
LESS_THAN_OR_EQUAL

The givenfield is less than or equal to the givenvalue.

Requires:

  • Thatfield come first inorderBy.
GREATER_THAN

The givenfield is greater than the givenvalue.

Requires:

  • Thatfield come first inorderBy.
GREATER_THAN_OR_EQUAL

The givenfield is greater than or equal to the givenvalue.

Requires:

  • Thatfield come first inorderBy.
EQUALThe givenfield is equal to the givenvalue.
NOT_EQUAL

The givenfield is not equal to the givenvalue.

Requires:

  • No otherNOT_EQUAL,NOT_IN,IS_NOT_NULL, orIS_NOT_NAN.
  • Thatfield comes first in theorderBy.
ARRAY_CONTAINSThe givenfield is an array that contains the givenvalue.
IN

The givenfield is equal to at least one value in the given array.

Requires:

  • Thatvalue is a non-emptyArrayValue, subject to disjunction limits.
  • NoNOT_IN filters in the same query.
ARRAY_CONTAINS_ANY

The givenfield is an array that contains any of the values in the given array.

Requires:

  • Thatvalue is a non-emptyArrayValue, subject to disjunction limits.
  • No otherARRAY_CONTAINS_ANY filters within the same disjunction.
  • NoNOT_IN filters in the same query.
NOT_IN

The value of thefield is not in the given array.

Requires:

  • Thatvalue is a non-emptyArrayValue with at most 10 values.
  • No otherOR,IN,ARRAY_CONTAINS_ANY,NOT_IN,NOT_EQUAL,IS_NOT_NULL, orIS_NOT_NAN.
  • Thatfield comes first in theorderBy.

UnaryFilter

A filter with a single operand.

JSON representation
{"op":enum (Operator),// Union fieldoperand_type can be only one of the following:"field":{object (FieldReference)}// End of list of possible types for union fieldoperand_type.}
Fields
op

enum (Operator)

The unary operator to apply.

Union fieldoperand_type. The argument to the filter.operand_type can be only one of the following:
field

object (FieldReference)

The field to which to apply the operator.

Operator

A unary operator.

Enums
OPERATOR_UNSPECIFIEDUnspecified. This value must not be used.
IS_NANThe givenfield is equal toNaN.
IS_NULLThe givenfield is equal toNULL.
IS_NOT_NAN

The givenfield is not equal toNaN.

Requires:

  • No otherNOT_EQUAL,NOT_IN,IS_NOT_NULL, orIS_NOT_NAN.
  • Thatfield comes first in theorderBy.
IS_NOT_NULL

The givenfield is not equal toNULL.

Requires:

  • A singleNOT_EQUAL,NOT_IN,IS_NOT_NULL, orIS_NOT_NAN.
  • Thatfield comes first in theorderBy.

Order

An order on a field.

JSON representation
{"field":{object (FieldReference)},"direction":enum (Direction)}
Fields
field

object (FieldReference)

The field to order by.

direction

enum (Direction)

The direction to order by. Defaults toASCENDING.

Direction

A sort direction.

Enums
DIRECTION_UNSPECIFIEDUnspecified.
ASCENDINGAscending.
DESCENDINGDescending.

FindNearest

Nearest Neighbors search config. The ordering provided by FindNearest supersedes the orderBy stage. If multiple documents have the same vector distance, the returned document order is not guaranteed to be stable between queries.

JSON representation
{"vectorField":{object (FieldReference)},"queryVector":{object (Value)},"distanceMeasure":enum (DistanceMeasure),"limit":integer,"distanceResultField":string,"distanceThreshold":number}
Fields
vectorField

object (FieldReference)

Required. An indexed vector field to search upon. Only documents which contain vectors whose dimensionality match the queryVector can be returned.

queryVector

object (Value)

Required. The query vector that we are searching on. Must be a vector of no more than 2048 dimensions.

distanceMeasure

enum (DistanceMeasure)

Required. The distance measure to use, required.

limit

integer

Required. The number of nearest neighbors to return. Must be a positive integer of no more than 1000.

distanceResultField

string

Optional. Optional name of the field to output the result of the vector distance calculation. Must conform todocument field name limitations.

distanceThreshold

number

Optional. Option to specify a threshold for which no less similar documents will be returned. The behavior of the specifieddistanceMeasure will affect the meaning of the distance threshold. Since DOT_PRODUCT distances increase when the vectors are more similar, the comparison is inverted.

  • For EUCLIDEAN, COSINE:WHERE distance <= distanceThreshold
  • For DOT_PRODUCT:WHERE distance >= distanceThreshold

DistanceMeasure

The distance measure to use when comparing vectors.

Enums
DISTANCE_MEASURE_UNSPECIFIEDShould not be set.
EUCLIDEANMeasures the EUCLIDEAN distance between the vectors. SeeEuclidean to learn more. The resulting distance decreases the more similar two vectors are.
COSINECOSINE distance compares vectors based on the angle between them, which allows you to measure similarity that isn't based on the vectors magnitude. We recommend using DOT_PRODUCT with unit normalized vectors instead of COSINE distance, which is mathematically equivalent with better performance. SeeCosine Similarity to learn more about COSINE similarity and COSINE distance. The resulting COSINE distance decreases the more similar two vectors are.
DOT_PRODUCTSimilar to cosine but is affected by the magnitude of the vectors. SeeDot Product to learn more. The resulting distance increases the more similar two vectors are.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-06-23 UTC.