devsite/tools/jazzy/templates

FirebaseFirestore Framework Reference

FIRQuery


@interface FIRQuery : NSObject

A 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 Firestore instance that created this query (useful for performing transactions, etc.).

    Declaration

    Objective-C

    @property (nonatomic, strong, readonly) FIRFirestore *_Nonnull firestore;

Retrieving Data

  • 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

    Objective-C

    - (void)getDocumentsWithCompletion:
    (nonnull void (^)(FIRQuerySnapshot *_Nullable,
                      NSError *_Nullable))completion;

    Parameters

    completion

    a block to execute once the documents have been successfully read. documentSet will be nil only if error is non-nil.

  • Reads the documents matching this query.

    Declaration

    Objective-C

    - (void)getDocumentsWithSource:(FIRFirestoreSource)source
                    completion:(nonnull void (^)(FIRQuerySnapshot *_Nullable,
                                                 NSError *_Nullable))completion;

    Parameters

    source

    indicates 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).
    completion

    a block to execute once the documents have been successfully read. documentSet will be nil only if error is non-nil.

  • Attaches a listener for QuerySnapshot events.

    Declaration

    Objective-C

    - (nonnull id<FIRListenerRegistration>)addSnapshotListener:
    (nonnull void (^)(FIRQuerySnapshot *_Nullable, NSError *_Nullable))listener;

    Parameters

    listener

    The listener to attach.

    Return Value

    A ListenerRegistration object that can be used to remove this listener.

  • Attaches a listener for QuerySnapshot events.

    Declaration

    Objective-C

    - (nonnull id<FIRListenerRegistration>)
    addSnapshotListenerWithIncludeMetadataChanges:(BOOL)includeMetadataChanges
                                         listener:
                                             (nonnull void (^)(
                                                 FIRQuerySnapshot *_Nullable,
                                                 NSError *_Nullable))listener;

    Parameters

    includeMetadataChanges

    Whether metadata-only changes (i.e. only DocumentSnapshot.metadata changed) should trigger snapshot events.
    listener

    The listener to attach.

    Return Value

    A ListenerRegistration that can be used to remove this listener.

  • Attaches a listener for QuerySnapshot events.

    Declaration

    Objective-C

    - (nonnull id<FIRListenerRegistration>)
    addSnapshotListenerWithOptions:(nonnull FIRSnapshotListenOptions *)options
                          listener:
                              (nonnull void (^)(FIRQuerySnapshot *_Nullable,
                                                NSError *_Nullable))listener;

    Parameters

    options

    Sets 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.
    listener

    The listener to attach.

    Return Value

    A ListenerRegistration that can be used to remove this listener.

