YapDatabaseReadTransaction

@interface YapDatabaseReadTransaction : NSObject

A YapDatabaseReadTransaction encompasses a single read-only database transaction. You can execute multiple operations within a single transaction.

A transaction allows you to safely access the database as needed in a thread-safe and optimized manner.

  • Transactions are light-weight objects created by connections.

    Connections are the parent objects of transactions. Connections own the transaction objects.

    Transactions store nearly all their state in the parent connection object. This reduces the memory requirements for transactions objects, and reduces the overhead associated in creating them.

    Declaration

    Objective-C

    @property (readonly, assign, nonatomic)
    YapDatabaseConnection *_Nonnull connection;

    Swift

    unowned(unsafe) var connection: YapDatabaseConnection { get }

  • The userInfo property allows arbitrary info to be associated with the transaction. This propery is not used by YapDatabaseTransaction in any way.

    Keep in mind that transactions are short lived objects. Each transaction is a new/different transaction object.

    Declaration

    Objective-C

    @property (readwrite, strong, nonatomic, nullable) id userInfo;

    Swift

    var userInfo: Any? { get set }

Count

  • Returns the total number of collections. Each collection may have 1 or more key/object pairs.

    Declaration

    Objective-C

    - (NSUInteger)numberOfCollections;

    Swift

    func numberOfCollections() -> UInt

  • Returns the total number of keys in the given collection. Returns zero if the collection doesn’t exist (or all key/object pairs from the collection have been removed).

    Declaration

    Objective-C

    - (NSUInteger)numberOfKeysInCollection:(nullable NSString *)collection;

    Swift

    func numberOfKeys(inCollection collection: String?) -> UInt

  • Returns the total number of key/object pairs in the entire database (including all collections).

    Declaration

    Objective-C

    - (NSUInteger)numberOfKeysInAllCollections;

    Swift

    func numberOfKeysInAllCollections() -> UInt

List

  • Returns a list of all collection names.

    If the list of collections is really big, it may be more efficient to enumerate them instead.

    See

    enumerateCollectionsUsingBlock:

    Declaration

    Objective-C

    - (nonnull NSArray<NSString *> *)allCollections;

    Swift

    func allCollections() -> [String]

  • Returns a list of all keys in the given collection.

    If the list of keys is really big, it may be more efficient to enumerate them instead.

    See

    enumerateKeysInCollection:usingBlock:

    Declaration

    Objective-C

    - (nonnull NSArray<NSString *> *)allKeysInCollection:
    (nullable NSString *)collection;

    Swift

    func allKeys(inCollection collection: String?) -> [String]

Object & Metadata

  • Returns whether or not the given key/collection exists in the database.

    Declaration

    Objective-C

    - (BOOL)hasObjectForKey:(nonnull NSString *)key
           inCollection:(nullable NSString *)collection;

    Swift

    func hasObject(forKey key: String, inCollection collection: String?) -> Bool

  • Object access. Objects are automatically deserialized using database’s configured deserializer.

    Declaration

    Objective-C

    - (nullable id)objectForKey:(nonnull NSString *)key
               inCollection:(nullable NSString *)collection;

    Swift

    func object(forKey key: String, inCollection collection: String?) -> Any?

  • Returns the metadata associated with the {collection, key} tuple. If the item is cached in memory, it’s immediately returned. Otherwise the item is fetched from disk and deserialized.

    Declaration

    Objective-C

    - (nullable id)metadataForKey:(nonnull NSString *)key
                 inCollection:(nullable NSString *)collection;

    Swift

    func metadata(forKey key: String, inCollection collection: String?) -> Any?

  • Provides access to both object and metadata in a single call.

    Declaration

    Objective-C

    - (BOOL)getObject:(id _Nullable *_Nullable)objectPtr
         metadata:(id _Nullable *_Nullable)metadataPtr
           forKey:(nonnull NSString *)key
     inCollection:(nullable NSString *)collection;

    Swift

    func __getObject(_ objectPtr: AutoreleasingUnsafeMutablePointer<AnyObject?>?, metadata metadataPtr: AutoreleasingUnsafeMutablePointer<AnyObject?>?, forKey key: String, inCollection collection: String?) -> Bool

    Return Value

    YES if the key exists in the database. NO otherwise, in which case both object and metadata will be nil.

