FIRFirestore


@interface FIRFirestore : NSObject

FIRFirestore represents a Firestore Database and is the entry point for all Firestore operations.

Initializing

  • Creates, caches, and returns a FIRFirestore using the default FIRApp. Each subsequent invocation returns the same FIRFirestore object.

    Declaration

    Objective-C

    + (nonnull instancetype)firestore;

    Return Value

    The FIRFirestore instance.

  • Creates, caches, and returns a FIRFirestore object for the specified app. Each subsequent invocation returns the same FIRFirestore object.

    Declaration

    Objective-C

    + (nonnull instancetype)firestoreForApp:(nonnull FIRApp *)app;

    Parameters

    app

    The FIRApp instance to use for authentication and as a source of the Google Cloud Project ID for your Firestore Database. If you want the default instance, you should explicitly set it to [FIRApp defaultApp].

    Return Value

    The FIRFirestore instance.

  • Custom settings used to configure this FIRFirestore object.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic) FIRFirestoreSettings *_Nonnull settings;

  • app

    The Firebase App associated with this Firestore instance.

    Declaration

    Objective-C

    @property (readonly, strong, nonatomic) FIRApp *_Nonnull app;

Collections and Documents

Collection Group Queries

  • Creates and returns a new Query that includes all documents in the database that are contained in a collection or subcollection with the given collectionID.

    Declaration

    Objective-C

    - (nonnull FIRQuery *)collectionGroupWithID:(nonnull NSString *)collectionID;

    Parameters

    collectionID

    Identifies the collections to query over. Every collection or subcollection with this ID as the last segment of its path will be included. Cannot contain a slash.

    Return Value

    The created Query.

Transactions and Write Batches

  • Executes the given updateBlock and then attempts to commit the changes applied within an atomic transaction.

    The maximum number of writes allowed in a single transaction is 500, but note that each usage of FieldValue.serverTimestamp(), FieldValue.arrayUnion(), FieldValue.arrayRemove(), or FieldValue.increment() inside a transaction counts as an additional write.

    In the updateBlock, a set of reads and writes can be performed atomically using the FIRTransaction object passed to the block. After the updateBlock is run, Firestore will attempt to apply the changes to the server. If any of the data read has been modified outside of this transaction since being read, then the transaction will be retried by executing the updateBlock again. If the transaction still fails after 5 retries, then the transaction will fail.

    Since the updateBlock may be executed multiple times, it should avoiding doing anything that would cause side effects.

    Any value maybe be returned from the updateBlock. If the transaction is successfully committed, then the completion block will be passed that value. The updateBlock also has an NSError out parameter. If this is set, then the transaction will not attempt to commit, and the given error will be passed to the completion block.

    The FIRTransaction object passed to the updateBlock contains methods for accessing documents and collections. Unlike other firestore access, data accessed with the transaction will not reflect local changes that have not been committed. For this reason, it is required that all reads are performed before any writes. Transactions must be performed while online. Otherwise, reads will fail, the final commit will fail, and the completion block will return an error.

    Declaration

    Objective-C

    - (void)runTransactionWithBlock:
            (nonnull id _Nullable (^)(FIRTransaction *_Nonnull,
                                      NSError *_Nullable *_Nullable))updateBlock
                     completion:
                         (nonnull void (^)(id _Nullable,
                                           NSError *_Nullable))completion;

    Parameters

    updateBlock

    The block to execute within the transaction context.
    completion

    The block to call with the result or error of the transaction. This block will run even if the client is offline, unless the process is killed.

  • Creates a write batch, used for performing multiple writes as a single atomic operation.

    The maximum number of writes allowed in a single batch is 500, but note that each usage of FieldValue.serverTimestamp(), FieldValue.arrayUnion(), FieldValue.arrayRemove(), or FieldValue.increment() inside a batch counts as an additional write.

    Unlike transactions, write batches are persisted offline and therefore are preferable when you don’t need to condition your writes on read data.

    Declaration

    Objective-C

    - (nonnull FIRWriteBatch *)batch;