Query
class Query : NSObject, @unchecked SendableA Query refers to a query which you can read or listen to. You can also construct
refined Query objects by adding filters and ordering.
-
The
Firestoreinstance that created this query (useful for performing transactions, etc.).Declaration
Swift
var firestore: FIRFirestore { get }
-
Reads the documents matching this query.
This method attempts to provide up-to-date data when possible by waiting for data from the server, but it may return cached data or fail if you are offline and the server cannot be reached. See the
getDocuments(source:completion:)method to change this behavior.Declaration
Swift
func getDocuments() async throws -> FIRQuerySnapshotParameters
completiona block to execute once the documents have been successfully read. documentSet will be
nilonly if error isnon-nil. -
Reads the documents matching this query.
Declaration
Swift
func getDocuments(source: FirestoreSource) async throws -> FIRQuerySnapshotParameters
sourceindicates whether the results should be fetched from the cache only (
Source.cache), the server only (Source.server), or to attempt the server and fall back to the cache (Source.default).completiona block to execute once the documents have been successfully read. documentSet will be
nilonly if error isnon-nil. -
Attaches a listener for
QuerySnapshotevents.Declaration
Swift
func addSnapshotListener(_ listener: @escaping (FIRQuerySnapshot?, (any Error)?) -> Void) -> any ListenerRegistrationParameters
listenerThe listener to attach.
Return Value
A
ListenerRegistrationobject that can be used to remove this listener. -
Attaches a listener for
QuerySnapshotevents.Declaration
Swift
func addSnapshotListener(includeMetadataChanges: Bool, listener: @escaping (FIRQuerySnapshot?, (any Error)?) -> Void) -> any ListenerRegistrationParameters
includeMetadataChangesWhether metadata-only changes (i.e. only
DocumentSnapshot.metadatachanged) should trigger snapshot events.listenerThe listener to attach.
Return Value
A
ListenerRegistrationthat can be used to remove this listener. -
Attaches a listener for
QuerySnapshotevents.Declaration
Swift
func addSnapshotListener(options: SnapshotListenOptions, listener: @escaping (FIRQuerySnapshot?, (any Error)?) -> Void) -> any ListenerRegistrationParameters
optionsSets snapshot listener options, including whether metadata-only changes should trigger snapshot events, the source to listen to, the executor to use to call the listener, or the activity to scope the listener to.
listenerThe listener to attach.
Return Value
A
ListenerRegistrationthat can be used to remove this listener.
-
Creates and returns a new Query with the additional filter.
Declaration
Swift
func whereFilter(_ filter: FIRFilter) -> QueryParameters
filterThe new filter to apply to the existing query.
Return Value
The newly created Query.
-
Creates and returns a new
Querywith the additional filter that documents must contain the specified field and the value must be equal to the specified value.Declaration
Swift
func whereField(_ field: String, isEqualTo value: Any) -> QueryParameters
fieldThe name of the field to compare.
valueThe value the field must be equal to.
Return Value
The created
Query. -
Creates and returns a new
Querywith the additional filter that documents must contain the specified field and the value does not equal the specified value.Declaration
Swift
func whereField(_ path: FIRFieldPath, isNotEqualTo value: Any) -> QueryParameters
pathThe path of the field to compare.
valueThe value the field must be equal to.
Return Value
The created
Query. -
Creates and returns a new
Querywith the additional filter that documents must contain the specified field and the value does not equal the specified value.Declaration
Swift
func whereField(_ field: String, isNotEqualTo value: Any) -> QueryParameters
fieldThe name of the field to compare.
valueThe value the field must be equal to.
Return Value
The created
Query. -
Creates and returns a new
Querywith the additional filter that documents must contain the specified field and the value must be equal to the specified value.Declaration
Swift
func whereField(_ path: FIRFieldPath, isEqualTo value: Any) -> QueryParameters
pathThe path of the field to compare.
valueThe value the field must be equal to.
Return Value
The created
Query. -
Creates and returns a new
Querywith the additional filter that documents must contain the specified field and the value must be less than the specified value.Declaration
Swift
func whereField(_ field: String, isLessThan value: Any) -> QueryParameters
fieldThe name of the field to compare.
valueThe value the field must be less than.
Return Value
The created
Query. -
Creates and returns a new
Querywith the additional filter that documents must contain the specified field and the value must be less than the specified value.Declaration
Swift
func whereField(_ path: FIRFieldPath, isLessThan value: Any) -> QueryParameters
pathThe path of the field to compare.
valueThe value the field must be less than.
Return Value
The created
Query. -
Creates and returns a new
Querywith the additional filter that documents must contain the specified field and the value must be less than or equal to the specified value.Declaration
Swift
func whereField(_ field: String, isLessThanOrEqualTo value: Any) -> QueryParameters
fieldThe name of the field to compare
valueThe value the field must be less than or equal to.
Return Value
The created
Query. -
Creates and returns a new
Querywith the additional filter that documents must contain the specified field and the value must be less than or equal to the specified value.Declaration
Swift
func whereField(_ path: FIRFieldPath, isLessThanOrEqualTo value: Any) -> QueryParameters
pathThe path of the field to compare
valueThe value the field must be less than or equal to.
Return Value
The created
Query. -
Creates and returns a new
Querywith the additional filter that documents must contain the specified field and the value must greater than the specified value.Declaration
Swift
func whereField(_ field: String, isGreaterThan value: Any) -> QueryParameters
fieldThe name of the field to compare
valueThe value the field must be greater than.
Return Value
The created
Query. -
Creates and returns a new
Querywith the additional filter that documents must contain the specified field and the value must greater than the specified value.Declaration
Swift
func whereField(_ path: FIRFieldPath, isGreaterThan value: Any) -> QueryParameters
pathThe path of the field to compare
valueThe value the field must be greater than.
Return Value
The created
Query. -
Creates and returns a new
Querywith the additional filter that documents must contain the specified field and the value must be greater than or equal to the specified value.Declaration
Swift
func whereField(_ field: String, isGreaterThanOrEqualTo value: Any) -> QueryParameters
fieldThe name of the field to compare
valueThe value the field must be greater than.
Return Value
The created
Query. -
Creates and returns a new
Querywith the additional filter that documents must contain the specified field and the value must be greater than or equal to the specified value.Declaration
Swift
func whereField(_ path: FIRFieldPath, isGreaterThanOrEqualTo value: Any) -> QueryParameters
pathThe path of the field to compare
valueThe value the field must be greater than.
Return Value
The created
Query. -
Creates and returns a new
Querywith the additional filter that documents must contain the specified field, it must be an array, and the array must contain the provided value.A query can have only one
arrayContainsfilter.Declaration
Swift
func whereField(_ field: String, arrayContains value: Any) -> QueryParameters
fieldThe name of the field containing an array to search
valueThe value that must be contained in the array
Return Value
The created
Query. -
Creates and returns a new
Querywith the additional filter that documents must contain the specified field, it must be an array, and the array must contain the provided value.A query can have only one
arrayContainsfilter.Declaration
Swift
func whereField(_ path: FIRFieldPath, arrayContains value: Any) -> QueryParameters
pathThe path of the field containing an array to search
valueThe value that must be contained in the array
Return Value
The created
Query. -
Creates and returns a new
Querywith the additional filter that documents must contain the specified field, the value must be an array, and that array must contain at least one value from the provided array.A query can have only one
arrayContainsAnyfilter and it cannot be combined witharrayContainsorinfilters.Declaration
Swift
func whereField(_ field: String, arrayContainsAny values: [Any]) -> QueryParameters
fieldThe name of the field containing an array to search.
valuesThe array that contains the values to match.
Return Value
The created
Query. -
Creates and returns a new
Querywith the additional filter that documents must contain the specified field, the value must be an array, and that array must contain at least one value from the provided array.A query can have only one
arrayContainsAnyfilter and it cannot be combined witharrayContainsorinfilters.Declaration
Swift
func whereField(_ path: FIRFieldPath, arrayContainsAny values: [Any]) -> QueryParameters
pathThe path of the field containing an array to search.
valuesThe array that contains the values to match.
Return Value
The created
Query. -
Creates and returns a new
Querywith the additional filter that documents must contain the specified field and the value must equal one of the values from the provided array.A query can have only one
infilter, and it cannot be combined with anarrayContainsAnyfilter.Declaration
Swift
func whereField(_ field: String, in values: [Any]) -> QueryParameters
fieldThe name of the field to search.
valuesThe array that contains the values to match.
Return Value
The created
Query. -
Creates and returns a new
Querywith the additional filter that documents must contain the specified field and the value must equal one of the values from the provided array.A query can have only one
infilter, and it cannot be combined with anarrayContainsAnyfilter.Declaration
Swift
func whereField(_ path: FIRFieldPath, in values: [Any]) -> QueryParameters
pathThe path of the field to search.
valuesThe array that contains the values to match.
Return Value
The created
Query. -
Creates and returns a new
Querywith the additional filter that documents must contain the specified field and the value does not equal any of the values from the provided array.One special case is that
notInfilters cannot matchnilvalues. To query for documents where a field exists and isnil, use anotEqualfilter, which can handle this special case.A query can have only one
notInfilter, and it cannot be combined with anarrayContains,arrayContainsAny,in, ornotEqualfilter.Declaration
Swift
func whereField(_ field: String, notIn values: [Any]) -> QueryParameters
fieldThe name of the field to search.
valuesThe array that contains the values to match.
Return Value
The created
Query. -
Creates and returns a new
Querywith the additional filter that documents must contain the specified field and the value does not equal any of the values from the provided array.One special case is that
notInfilters cannot matchnilvalues. To query for documents where a field exists and isnil, use anotEqualfilter, which can handle this special case.Passing in a
nullvalue into thevaluesarray results in no document matches. To query for documents where a field is notnull, use anotEqualfilter.Declaration
Swift
func whereField(_ path: FIRFieldPath, notIn values: [Any]) -> QueryParameters
pathThe path of the field to search.
valuesThe array that contains the values to match.
Return Value
The created
Query. -
Creates and returns a new
Querywith the additional filter that documents must satisfy the specified predicate.Declaration
Swift
func filter(using predicate: NSPredicate) -> QueryParameters
predicateThe predicate the document must satisfy. Can be either comparison or compound of comparison. In particular, block-based predicate is not supported.
Return Value
The created
Query.
-
Creates and returns a new
Querythat’s additionally sorted by the specified field.Declaration
Swift
func order(by field: String) -> QueryParameters
fieldThe field to sort by.
Return Value
The created
Query. -
Creates and returns a new
Querythat’s additionally sorted by the specified field.Declaration
Swift
func order(by path: FIRFieldPath) -> QueryParameters
pathThe field to sort by.
Return Value
The created
Query. -
Creates and returns a new
Querythat’s additionally sorted by the specified field, optionally in descending order instead of ascending.Declaration
Swift
func order(by field: String, descending: Bool) -> QueryParameters
fieldThe field to sort by.
descendingWhether to sort descending.
Return Value
The created
Query. -
Creates and returns a new
Querythat’s additionally sorted by the specified field, optionally in descending order instead of ascending.Declaration
Swift
func order(by path: FIRFieldPath, descending: Bool) -> QueryParameters
pathThe field to sort by.
descendingWhether to sort descending.
Return Value
The created
Query.
-
Creates and returns a new
Querythat only returns the first matching documents up to the specified number.Declaration
Swift
func limit(to limit: Int) -> QueryParameters
limitThe maximum number of items to return.
Return Value
The created
Query. -
Creates and returns a new
Querythat only returns the last matching documents up to the specified number.A query with a
limit(toLast:)clause must have at least oneorderByclause.Declaration
Swift
func limit(toLast limit: Int) -> QueryParameters
limitThe maximum number of items to return.
Return Value
The created
Query.
-
Creates and returns a new
Querythat starts at the provided document (inclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of this query.Declaration
Swift
func start(atDocument document: FIRDocumentSnapshot) -> QueryParameters
documentThe snapshot of the document to start at.
Return Value
The created
Query. -
Creates and returns a new
Querythat starts at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query.Declaration
Swift
func start(at fieldValues: [Any]) -> QueryParameters
fieldValuesThe field values to start this query at, in order of the query’s order by.
Return Value
The created
Query. -
Creates and returns a new
Querythat starts after the provided document (exclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of this query.Declaration
Swift
func start(afterDocument document: FIRDocumentSnapshot) -> QueryParameters
documentThe snapshot of the document to start after.
Return Value
The created
Query. -
Creates and returns a new
Querythat starts after the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query.Declaration
Swift
func start(after fieldValues: [Any]) -> QueryParameters
fieldValuesThe field values to start this query after, in order of the query’s orderBy.
Return Value
The created
Query. -
Creates and returns a new
Querythat ends before the provided document (exclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of this query.Declaration
Swift
func end(beforeDocument document: FIRDocumentSnapshot) -> QueryParameters
documentThe snapshot of the document to end before.
Return Value
The created
Query. -
Creates and returns a new
Querythat ends before the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query.Declaration
Swift
func end(before fieldValues: [Any]) -> QueryParameters
fieldValuesThe field values to end this query before, in order of the query’s order by.
Return Value
The created
Query. -
Creates and returns a new
Querythat ends at the provided document (exclusive). The end position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of this query.Declaration
Swift
func end(atDocument document: FIRDocumentSnapshot) -> QueryParameters
documentThe snapshot of the document to end at.
Return Value
The created
Query. -
Creates and returns a new
Querythat ends at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query.Declaration
Swift
func end(at fieldValues: [Any]) -> QueryParameters
fieldValuesThe field values to end this query at, in order of the query’s order by.
Return Value
The created
Query.
-
A query that counts the documents in the result set of this query without actually downloading the documents.
Using this
AggregateQueryto count the documents is efficient because only the final count, not the documents’ data, is downloaded. TheAggregateQuerycan count the documents in cases where the result set is prohibitively large to download entirely (thousands of documents).Declaration
Swift
var count: FIRAggregateQuery { get } -
Creates and returns a new
AggregateQuerythat aggregates the documents in the result set of this query without actually downloading the documents.Using an
AggregateQueryto perform aggregations is efficient because only the final aggregation values, not the documents’ data, is downloaded. The returnedAggregateQuerycan perform aggregations of the documents in cases where the result set is prohibitively large to download entirely (thousands of documents).Declaration
Swift
func aggregate(_ aggregateFields: [FIRAggregateField]) -> FIRAggregateQueryParameters
aggregateFieldsSpecifies the aggregate operations to perform on the result set of this query.
Return Value
An
AggregateQueryencapsulating thisQueryandAggregateFields, which can be used to query the server for the aggregation results.