YapDatabaseRelationshipTransaction

@interface YapDatabaseRelationshipTransaction : YapDatabaseExtensionTransaction

Welcome to YapDatabase!

The project page has a wealth of documentation if you have any questions. https://github.com/yapstudios/YapDatabase

If you’re new to the project you may want to visit the wiki. https://github.com/yapstudios/YapDatabase/wiki

The YapDatabaseRelationship extension allow you to create relationships between objects, and configure automatic deletion rules.

For tons of information about this extension, see the wiki article: https://github.com/yapstudios/YapDatabase/wiki/Relationships

Node Fetch

Enumerate

  • Enumerates every edge in the graph with the given name.

    Declaration

    Objective-C

    - (void)enumerateEdgesWithName:(nonnull NSString *)name
                    usingBlock:
                        (nonnull void (^)(YapDatabaseRelationshipEdge *_Nonnull,
                                          BOOL *_Nonnull))block;

    Swift

    func enumerateEdges(withName name: String, using block: (YapDatabaseRelationshipEdge, UnsafeMutablePointer<ObjCBool>) -> Void)

    Parameters

    name

    The name of the edge (case sensitive).

  • Enumerates every edge that matches any parameters you specify. You can specify any combination of the following:

    • name only
    • sourceKey & sourceCollection only

    • name + sourceKey & sourceCollection

    If you pass a non-nil sourceKey, and sourceCollection is nil, then the sourceCollection is treated as the empty string, just like the rest of the YapDatabase framework.

    Declaration

    Objective-C

    - (void)enumerateEdgesWithName:(nullable NSString *)name
                     sourceKey:(nullable NSString *)sourceKey
                    collection:(nullable NSString *)sourceCollection
                    usingBlock:
                        (nonnull void (^)(YapDatabaseRelationshipEdge *_Nonnull,
                                          BOOL *_Nonnull))block;

    Swift

    func enumerateEdges(withName name: String?, sourceKey: String?, collection sourceCollection: String?, using block: (YapDatabaseRelationshipEdge, UnsafeMutablePointer<ObjCBool>) -> Void)

    Parameters

    name

    (optional) The name of the edge (case sensitive).
    sourceKey

    (optional) The edge.sourceKey to match.
    sourceCollection

    (optional) The edge.sourceCollection to match.

  • Enumerates every edge that matches any parameters you specify. You can specify any combination of the following:

    • name only
    • destinationKey & destinationCollection only

    • name + destinationKey & destinationCollection

    If you pass a non-nil destinationKey, and destinationCollection is nil, then the destinationCollection is treated as the empty string, just like the rest of the YapDatabase framework.

    Declaration

    Objective-C

    - (void)enumerateEdgesWithName:(nullable NSString *)name
                destinationKey:(nullable NSString *)destinationKey
                    collection:(nullable NSString *)destinationCollection
                    usingBlock:
                        (nonnull void (^)(YapDatabaseRelationshipEdge *_Nonnull,
                                          BOOL *_Nonnull))block;

    Swift

    func enumerateEdges(withName name: String?, destinationKey: String?, collection destinationCollection: String?, using block: (YapDatabaseRelationshipEdge, UnsafeMutablePointer<ObjCBool>) -> Void)

    Parameters

    name

    (optional) The name of the edge (case sensitive).
    destinationKey

    (optional) The edge.destinationKey to match.
    destinationCollection

    (optional) The edge.destinationCollection to match.

  • Enumerates every edge that matches any parameters you specify. You can specify any combination of the following:

    • name only
    • destinationFileURL

    • name + destinationFileURL

    Declaration

    Objective-C

    - (void)enumerateEdgesWithName:(nullable NSString *)name
            destinationFileURL:(nullable NSURL *)destinationFileURL
                    usingBlock:
                        (nonnull void (^)(YapDatabaseRelationshipEdge *_Nonnull,
                                          BOOL *_Nonnull))block;

    Swift

    func enumerateEdges(withName name: String?, destinationFileURL: URL?, using block: (YapDatabaseRelationshipEdge, UnsafeMutablePointer<ObjCBool>) -> Void)

    Parameters

    name

    (optional) The name of the edge (case sensitive).
    destinationFileURL

    (optional) The edge.destinationFileURL to match.

  • Enumerates every edge that matches any parameters you specify. You can specify any combination of the following:

    • name only
    • sourceKey & sourceCollection only
    • destinationKey & destinationCollection only
    • name + sourceKey & sourceCollection
    • name + destinationKey & destinationCollection

    • name + sourceKey & sourceCollection + destinationKey & destinationCollection

    If you pass a non-nil sourceKey, and sourceCollection is nil, then the sourceCollection is treated as the empty string, just like the rest of the YapDatabase framework.

    If you pass a non-nil destinationKey, and destinationCollection is nil, then the destinationCollection is treated as the empty string, just like the rest of the YapDatabase framework.

    Declaration

    Objective-C

    - (void)enumerateEdgesWithName:(nullable NSString *)name
                     sourceKey:(nullable NSString *)sourceKey
                    collection:(nullable NSString *)sourceCollection
                destinationKey:(nullable NSString *)destinationKey
                    collection:(nullable NSString *)destinationCollection
                    usingBlock:
                        (nonnull void (^)(YapDatabaseRelationshipEdge *_Nonnull,
                                          BOOL *_Nonnull))block;

    Swift

    func enumerateEdges(withName name: String?, sourceKey: String?, collection sourceCollection: String?, destinationKey: String?, collection destinationCollection: String?, using block: (YapDatabaseRelationshipEdge, UnsafeMutablePointer<ObjCBool>) -> Void)

    Parameters

    name

    (optional) The name of the edge (case sensitive).
    sourceKey

    (optional) The edge.sourceKey to match.
    sourceCollection

    (optional) The edge.sourceCollection to match.
    destinationKey

    (optional) The edge.destinationKey to match.
    destinationCollection

    (optional) The edge.destinationCollection to match.

  • Enumerates every edge that matches any parameters you specify. You can specify any combination of the following:

    • name only
    • sourceKey & sourceCollection only
    • destinationKey & destinationCollection only
    • name + sourceKey & sourceCollection
    • name + destinationKey & destinationCollection

    • name + sourceKey & sourceCollection + destinationKey & destinationCollection

    If you pass a non-nil sourceKey, and sourceCollection is nil, then the sourceCollection is treated as the empty string, just like the rest of the YapDatabase framework.

    Declaration

    Objective-C

    - (void)enumerateEdgesWithName:(nullable NSString *)name
                     sourceKey:(nullable NSString *)sourceKey
                    collection:(nullable NSString *)sourceCollection
            destinationFileURL:(nullable NSURL *)destinationFileURL
                    usingBlock:
                        (nonnull void (^)(YapDatabaseRelationshipEdge *_Nonnull,
                                          BOOL *_Nonnull))block;

    Swift

    func enumerateEdges(withName name: String?, sourceKey: String?, collection sourceCollection: String?, destinationFileURL: URL?, using block: (YapDatabaseRelationshipEdge, UnsafeMutablePointer<ObjCBool>) -> Void)

    Parameters

    name

    (optional) The name of the edge (case sensitive).
    sourceKey

    (optional) The edge.sourceKey to match.
    sourceCollection

    (optional) The edge.sourceCollection to match.
    destinationFileURL

    (optional) The edge.destinationFileURL to match.

