StructuredQuery

A Firestore query.

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

object(Projection)

The projection to return.

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 guarantees a stable ordering through the following rules:

  • Any field required to appear in orderBy, that is not already specified in orderBy, is appended to the order in field name order by default.
  • 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:

  • SELECT * FROM Foo ORDER BY A becomes SELECT * FROM Foo ORDER BY A, __name__
  • SELECT * FROM Foo ORDER BY A DESC becomes SELECT * FROM Foo ORDER BY A DESC, __name__ DESC
  • SELECT * FROM Foo WHERE A > 1 becomes SELECT * FROM Foo WHERE A > 1 ORDER BY A, __name__
startAt

object(Cursor)

A starting point for the query results.

endAt

object(Cursor)

A end point for the query results.

offset

number

The number of results to skip.

Applies before limit, but after all other constraints. Must be >= 0 if specified.
limit

number

The maximum number of results to return.

Applies after all other constraints. Must be >= 0 if specified.

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__'].

FieldReference

A reference to a field, such as max(messages.time) as max_time.

JSON representation 
{
  "fieldPath": string
}
Fields
fieldPath

string

CollectionSelector

A selection of a collection, such as messages 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 the parent specified in the containing RunQueryRequest. When true, selects all descendant collections.

Filter

A filter.

JSON representation 
{

  // Union field filter_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 field filter_type.
}
Fields
Union field filter_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. Must contain at least one filter.

Operator

A composite filter operator.

Enums
OPERATOR_UNSPECIFIED Unspecified. This value must not be used.
AND The results are required to satisfy each 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_UNSPECIFIED Unspecified. This value must not be used.
LESS_THAN Less than. Requires that the field come first in orderBy.
LESS_THAN_OR_EQUAL Less than or equal. Requires that the field come first in orderBy.
GREATER_THAN Greater than. Requires that the field come first in orderBy.
GREATER_THAN_OR_EQUAL Greater than or equal. Requires that the field come first in orderBy.
EQUAL Equal.
ARRAY_CONTAINS Contains. Requires that the field is an array.

UnaryFilter

A filter with a single operand.

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

enum(Operator)

The unary operator to apply.

field

object(FieldReference)

The field to which to apply the operator.

Operator

A unary operator.

Enums
OPERATOR_UNSPECIFIED Unspecified. This value must not be used.
IS_NAN Test if a field is equal to NaN.
IS_NULL Test if an exprestion evaluates to Null.

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 to ASCENDING.

Direction

A sort direction.

Enums
DIRECTION_UNSPECIFIED Unspecified.
ASCENDING Ascending.
DESCENDING Descending.

Cursor

A position in a query result set.

JSON representation 
{
  "values": [
    {
      object(Value)
    }
  ],
  "before": boolean
}
Fields
values[]

object(Value)

The values that represent a position, in the order they appear in the order by clause of a query.

Can contain fewer values than specified in the order by clause.
before

boolean

If the position is just before or just after the given values, relative to the sort order defined by the query.

Was this page helpful? Let us know how we did:

Send feedback about...

This page
Documentation feedback
Cloud Firestore
Product feedback