Filtering Data

  • Creates and returns a new Query with the additional filter.

    Declaration

    Objective-C

    - (nonnull FIRQuery *)queryWhereFilter:(nonnull FIRFilter *)filter;

    Parameters

    filter

    The new filter to apply to the existing query.

    Return Value

    The newly created Query.

  • Creates and returns a new Query with the additional filter that documents must contain the specified field and the value must be equal to the specified value.

    Declaration

    Objective-C

    - (nonnull FIRQuery *)queryWhereField:(nonnull NSString *)field
                            isEqualTo:(nonnull id)value;

    Parameters

    field

    The name of the field to compare.
    value

    The value the field must be equal to.

    Return Value

    The created Query.

  • Creates and returns a new Query with the additional filter that documents must contain the specified field and the value does not equal the specified value.

    Declaration

    Objective-C

    - (nonnull FIRQuery *)queryWhereFieldPath:(nonnull FIRFieldPath *)path
                             isNotEqualTo:(nonnull id)value;

    Parameters

    path

    The path of the field to compare.
    value

    The value the field must be equal to.

    Return Value

    The created Query.

  • Creates and returns a new Query with the additional filter that documents must contain the specified field and the value does not equal the specified value.

    Declaration

    Objective-C

    - (nonnull FIRQuery *)queryWhereField:(nonnull NSString *)field
                         isNotEqualTo:(nonnull id)value;

    Parameters

    field

    The name of the field to compare.
    value

    The value the field must be equal to.

    Return Value

    The created Query.

  • Creates and returns a new Query with the additional filter that documents must contain the specified field and the value must be equal to the specified value.

    Declaration

    Objective-C

    - (nonnull FIRQuery *)queryWhereFieldPath:(nonnull FIRFieldPath *)path
                                isEqualTo:(nonnull id)value;

    Parameters

    path

    The path of the field to compare.
    value

    The value the field must be equal to.

    Return Value

    The created Query.

  • Creates and returns a new Query with the additional filter that documents must contain the specified field and the value must be less than the specified value.

    Declaration

    Objective-C

    - (nonnull FIRQuery *)queryWhereField:(nonnull NSString *)field
                           isLessThan:(nonnull id)value;

    Parameters

    field

    The name of the field to compare.
    value

    The value the field must be less than.

    Return Value

    The created Query.

  • Creates and returns a new Query with the additional filter that documents must contain the specified field and the value must be less than the specified value.

    Declaration

    Objective-C

    - (nonnull FIRQuery *)queryWhereFieldPath:(nonnull FIRFieldPath *)path
                               isLessThan:(nonnull id)value;

    Parameters

    path

    The path of the field to compare.
    value

    The value the field must be less than.

    Return Value

    The created Query.

  • Creates and returns a new Query with the additional filter that documents must contain the specified field and the value must be less than or equal to the specified value.

    Declaration

    Objective-C

    - (nonnull FIRQuery *)queryWhereField:(nonnull NSString *)field
                  isLessThanOrEqualTo:(nonnull id)value;

    Parameters

    field

    The name of the field to compare
    value

    The value the field must be less than or equal to.

    Return Value

    The created Query.

  • Creates and returns a new Query with the additional filter that documents must contain the specified field and the value must be less than or equal to the specified value.

    Declaration

    Objective-C

    - (nonnull FIRQuery *)queryWhereFieldPath:(nonnull FIRFieldPath *)path
                      isLessThanOrEqualTo:(nonnull id)value;

    Parameters

    path

    The path of the field to compare
    value

    The value the field must be less than or equal to.

    Return Value

    The created Query.

  • Creates and returns a new Query with the additional filter that documents must contain the specified field and the value must greater than the specified value.

    Declaration

    Objective-C

    - (nonnull FIRQuery *)queryWhereField:(nonnull NSString *)field
                        isGreaterThan:(nonnull id)value;

    Parameters

    field

    The name of the field to compare
    value

    The value the field must be greater than.

    Return Value

    The created Query.

  • Creates and returns a new Query with the additional filter that documents must contain the specified field and the value must greater than the specified value.

    Declaration

    Objective-C

    - (nonnull FIRQuery *)queryWhereFieldPath:(nonnull FIRFieldPath *)path
                            isGreaterThan:(nonnull id)value;

    Parameters

    path

    The path of the field to compare
    value

    The value the field must be greater than.

    Return Value

    The created Query.

  • Creates and returns a new Query with the additional filter that documents must contain the specified field and the value must be greater than or equal to the specified value.

    Declaration

    Objective-C

    - (nonnull FIRQuery *)queryWhereField:(nonnull NSString *)field
               isGreaterThanOrEqualTo:(nonnull id)value;

    Parameters

    field

    The name of the field to compare
    value

    The value the field must be greater than.

    Return Value

    The created Query.

  • Creates and returns a new Query with the additional filter that documents must contain the specified field and the value must be greater than or equal to the specified value.

    Declaration

    Objective-C

    - (nonnull FIRQuery *)queryWhereFieldPath:(nonnull FIRFieldPath *)path
                   isGreaterThanOrEqualTo:(nonnull id)value;

    Parameters

    path

    The path of the field to compare
    value

    The value the field must be greater than.

    Return Value

    The created Query.

  • Creates and returns a new Query with 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 arrayContains filter.

    Declaration

    Objective-C

    - (nonnull FIRQuery *)queryWhereField:(nonnull NSString *)field
                        arrayContains:(nonnull id)value;

    Parameters

    field

    The name of the field containing an array to search
    value

    The value that must be contained in the array

    Return Value

    The created Query.

  • Creates and returns a new Query with 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 arrayContains filter.

    Declaration

    Objective-C

    - (nonnull FIRQuery *)queryWhereFieldPath:(nonnull FIRFieldPath *)path
                            arrayContains:(nonnull id)value;

    Parameters

    path

    The path of the field containing an array to search
    value

    The value that must be contained in the array

    Return Value

    The created Query.

  • Creates and returns a new Query with 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 arrayContainsAny filter and it cannot be combined with arrayContains or in filters.

    Declaration

    Objective-C

    - (nonnull FIRQuery *)queryWhereField:(nonnull NSString *)field
                     arrayContainsAny:(nonnull NSArray<id> *)values;

    Parameters

    field

    The name of the field containing an array to search.
    values

    The array that contains the values to match.

    Return Value

    The created Query.

  • Creates and returns a new Query with 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 arrayContainsAny filter and it cannot be combined with arrayContains or in filters.

    Declaration

    Objective-C

    - (nonnull FIRQuery *)queryWhereFieldPath:(nonnull FIRFieldPath *)path
                         arrayContainsAny:(nonnull NSArray<id> *)values;

    Parameters

    path

    The path of the field containing an array to search.
    values

    The array that contains the values to match.

    Return Value

    The created Query.

  • Creates and returns a new Query with 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 in filter, and it cannot be combined with an arrayContainsAny filter.

    Declaration

    Objective-C

    - (nonnull FIRQuery *)queryWhereField:(nonnull NSString *)field
                                   in:(nonnull NSArray<id> *)values;

    Parameters

    field

    The name of the field to search.
    values

    The array that contains the values to match.

    Return Value

    The created Query.

  • Creates and returns a new Query with 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 in filter, and it cannot be combined with an arrayContainsAny filter.

    Declaration

    Objective-C

    - (nonnull FIRQuery *)queryWhereFieldPath:(nonnull FIRFieldPath *)path
                                       in:(nonnull NSArray<id> *)values;

    Parameters

    path

    The path of the field to search.
    values

    The array that contains the values to match.

    Return Value

    The created Query.

  • Creates and returns a new Query with 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 notIn filters cannot match nil values. To query for documents where a field exists and is nil, use a notEqual filter, which can handle this special case.

    A query can have only one notIn filter, and it cannot be combined with an arrayContains, arrayContainsAny, in, or notEqual filter.

    Declaration

    Objective-C

    - (nonnull FIRQuery *)queryWhereField:(nonnull NSString *)field
                                notIn:(nonnull NSArray<id> *)values;

    Parameters

    field

    The name of the field to search.
    values

    The array that contains the values to match.

    Return Value

    The created Query.

  • Creates and returns a new Query with 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 notIn filters cannot match nil values. To query for documents where a field exists and is nil, use a notEqual filter, which can handle this special case.

    Passing in a null value into the values array results in no document matches. To query for documents where a field is not null, use a notEqual filter.

    Declaration

    Objective-C

    - (nonnull FIRQuery *)queryWhereFieldPath:(nonnull FIRFieldPath *)path
                                    notIn:(nonnull NSArray<id> *)values;

    Parameters

    path

    The path of the field to search.
    values

    The array that contains the values to match.

    Return Value

    The created Query.

  • Creates and returns a new Query with the additional filter that documents must satisfy the specified predicate.

    Declaration

    Objective-C

    - (nonnull FIRQuery *)queryFilteredUsingPredicate:
    (nonnull NSPredicate *)predicate;

    Parameters

    predicate

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