Count

  • Returns a count of every edge in the graph with the given name.

    Declaration

    Objective-C

    - (NSUInteger)edgeCountWithName:(nonnull NSString *)name;

    Swift

    func edgeCount(withName name: String) -> UInt

    Parameters

    name

    The name of the edge (case sensitive).

  • Returns a count of every edge that matches any parameters you specify. You can specify any combination of the following:

    • name only
    • sourceKey & sourceCollection only

    • name + sourceKey & sourceCollection

    If you pass a non-nil sourceKey, and sourceCollection is nil, then the sourceCollection is treated as the empty string, just like the rest of the YapDatabase framework.

    Declaration

    Objective-C

    - (NSUInteger)edgeCountWithName:(nullable NSString *)name
                      sourceKey:(nullable NSString *)sourceKey
                     collection:(nullable NSString *)sourceCollection;

    Swift

    func edgeCount(withName name: String?, sourceKey: String?, collection sourceCollection: String?) -> UInt

    Parameters

    name

    (optional) The name of the edge (case sensitive).
    sourceKey

    (optional) The edge.sourceKey to match.
    sourceCollection

    (optional) The edge.sourceCollection to match.

  • Returns a count of every edge that matches any parameters you specify. You can specify any combination of the following:

    • name only
    • destinationKey & destinationCollection only

    • name + destinationKey & destinationCollection

    If you pass a non-nil destinationKey, and destinationCollection is nil, then the destinationCollection is treated as the empty string, just like the rest of the YapDatabase framework.

    Declaration

    Objective-C

    - (NSUInteger)edgeCountWithName:(nullable NSString *)name
                 destinationKey:(nullable NSString *)destinationKey
                     collection:(nullable NSString *)destinationCollection;

    Swift

    func edgeCount(withName name: String?, destinationKey: String?, collection destinationCollection: String?) -> UInt

    Parameters

    name

    (optional) The name of the edge (case sensitive).
    destinationKey

    (optional) The edge.destinationKey to match.
    destinationCollection

    (optional) The edge.destinationCollection to match.

  • Returns a count of every edge that matches any parameters you specify. You can specify any combination of the following:

    • name only
    • destinationFileURL

    • name + destinationFileURL

    Declaration

    Objective-C

    - (NSUInteger)edgeCountWithName:(nullable NSString *)name
             destinationFileURL:(nullable NSURL *)destinationFileURL;

    Swift

    func edgeCount(withName name: String?, destinationFileURL: URL?) -> UInt

    Parameters

    name

    (optional) The name of the edge (case sensitive).
    destinationFileURL

    (optional) The edge.destinationFileURL to match.

  • Returns a count of every edge that matches any parameters you specify. You can specify any combination of the following:

    • name only
    • sourceKey & sourceCollection only
    • destinationKey & destinationCollection only
    • name + sourceKey & sourceCollection
    • name + destinationKey & destinationCollection

    • name + sourceKey & sourceCollection + destinationKey & destinationCollection

    If you pass a non-nil sourceKey, and sourceCollection is nil, then the sourceCollection is treated as the empty string, just like the rest of the YapDatabase framework.

    If you pass a non-nil destinationKey, and destinationCollection is nil, then the destinationCollection is treated as the empty string, just like the rest of the YapDatabase framework.

    Declaration

    Objective-C

    - (NSUInteger)edgeCountWithName:(nullable NSString *)name
                      sourceKey:(nullable NSString *)sourceKey
                     collection:(nullable NSString *)sourceCollection
                 destinationKey:(nullable NSString *)destinationKey
                     collection:(nullable NSString *)destinationCollection;

    Swift

    func edgeCount(withName name: String?, sourceKey: String?, collection sourceCollection: String?, destinationKey: String?, collection destinationCollection: String?) -> UInt

    Parameters

    name

    (optional) The name of the edge (case sensitive).
    sourceKey

    (optional) The edge.sourceKey to match.
    sourceCollection

    (optional) The edge.sourceCollection to match.
    destinationKey

    (optional) The edge.destinationKey to match.
    destinationCollection

    (optional) The edge.destinationCollection to match.

  • Returns a count of every edge that matches any parameters you specify. You can specify any combination of the following:

    • name only
    • sourceKey & sourceCollection only
    • destinationFileURL
    • name + sourceKey & sourceCollection
    • name + destinationFileURL

    • name + sourceKey & sourceCollection + destinationFileURL

    If you pass a non-nil sourceKey, and sourceCollection is nil, then the sourceCollection is treated as the empty string, just like the rest of the YapDatabase framework.

    Declaration

    Objective-C

    - (NSUInteger)edgeCountWithName:(nullable NSString *)name
                      sourceKey:(nullable NSString *)sourceKey
                     collection:(nullable NSString *)sourceCollection
             destinationFileURL:(nullable NSURL *)destinationFileURL;

    Swift

    func edgeCount(withName name: String?, sourceKey: String?, collection sourceCollection: String?, destinationFileURL: URL?) -> UInt

    Parameters

    name

    (optional) The name of the edge (case sensitive).
    sourceKey

    (optional) The edge.sourceKey to match.
    sourceCollection

    (optional) The edge.sourceCollection to match.
    destinationFileURL

    (optional) The edge.destinationFileURL to match.