Primitive

  • Primitive access. This method is available in-case you have a need to fetch the raw serializedObject from the database.

    This method is slower than objectForKey:inCollection:, since that method makes use of the objectCache. In contrast, this method always fetches the raw data from disk.

    See

    objectForKey:inCollection:

    Declaration

    Objective-C

    - (nullable NSData *)serializedObjectForKey:(nonnull NSString *)key
                               inCollection:(nullable NSString *)collection;

    Swift

    func serializedObject(forKey key: String, inCollection collection: String?) -> Data?

  • Primitive access. This method is available in-case you have a need to fetch the raw serializedMetadata from the database.

    This method is slower than metadataForKey:inCollection:, since that method makes use of the metadataCache. In contrast, this method always fetches the raw data from disk.

    See

    metadataForKey:inCollection:

    Declaration

    Objective-C

    - (nullable NSData *)serializedMetadataForKey:(nonnull NSString *)key
                                 inCollection:(nullable NSString *)collection;

    Swift

    func serializedMetadata(forKey key: String, inCollection collection: String?) -> Data?

  • Primitive access. This method is available in-case you have a need to fetch the raw serialized forms from the database.

    This method is slower than getObject:metadata:forKey:inCollection:, since that method makes use of the caches. In contrast, this method always fetches the raw data from disk.

    See

    getObject:metadata:forKey:inCollection:

    Declaration

    Objective-C

    - (BOOL)getSerializedObject:(NSData *_Nullable *_Nullable)serializedObjectPtr
         serializedMetadata:(NSData *_Nullable *_Nullable)serializedMetadataPtr
                     forKey:(nonnull NSString *)key
               inCollection:(nullable NSString *)collection;

    Swift

    func getSerializedObject(_ serializedObjectPtr: AutoreleasingUnsafeMutablePointer<NSData?>?, serializedMetadata serializedMetadataPtr: AutoreleasingUnsafeMutablePointer<NSData?>?, forKey key: String, inCollection collection: String?) -> Bool