Sorting Data

  • Creates and returns a new Query that’s additionally sorted by the specified field.

    Declaration

    Objective-C

    - (nonnull FIRQuery *)queryOrderedByField:(nonnull NSString *)field;

    Parameters

    field

    The field to sort by.

    Return Value

    The created Query.

  • Creates and returns a new Query that’s additionally sorted by the specified field.

    Declaration

    Objective-C

    - (nonnull FIRQuery *)queryOrderedByFieldPath:(nonnull FIRFieldPath *)path;

    Parameters

    path

    The field to sort by.

    Return Value

    The created Query.

  • Creates and returns a new Query that’s additionally sorted by the specified field, optionally in descending order instead of ascending.

    Declaration

    Objective-C

    - (nonnull FIRQuery *)queryOrderedByField:(nonnull NSString *)field
                               descending:(BOOL)descending;

    Parameters

    field

    The field to sort by.
    descending

    Whether to sort descending.

    Return Value

    The created Query.

  • Creates and returns a new Query that’s additionally sorted by the specified field, optionally in descending order instead of ascending.

    Declaration

    Objective-C

    - (nonnull FIRQuery *)queryOrderedByFieldPath:(nonnull FIRFieldPath *)path
                                   descending:(BOOL)descending;

    Parameters

    path

    The field to sort by.
    descending

    Whether to sort descending.

    Return Value

    The created Query.