Manual Edge Management

  • This method will add the manual edge (if it doesn’t already exist). Otherwise it will replace the the existing manual edge with the same name & srcKey/collection & dstKey/collection.

    Declaration

    Objective-C

    - (void)addEdge:(nonnull YapDatabaseRelationshipEdge *)edge;

    Swift

    func add(_ edge: YapDatabaseRelationshipEdge)

  • This method will remove the given manual edge (if it exists).

    The following properties are compared, for the purpose of checking edges to see if they match:

    • name
    • sourceKey & sourceCollection
    • destinationKey & destinationCollection
    • isManualEdge

    In other words, to manually remove an existing manual edge, you simply need to pass an edge instance which has the same name & source & destination.

    When you manually remove an edge, you can decide how the relationship extension should process it. That is, you can tell the relationship edge to act as if the source or destination node was deleted:

    • YDB_EdgeDeleted : Do nothing. Simply remove the edge from the database.
    • YDB_SourceNodeDeleted : Act as if the source node was deleted.
    • YDB_DestinationNodeDeleted : Act as if the destination node was deleted.

    This allows you to tell the relationship extension whether or not to process the nodeDeleteRules of the edge. And, if so, in what manner.

    In other words, you can remove an edge, and tell the relationship extension to pretend the source node was deleted (for example), even if you didn’t actually delete the source node. This allows you to execute the nodeDeleteRules that exist on an edge, without actually deleting the node.

    Please note that manual edges and protocol edges are in different domains. A manual edge is one you create and add to the system via the addEdge: method. A protocol edge is one created via the YapDatabaseRelationshipNode protocol. So you cannot, for example, create an edge via the YapDatabaseRelationshipNode protocol, and then manually delete it via the removeEdge:: method. This is what is meant by different domains.

    Declaration

    Objective-C

    - (void)removeEdgeWithName:(nonnull NSString *)edgeName
                 sourceKey:(nonnull NSString *)sourceKey
                collection:(nullable NSString *)sourceCollection
            destinationKey:(nonnull NSString *)destinationKey
                collection:(nullable NSString *)destinationCollection
            withProcessing:(YDB_NotifyReason)reason;

    Swift

    func removeEdge(withName edgeName: String, sourceKey: String, collection sourceCollection: String?, destinationKey: String, collection destinationCollection: String?, withProcessing reason: YDB_NotifyReason)

  • This method is the same as removeEdgeWithName::::::, but allows you to pass an existing edge instance.

    The following properties of the given edge are inspected, for the purpose of checking edges to see if they match:

    • name
    • sourceKey & sourceCollection
    • destinationKey & destinationCollection

    The given edge’s nodeDeleteRules are ignored. The nodeDeleteRules of the pre-existing edge are processed according to the given reason.

    See

    removeEdgeWithName:sourceKey:collection:destinationKey:collection:withProcessing:

    Declaration

    Objective-C

    - (void)removeEdge:(nonnull YapDatabaseRelationshipEdge *)edge
    withProcessing:(YDB_NotifyReason)reason;

    Swift

    func remove(_ edge: YapDatabaseRelationshipEdge, withProcessing reason: YDB_NotifyReason)

Force Processing

  • The extension automatically processes all changes to the graph at the end of a readwrite transaction. This allows it to consolidate multiple changes into a single batch, and also minimizes the impact of cascading delete rules, especially in the case where you’ll be deleting many of the objects manually at some later point within the transaction block.

    However, there may be certain use cases where it is preferable to have the extension execute its rules in advance. For example, if you need a cascading delete to complete before continuing your transaction logic, then you can force the extension processing to occur prior to the end of the readwrite transaction by invoking this flush method

    Declaration

    Objective-C

    - (void)flush;

    Swift

    func flush()