Enumerate

  • Fast enumeration over all the collections in the database.

    This uses a SELECT collection FROM database operation, and then steps over the results invoking the given block handler.

    Declaration

    Objective-C

    - (void)enumerateCollectionsUsingBlock:(nonnull void (^)(NSString *_Nonnull,
                                                         BOOL *_Nonnull))block;

    Swift

    func __enumerateCollections(_ block: (String, UnsafeMutablePointer<ObjCBool>) -> Void)

  • This method is rarely needed, but may be helpful in certain situations.

    This method may be used if you have the key, but not the collection for a particular item. Please note that this is not the ideal situation.

    Since there may be numerous collections for a given key, this method enumerates all possible collections.

    Declaration

    Objective-C

    - (void)enumerateCollectionsForKey:(nonnull NSString *)key
                        usingBlock:(nonnull void (^)(NSString *_Nonnull,
                                                     BOOL *_Nonnull))block;

    Swift

    func enumerateCollections(forKey key: String, using block: (String, UnsafeMutablePointer<ObjCBool>) -> Void)

  • Fast enumeration over all keys in the given collection.

    This uses a SELECT key FROM database WHERE collection = ? operation, and then steps over the results invoking the given block handler.

    Declaration

    Objective-C

    - (void)enumerateKeysInCollection:(nullable NSString *)collection
                       usingBlock:(nonnull void (^)(NSString *_Nonnull,
                                                    BOOL *_Nonnull))block;

    Swift

    func __enumerateKeys(inCollection collection: String?, using block: (String, UnsafeMutablePointer<ObjCBool>) -> Void)

  • Fast enumeration over all keys in the given collection.

    This uses a SELECT collection, key FROM database operation, and then steps over the results invoking the given block handler.

    Declaration

    Objective-C

    - (void)enumerateKeysInAllCollectionsUsingBlock:
    (nonnull void (^)(NSString *_Nonnull, NSString *_Nonnull,
                      BOOL *_Nonnull))block;

    Swift

    func __enumerateKeysInAllCollections(_ block: (String, String, UnsafeMutablePointer<ObjCBool>) -> Void)

  • Fast enumeration over all objects in the database.

    This uses a SELECT key, object from database WHERE collection = ? operation, and then steps over the results, deserializing each object, and then invoking the given block handler.

    If you only need to enumerate over certain objects (e.g. keys with a particular prefix), consider using the alternative version below which provides a filter, allowing you to skip the serialization step for those objects you’re not interested in.

    Declaration

    Objective-C

    - (void)enumerateKeysAndObjectsInCollection:(nullable NSString *)collection
                                 usingBlock:
                                     (nonnull void (^)(NSString *_Nonnull,
                                                       id _Nonnull,
                                                       BOOL *_Nonnull))block;

    Swift

    func __enumerateKeysAndObjects(inCollection collection: String?, using block: (String, Any, UnsafeMutablePointer<ObjCBool>) -> Void)

  • Fast enumeration over objects in the database for which you’re interested in. The filter block allows you to decide which objects you’re interested in.

    From the filter block, simply return YES if you’d like the block handler to be invoked for the given key. If the filter block returns NO, then the block handler is skipped for the given key, which avoids the cost associated with deserializing the object.

    Declaration

    Objective-C

    - (void)
    enumerateKeysAndObjectsInCollection:(nullable NSString *)collection
                             usingBlock:(nonnull void (^)(NSString *_Nonnull,
                                                          id _Nonnull,
                                                          BOOL *_Nonnull))block
                             withFilter:
                                 (nullable BOOL (^)(NSString *_Nonnull))filter;

    Swift

    func __enumerateKeysAndObjects(inCollection collection: String?, using block: (String, Any, UnsafeMutablePointer<ObjCBool>) -> Void, withFilter filter: ((String) -> Bool)? = nil)

  • Enumerates all key/object pairs in all collections.

    The enumeration is sorted by collection. That is, it will enumerate fully over a single collection before moving onto another collection.

    If you only need to enumerate over certain objects (e.g. subset of collections, or keys with a particular prefix), consider using the alternative version below which provides a filter, allowing you to skip the serialization step for those objects you’re not interested in.

    Declaration

    Objective-C

    - (void)enumerateKeysAndObjectsInAllCollectionsUsingBlock:
    (nonnull void (^)(NSString *_Nonnull, NSString *_Nonnull, id _Nonnull,
                      BOOL *_Nonnull))block;

    Swift

    func __enumerateKeysAndObjectsInAllCollections(_ block: (String, String, Any, UnsafeMutablePointer<ObjCBool>) -> Void)

  • Enumerates all key/object pairs in all collections. The filter block allows you to decide which objects you’re interested in.

    The enumeration is sorted by collection. That is, it will enumerate fully over a single collection before moving onto another collection.

    From the filter block, simply return YES if you’d like the block handler to be invoked for the given collection/key pair. If the filter block returns NO, then the block handler is skipped for the given pair, which avoids the cost associated with deserializing the object.

    Declaration

    Objective-C

    - (void)enumerateKeysAndObjectsInAllCollectionsUsingBlock:
            (nonnull void (^)(NSString *_Nonnull, NSString *_Nonnull,
                              id _Nonnull, BOOL *_Nonnull))block
                                               withFilter:
                                                   (nullable BOOL (^)(
                                                       NSString *_Nonnull,
                                                       NSString *_Nonnull))
                                                       filter;

    Swift

    func __enumerateKeysAndObjectsInAllCollections(_ block: (String, String, Any, UnsafeMutablePointer<ObjCBool>) -> Void, withFilter filter: ((String, String) -> Bool)? = nil)

  • Fast enumeration over all keys and associated metadata in the given collection.

    This uses a SELECT key, metadata FROM database WHERE collection = ? operation and steps over the results.

    If you only need to enumerate over certain items (e.g. keys with a particular prefix), consider using the alternative version below which provides a filter, allowing you to skip the deserialization step for those items you’re not interested in.

    Keep in mind that you cannot modify the collection mid-enumeration (just like any other kind of enumeration).

    Declaration

    Objective-C

    - (void)enumerateKeysAndMetadataInCollection:(nullable NSString *)collection
                                  usingBlock:
                                      (nonnull void (^)(NSString *_Nonnull,
                                                        id _Nullable,
                                                        BOOL *_Nonnull))block;

    Swift

    func __enumerateKeysAndMetadata(inCollection collection: String?, using block: (String, Any?, UnsafeMutablePointer<ObjCBool>) -> Void)

  • Fast enumeration over all keys and associated metadata in the given collection.

    From the filter block, simply return YES if you’d like the block handler to be invoked for the given key. If the filter block returns NO, then the block handler is skipped for the given key, which avoids the cost associated with deserializing the object.

    Keep in mind that you cannot modify the collection mid-enumeration (just like any other kind of enumeration).

    Declaration

    Objective-C

    - (void)
    enumerateKeysAndMetadataInCollection:(nullable NSString *)collection
                              usingBlock:(nonnull void (^)(NSString *_Nonnull,
                                                           id _Nullable,
                                                           BOOL *_Nonnull))block
                              withFilter:
                                  (nullable BOOL (^)(NSString *_Nonnull))filter;

    Swift

    func __enumerateKeysAndMetadata(inCollection collection: String?, using block: (String, Any?, UnsafeMutablePointer<ObjCBool>) -> Void, withFilter filter: ((String) -> Bool)? = nil)

  • Fast enumeration over all key/metadata pairs in all collections.

    This uses a SELECT metadata FROM database ORDER BY collection ASC operation, and steps over the results.

    If you only need to enumerate over certain objects (e.g. keys with a particular prefix), consider using the alternative version below which provides a filter, allowing you to skip the deserialization step for those objects you’re not interested in.

    Keep in mind that you cannot modify the database mid-enumeration (just like any other kind of enumeration).

    Declaration

    Objective-C

    - (void)enumerateKeysAndMetadataInAllCollectionsUsingBlock:
    (nonnull void (^)(NSString *_Nonnull, NSString *_Nonnull, id _Nullable,
                      BOOL *_Nonnull))block;

    Swift

    func __enumerateKeysAndMetadataInAllCollections(_ block: (String, String, Any?, UnsafeMutablePointer<ObjCBool>) -> Void)

  • Fast enumeration over all key/metadata pairs in all collections.

    This uses a SELECT metadata FROM database ORDER BY collection ASC operation and steps over the results.

    From the filter block, simply return YES if you’d like the block handler to be invoked for the given key. If the filter block returns NO, then the block handler is skipped for the given key, which avoids the cost associated with deserializing the object.

    Keep in mind that you cannot modify the database mid-enumeration (just like any other kind of enumeration).

    Declaration

    Objective-C

    - (void)enumerateKeysAndMetadataInAllCollectionsUsingBlock:
            (nonnull void (^)(NSString *_Nonnull, NSString *_Nonnull,
                              id _Nullable, BOOL *_Nonnull))block
                                                withFilter:
                                                    (nullable BOOL (^)(
                                                        NSString *_Nonnull,
                                                        NSString *_Nonnull))
                                                        filter;

    Swift

    func __enumerateKeysAndMetadataInAllCollections(_ block: (String, String, Any?, UnsafeMutablePointer<ObjCBool>) -> Void, withFilter filter: ((String, String) -> Bool)? = nil)

  • Fast enumeration over all rows in the database.

    This uses a SELECT key, data, metadata from database WHERE collection = ? operation, and then steps over the results, deserializing each object & metadata, and then invoking the given block handler.

    If you only need to enumerate over certain rows (e.g. keys with a particular prefix), consider using the alternative version below which provides a filter, allowing you to skip the serialization step for those rows you’re not interested in.

    Declaration

    Objective-C

    - (void)enumerateRowsInCollection:(nullable NSString *)collection
                       usingBlock:(nonnull void (^)(NSString *_Nonnull,
                                                    id _Nonnull, id _Nullable,
                                                    BOOL *_Nonnull))block;

    Swift

    func __enumerateRows(inCollection collection: String?, using block: (String, Any, Any?, UnsafeMutablePointer<ObjCBool>) -> Void)

  • Fast enumeration over rows in the database for which you’re interested in. The filter block allows you to decide which rows you’re interested in.

    From the filter block, simply return YES if you’d like the block handler to be invoked for the given key. If the filter block returns NO, then the block handler is skipped for the given key, which avoids the cost associated with deserializing the object & metadata.

    Declaration

    Objective-C

    - (void)enumerateRowsInCollection:(nullable NSString *)collection
                       usingBlock:(nonnull void (^)(NSString *_Nonnull,
                                                    id _Nonnull, id _Nullable,
                                                    BOOL *_Nonnull))block
                       withFilter:(nullable BOOL (^)(NSString *_Nonnull))filter;

    Swift

    func __enumerateRows(inCollection collection: String?, using block: (String, Any, Any?, UnsafeMutablePointer<ObjCBool>) -> Void, withFilter filter: ((String) -> Bool)? = nil)

  • Enumerates all rows in all collections.

    The enumeration is sorted by collection. That is, it will enumerate fully over a single collection before moving onto another collection.

    If you only need to enumerate over certain rows (e.g. subset of collections, or keys with a particular prefix), consider using the alternative version below which provides a filter, allowing you to skip the serialization step for those objects you’re not interested in.

    Declaration

    Objective-C

    - (void)enumerateRowsInAllCollectionsUsingBlock:
    (nonnull void (^)(NSString *_Nonnull, NSString *_Nonnull, id _Nonnull,
                      id _Nullable, BOOL *_Nonnull))block;

    Swift

    func __enumerateRowsInAllCollections(_ block: (String, String, Any, Any?, UnsafeMutablePointer<ObjCBool>) -> Void)

  • Enumerates all rows in all collections. The filter block allows you to decide which objects you’re interested in.

    The enumeration is sorted by collection. That is, it will enumerate fully over a single collection before moving onto another collection.

    From the filter block, simply return YES if you’d like the block handler to be invoked for the given collection/key pair. If the filter block returns NO, then the block handler is skipped for the given pair, which avoids the cost associated with deserializing the object.

    Declaration

    Objective-C

    - (void)enumerateRowsInAllCollectionsUsingBlock:
            (nonnull void (^)(NSString *_Nonnull, NSString *_Nonnull,
                              id _Nonnull, id _Nullable, BOOL *_Nonnull))block
                                     withFilter:(nullable BOOL (^)(
                                                    NSString *_Nonnull,
                                                    NSString *_Nonnull))filter;

    Swift

    func __enumerateRowsInAllCollections(_ block: (String, String, Any, Any?, UnsafeMutablePointer<ObjCBool>) -> Void, withFilter filter: ((String, String) -> Bool)? = nil)

  • Enumerates over the given list of keys (unordered).

    This method is faster than fetching individual items as it optimizes cache access. That is, it will first enumerate over items in the cache and then fetch items from the database, thus optimizing the cache and reducing query size.

    If any keys are missing from the database, the ‘object’ parameter will be nil.

    IMPORTANT: Due to cache optimizations, the items may not be enumerated in the same order as the ‘keys’ parameter.

    Declaration

    Objective-C

    - (void)enumerateObjectsForKeys:(nonnull NSArray<NSString *> *)keys
                   inCollection:(nullable NSString *)collection
            unorderedUsingBlock:(nonnull void (^)(NSUInteger, id _Nullable,
                                                  BOOL *_Nonnull))block;

    Swift

    func enumerateObjects(forKeys keys: [String], inCollection collection: String?, unorderedUsing block: (UInt, Any?, UnsafeMutablePointer<ObjCBool>) -> Void)

  • Enumerates over the given list of keys (unordered).

    This method is faster than fetching individual items as it optimizes cache access. That is, it will first enumerate over items in the cache and then fetch items from the database, thus optimizing the cache and reducing query size.

    If any keys are missing from the database, the ‘metadata’ parameter will be nil.

    IMPORTANT: Due to cache optimizations, the items may not be enumerated in the same order as the ‘keys’ parameter.

    Declaration

    Objective-C

    - (void)enumerateMetadataForKeys:(nonnull NSArray<NSString *> *)keys
                    inCollection:(nullable NSString *)collection
             unorderedUsingBlock:(nonnull void (^)(NSUInteger, id _Nullable,
                                                   BOOL *_Nonnull))block;

    Swift

    func enumerateMetadata(forKeys keys: [String], inCollection collection: String?, unorderedUsing block: (UInt, Any?, UnsafeMutablePointer<ObjCBool>) -> Void)

  • Enumerates over the given list of keys (unordered).

    This method is faster than fetching individual items as it optimizes cache access. That is, it will first enumerate over items in the cache and then fetch items from the database, thus optimizing the cache and reducing query size.

    If any keys are missing from the database, the ‘object’ and ‘metadata’ parameter will be nil.

    IMPORTANT: Due to cache optimizations, the items may not be enumerated in the same order as the ‘keys’ parameter.

    Declaration

    Objective-C

    - (void)enumerateRowsForKeys:(nonnull NSArray<NSString *> *)keys
                inCollection:(nullable NSString *)collection
         unorderedUsingBlock:(nonnull void (^)(NSUInteger, id _Nullable,
                                               id _Nullable,
                                               BOOL *_Nonnull))block;

    Swift

    func enumerateRows(forKeys keys: [String], inCollection collection: String?, unorderedUsing block: (UInt, Any?, Any?, UnsafeMutablePointer<ObjCBool>) -> Void)

Extensions

  • Returns an extension transaction corresponding to the extension type registered under the given name. If the extension has not yet been opened, it is done so automatically.

    @return A subclass of YapDatabaseExtensionTransaction, according to the type of extension registered under the given name.

    One must register an extension with the database before it can be accessed from within connections or transactions. After registration everything works automatically using just the registered extension name.

    See

    [YapDatabase registerExtension:withName:]

    Declaration

    Objective-C

    - (nullable __kindof YapDatabaseExtensionTransaction *)extension:
    (nonnull NSString *)extensionName;

    Swift

    func `extension`(_ extensionName: String) -> YapDatabaseExtensionTransaction?

  • Undocumented

    Declaration

    Objective-C

    - (nullable __kindof YapDatabaseExtensionTransaction *)ext:(NSString *)extensionName;

    Swift

    func ext(_ extensionName: String) -> YapDatabaseExtensionTransaction?