Limiting Data

  • Creates and returns a new Query that only returns the first matching documents up to the specified number.

    Declaration

    Objective-C

    - (nonnull FIRQuery *)queryLimitedTo:(NSInteger)limit;

    Parameters

    limit

    The maximum number of items to return.

    Return Value

    The created Query.

  • Creates and returns a new Query that only returns the last matching documents up to the specified number.

    A query with a limit(toLast:) clause must have at least one orderBy clause.

    Declaration

    Objective-C

    - (nonnull FIRQuery *)queryLimitedToLast:(NSInteger)limit;

    Parameters

    limit

    The maximum number of items to return.

    Return Value

    The created Query.

Choosing Endpoints

  • Creates and returns a new Query that 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

    Objective-C

    - (nonnull FIRQuery *)queryStartingAtDocument:
    (nonnull FIRDocumentSnapshot *)document;

    Parameters

    document

    The snapshot of the document to start at.

    Return Value

    The created Query.

  • Creates and returns a new Query that 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

    Objective-C

    - (nonnull FIRQuery *)queryStartingAtValues:(nonnull NSArray *)fieldValues;

    Parameters

    fieldValues

    The 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 Query that 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

    Objective-C

    - (nonnull FIRQuery *)queryStartingAfterDocument:
    (nonnull FIRDocumentSnapshot *)document;

    Parameters

    document

    The snapshot of the document to start after.

    Return Value

    The created Query.

  • Creates and returns a new Query that 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

    Objective-C

    - (nonnull FIRQuery *)queryStartingAfterValues:(nonnull NSArray *)fieldValues;

    Parameters

    fieldValues

    The field values to start this query after, in order of the query’s orderBy.

    Return Value

    The created Query.

  • Creates and returns a new Query that 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

    Objective-C

    - (nonnull FIRQuery *)queryEndingBeforeDocument:
    (nonnull FIRDocumentSnapshot *)document;

    Parameters

    document

    The snapshot of the document to end before.

    Return Value

    The created Query.

  • Creates and returns a new Query that 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

    Objective-C

    - (nonnull FIRQuery *)queryEndingBeforeValues:(nonnull NSArray *)fieldValues;

    Parameters

    fieldValues

    The 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 Query that 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

    Objective-C

    - (nonnull FIRQuery *)queryEndingAtDocument:
    (nonnull FIRDocumentSnapshot *)document;

    Parameters

    document

    The snapshot of the document to end at.

    Return Value

    The created Query.

  • Creates and returns a new Query that 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

    Objective-C

    - (nonnull FIRQuery *)queryEndingAtValues:(nonnull NSArray *)fieldValues;

    Parameters

    fieldValues

    The field values to end this query at, in order of the query’s order by.

    Return Value

    The created Query.

Aggregation

  • A query that counts the documents in the result set of this query without actually downloading the documents.

    Using this AggregateQuery to count the documents is efficient because only the final count, not the documents’ data, is downloaded. The AggregateQuery can count the documents in cases where the result set is prohibitively large to download entirely (thousands of documents).

    Declaration

    Objective-C

    @property (nonatomic, readonly) FIRAggregateQuery *_Nonnull count;

  • Creates and returns a new AggregateQuery that aggregates the documents in the result set of this query without actually downloading the documents.

    Using an AggregateQuery to perform aggregations is efficient because only the final aggregation values, not the documents’ data, is downloaded. The returned AggregateQuery can perform aggregations of the documents in cases where the result set is prohibitively large to download entirely (thousands of documents).

    Declaration

    Objective-C

    - (nonnull FIRAggregateQuery *)aggregate:
    (nonnull NSArray<FIRAggregateField *> *)aggregateFields;

    Parameters

    aggregateFields

    Specifies the aggregate operations to perform on the result set of this query.

    Return Value

    An AggregateQuery encapsulating this Query and AggregateFields, which can be used to query the server for the aggregation results.