DataStack

public final class DataStack : Equatable

The DataStack encapsulates the data model for the Core Data stack. Each DataStack can have multiple data stores, usually specified as a Configuration in the model editor. Behind the scenes, the DataStack manages its own NSPersistentStoreCoordinator, a root NSManagedObjectContext for disk saves, and a shared NSManagedObjectContext designed as a read-only model interface for NSManagedObjects.

  • The resolved application name, used by the DataStack as the default Xcode model name (.xcdatamodel filename) if not explicitly provided.

    Declaration

    Swift

    public static let applicationName: String
  • Convenience initializer for DataStack that creates a SchemaHistory from the model with the specified modelName in the specified bundle.

    Declaration

    Swift

    public convenience init(xcodeModelName: XcodeDataModelFileName = DataStack.applicationName, bundle: Bundle = Bundle.main, migrationChain: MigrationChain = nil)

    Parameters

    xcodeModelName

    the name of the (.xcdatamodeld) model file. If not specified, the application name (CFBundleName) will be used if it exists, or CoreData if it the bundle name was not set (e.g. in Unit Tests).

    bundle

    an optional bundle to load .xcdatamodeld models from. If not specified, the main bundle will be used.

    migrationChain

    the MigrationChain that indicates the sequence of model versions to be used as the order for progressive migrations. If not specified, will default to a non-migrating data stack.

  • Convenience initializer for DataStack that creates a SchemaHistory from a list of DynamicSchema versions.

    CoreStore.defaultStack = DataStack(
        XcodeDataModelSchema(modelName: "MyModelV1"),
        CoreStoreSchema(
            modelVersion: "MyModelV2",
            entities: [
                Entity<Animal>("Animal"),
                Entity<Person>("Person")
            ]
        ),
        migrationChain: ["MyModelV1", "MyModelV2"]
    )
    

    Declaration

    Swift

    public convenience init(_ schema: DynamicSchema, _ otherSchema: DynamicSchema..., migrationChain: MigrationChain = nil)

    Parameters

    schema

    an instance of DynamicSchema

    otherSchema

    a list of other DynamicSchema instances that represent present/previous/future model versions, in any order

    migrationChain

    the MigrationChain that indicates the sequence of model versions to be used as the order for progressive migrations. If not specified, will default to a non-migrating data stack.

  • Initializes a DataStack from a SchemaHistory instance.

    CoreStore.defaultStack = DataStack(
        schemaHistory: SchemaHistory(
            XcodeDataModelSchema(modelName: "MyModelV1"),
            CoreStoreSchema(
                modelVersion: "MyModelV2",
                entities: [
                    Entity<Animal>("Animal"),
                    Entity<Person>("Person")
                ]
            ),
            migrationChain: ["MyModelV1", "MyModelV2"]
        )
    )
    

    Declaration

    Swift

    public required init(schemaHistory: SchemaHistory)

    Parameters

    schemaHistory

    the SchemaHistory for the stack

  • Returns the DataStack‘s current model version. StorageInterfaces added to the stack will be migrated to this version.

    Declaration

    Swift

    public var modelVersion: String { get }
  • Returns the DataStack‘s current model schema. StorageInterfaces added to the stack will be migrated to this version.

    Declaration

    Swift

    public var modelSchema: DynamicSchema { get }
  • Returns the entity name-to-class type mapping from the DataStack‘s model.

    Declaration

    Swift

    public func entityTypesByName(for type: NSManagedObject.Type) -> [EntityName : NSManagedObject.Type]
  • Returns the entity name-to-class type mapping from the DataStack‘s model.

    Declaration

    Swift

    public func entityTypesByName(for type: CoreStoreObject.Type) -> [EntityName : CoreStoreObject.Type]
  • Returns the NSEntityDescription for the specified NSManagedObject subclass.

    Declaration

    Swift

    public func entityDescription(for type: NSManagedObject.Type) -> NSEntityDescription?
  • Returns the NSEntityDescription for the specified CoreStoreObject subclass.

    Declaration

    Swift

    public func entityDescription(for type: CoreStoreObject.Type) -> NSEntityDescription?
  • Returns the NSManagedObjectID for the specified object URI if it exists in the persistent store.

    Declaration

    Swift

    public func objectID(forURIRepresentation url: URL) -> NSManagedObjectID?
  • Creates an SQLiteStore with default parameters and adds it to the stack. This method blocks until completion.

    try dataStack.addStorageAndWait()
    

    Throws

    a CoreStoreError value indicating the failure

    Declaration

    Swift

    @discardableResult
    public func addStorageAndWait() throws -> SQLiteStore

    Return Value

    the local SQLite storage added to the stack

  • Adds a StorageInterface to the stack and blocks until completion.

    try dataStack.addStorageAndWait(InMemoryStore(configuration: "Config1"))
    

    Throws

    a CoreStoreError value indicating the failure

    Declaration

    Swift

    @discardableResult
    public func addStorageAndWait<T>(_ storage: T) throws -> T where T : StorageInterface

    Parameters

    storage

    Return Value

    the StorageInterface added to the stack

  • Adds a LocalStorage to the stack and blocks until completion.

    try dataStack.addStorageAndWait(SQLiteStore(configuration: "Config1"))
    

    Throws

    a CoreStoreError value indicating the failure

    Declaration

    Swift

    @discardableResult
    public func addStorageAndWait<T>(_ storage: T) throws -> T where T : LocalStorage

    Parameters

    storage

    the local storage

    Return Value

    the local storage added to the stack. Note that this may not always be the same instance as the parameter argument if a previous LocalStorage was already added at the same URL and with the same configuration.

  • Adds a CloudStorage to the stack and blocks until completion.

    guard let storage = ICloudStore(
        ubiquitousContentName: "MyAppCloudData",
        ubiquitousContentTransactionLogsSubdirectory: "logs/config1",
        ubiquitousContainerID: "iCloud.com.mycompany.myapp.containername",
        ubiquitousPeerToken: "9614d658014f4151a95d8048fb717cf0",
        configuration: "Config1",
        cloudStorageOptions: .recreateLocalStoreOnModelMismatch
    ) else {
        // iCloud is not available on the device
        return
    }
    try dataStack.addStorageAndWait(storage)
    

    Throws

    a CoreStoreError value indicating the failure

    Declaration

    Swift

    @discardableResult
    public func addStorageAndWait<T>(_ storage: T) throws -> T where T : CloudStorage

    Parameters

    storage

    the local storage

    Return Value

    the cloud storage added to the stack. Note that this may not always be the same instance as the parameter argument if a previous CloudStorage was already added at the same URL and with the same configuration.

  • Allow external libraries to store custom data in the DataStack. App code should rarely have a need for this.

    enum Static {
       static var myDataKey: Void?
    }
    CoreStore.defaultStack.userInfo[&Static.myDataKey] = myObject
    

    Important

    Do not use this method to store thread-sensitive data.

    Declaration

    Swift

    public let userInfo: UserInfo
  • Declaration

    Swift

    public static func == (lhs: DataStack, rhs: DataStack) -> Bool
  • Declaration

    Swift

    public var debugDescription: String { get }
  • Asynchronously adds a StorageInterface to the stack. Migrations are also initiated by default.

    dataStack.addStorage(
        InMemoryStore(configuration: "Config1"),
        completion: { result in
            switch result {
            case .success(let storage): // ...
            case .failure(let error): // ...
            }
        }
    )
    

    Declaration

    Swift

    public func addStorage<T>(_ storage: T, completion: @escaping (SetupResult<T>) -> Void)

    Parameters

    storage

    the storage

    completion

    the closure to be executed on the main queue when the process completes, either due to success or failure. The closure’s SetupResult argument indicates the result. Note that the StorageInterface associated to the SetupResult.success may not always be the same instance as the parameter argument if a previous StorageInterface was already added at the same URL and with the same configuration.

  • Asynchronously adds a LocalStorage to the stack. Migrations are also initiated by default.

    let migrationProgress = dataStack.addStorage(
        SQLiteStore(fileName: "core_data.sqlite", configuration: "Config1"),
        completion: { result in
            switch result {
            case .success(let storage): // ...
            case .failure(let error): // ...
            }
        }
    )
    

    Declaration

    Swift

    public func addStorage<T: LocalStorage>(_ storage: T, completion: @escaping (SetupResult<T>) -> Void) -> Progress?

    Parameters

    storage

    the local storage

    completion

    the closure to be executed on the main queue when the process completes, either due to success or failure. The closure’s SetupResult argument indicates the result. Note that the LocalStorage associated to the SetupResult.success may not always be the same instance as the parameter argument if a previous LocalStorage was already added at the same URL and with the same configuration.

    Return Value

    a Progress instance if a migration has started, or nil if either no migrations are required or if a failure occured.

  • Asynchronously adds a CloudStorage to the stack. Migrations are also initiated by default.

    guard let storage = ICloudStore(
        ubiquitousContentName: "MyAppCloudData",
        ubiquitousContentTransactionLogsSubdirectory: "logs/config1",
        ubiquitousContainerID: "iCloud.com.mycompany.myapp.containername",
        ubiquitousPeerToken: "9614d658014f4151a95d8048fb717cf0",
        configuration: "Config1",
        cloudStorageOptions: .recreateLocalStoreOnModelMismatch
    ) else {
        // iCloud is not available on the device
        return
    }
    dataStack.addStorage(
        storage,
        completion: { result in
            switch result {
            case .success(let storage): // ...
            case .failure(let error): // ...
            }
        }
    )
    

    Declaration

    Swift

    public func addStorage<T: CloudStorage>(_ storage: T, completion: @escaping (SetupResult<T>) -> Void)

    Parameters

    storage

    the cloud storage

    completion

    the closure to be executed on the main queue when the process completes, either due to success or failure. The closure’s SetupResult argument indicates the result. Note that the CloudStorage associated to the SetupResult.success may not always be the same instance as the parameter argument if a previous CloudStorage was already added at the same URL and with the same configuration.

  • Migrates a local storage to match the DataStack‘s managed object model version. This method does NOT add the migrated store to the data stack.

    Throws

    a CoreStoreError value indicating the failure

    Declaration

    Swift

    public func upgradeStorageIfNeeded<T: LocalStorage>(_ storage: T, completion: @escaping (MigrationResult) -> Void) throws -> Progress?

    Parameters

    storage

    the local storage

    completion

    the closure to be executed on the main queue when the migration completes, either due to success or failure. The closure’s MigrationResult argument indicates the result.

    Return Value

    a Progress instance if a migration has started, or nil is no migrations are required

  • Checks the migration steps required for the storage to match the DataStack‘s managed object model version.

    Throws

    a CoreStoreError value indicating the failure

    Declaration

    Swift

    public func requiredMigrationsForStorage<T>(_ storage: T) throws -> [MigrationType] where T : LocalStorage

    Parameters

    storage

    the local storage

    Return Value

    a MigrationType array indicating the migration steps required for the store, or an empty array if the file does not exist yet. Otherwise, an error is thrown if either inspection of the store failed, or if no mapping model was found/inferred.

  • Fetches the DynamicObject instance in the DataStack‘s context from a reference created from a transaction or from a different managed object context.

    Declaration

    Swift

    public func fetchExisting<D>(_ object: D) -> D? where D : DynamicObject

    Parameters

    object

    a reference to the object created/fetched outside the DataStack

    Return Value

    the DynamicObject instance if the object exists in the DataStack, or nil if not found.

  • Fetches the DynamicObject instance in the DataStack‘s context from an NSManagedObjectID.

    Declaration

    Swift

    public func fetchExisting<D>(_ objectID: NSManagedObjectID) -> D? where D : DynamicObject

    Parameters

    objectID

    the NSManagedObjectID for the object

    Return Value

    the DynamicObject instance if the object exists in the DataStack, or nil if not found.

  • Fetches the DynamicObject instances in the DataStack‘s context from references created from a transaction or from a different managed object context.

    Declaration

    Swift

    public func fetchExisting<D, S>(_ objects: S) -> [D] where D : DynamicObject, D == S.Element, S : Sequence

    Parameters

    objects

    an array of DynamicObjects created/fetched outside the DataStack

    Return Value

    the DynamicObject array for objects that exists in the DataStack

  • Fetches the DynamicObject instances in the DataStack‘s context from a list of NSManagedObjectID.

    Declaration

    Swift

    public func fetchExisting<D, S>(_ objectIDs: S) -> [D] where D : DynamicObject, S : Sequence, S.Element == NSManagedObjectID

    Parameters

    objectIDs

    the NSManagedObjectID array for the objects

    Return Value

    the DynamicObject array for objects that exists in the DataStack

  • Fetches the first DynamicObject instance that satisfies the specified FetchClauses. Accepts Where, OrderBy, and Tweak clauses.

    Throws

    CoreStoreError.persistentStoreNotFound if the specified entity could not be found in any store’s schema.

    Declaration

    Swift

    public func fetchOne<D>(_ from: From<D>, _ fetchClauses: FetchClause...) throws -> D? where D : DynamicObject

    Parameters

    from

    a From clause indicating the entity type

    fetchClauses

    a series of FetchClause instances for the fetch request. Accepts Where, OrderBy, and Tweak clauses.

    Return Value

    the first DynamicObject instance that satisfies the specified FetchClauses, or nil if no match was found

  • Fetches the first DynamicObject instance that satisfies the specified FetchClauses. Accepts Where, OrderBy, and Tweak clauses.

    Throws

    CoreStoreError.persistentStoreNotFound if the specified entity could not be found in any store’s schema.

    Declaration

    Swift

    public func fetchOne<D>(_ from: From<D>, _ fetchClauses: [FetchClause]) throws -> D? where D : DynamicObject

    Parameters

    from

    a From clause indicating the entity type

    fetchClauses

    a series of FetchClause instances for the fetch request. Accepts Where, OrderBy, and Tweak clauses.

    Return Value

    the first DynamicObject instance that satisfies the specified FetchClauses, or nil if no match was found

  • Fetches the first DynamicObject instance that satisfies the specified FetchChainableBuilderType built from a chain of clauses.

    let youngestTeen = dataStack.fetchOne(
        From<MyPersonEntity>()
            .where(\.age > 18)
            .orderBy(.ascending(\.age))
    )
    

    Throws

    CoreStoreError.persistentStoreNotFound if the specified entity could not be found in any store’s schema.

    Declaration

    Swift

    public func fetchOne<B>(_ clauseChain: B) throws -> B.ObjectType? where B : FetchChainableBuilderType

    Parameters

    clauseChain

    a FetchChainableBuilderType built from a chain of clauses

    Return Value

    the first DynamicObject instance that satisfies the specified FetchChainableBuilderType, or nil if no match was found

  • Fetches all DynamicObject instances that satisfy the specified FetchClauses. Accepts Where, OrderBy, and Tweak clauses.

    Throws

    CoreStoreError.persistentStoreNotFound if the specified entity could not be found in any store’s schema.

    Declaration

    Swift

    public func fetchAll<D>(_ from: From<D>, _ fetchClauses: FetchClause...) throws -> [D] where D : DynamicObject

    Parameters

    from

    a From clause indicating the entity type

    fetchClauses

    a series of FetchClause instances for the fetch request. Accepts Where, OrderBy, and Tweak clauses.

    Return Value

    all DynamicObject instances that satisfy the specified FetchClauses, or an empty array if no match was found

  • Fetches all DynamicObject instances that satisfy the specified FetchClauses. Accepts Where, OrderBy, and Tweak clauses.

    Throws

    CoreStoreError.persistentStoreNotFound if the specified entity could not be found in any store’s schema.

    Declaration

    Swift

    public func fetchAll<D>(_ from: From<D>, _ fetchClauses: [FetchClause]) throws -> [D] where D : DynamicObject

    Parameters

    from

    a From clause indicating the entity type

    fetchClauses

    a series of FetchClause instances for the fetch request. Accepts Where, OrderBy, and Tweak clauses.

    Return Value

    all DynamicObject instances that satisfy the specified FetchClauses, or an empty array if no match was found

  • Fetches all DynamicObject instances that satisfy the specified FetchChainableBuilderType built from a chain of clauses.

    let people = dataStack.fetchAll(
        From<MyPersonEntity>()
            .where(\.age > 18)
            .orderBy(.ascending(\.age))
    )
    

    Throws

    CoreStoreError.persistentStoreNotFound if the specified entity could not be found in any store’s schema.

    Declaration

    Swift

    public func fetchAll<B>(_ clauseChain: B) throws -> [B.ObjectType] where B : FetchChainableBuilderType

    Parameters

    clauseChain

    a FetchChainableBuilderType built from a chain of clauses

    Return Value

    all DynamicObject instances that satisfy the specified FetchChainableBuilderType, or an empty array if no match was found

  • Fetches the number of DynamicObjects that satisfy the specified FetchClauses. Accepts Where, OrderBy, and Tweak clauses.

    Throws

    CoreStoreError.persistentStoreNotFound if the specified entity could not be found in any store’s schema.

    Declaration

    Swift

    public func fetchCount<D>(_ from: From<D>, _ fetchClauses: FetchClause...) throws -> Int where D : DynamicObject

    Parameters

    from

    a From clause indicating the entity type

    fetchClauses

    a series of FetchClause instances for the fetch request. Accepts Where, OrderBy, and Tweak clauses.

    Return Value

    the number of DynamicObjects that satisfy the specified FetchClauses

  • Fetches the number of DynamicObjects that satisfy the specified FetchClauses. Accepts Where, OrderBy, and Tweak clauses.

    Throws

    CoreStoreError.persistentStoreNotFound if the specified entity could not be found in any store’s schema.

    Declaration

    Swift

    public func fetchCount<D>(_ from: From<D>, _ fetchClauses: [FetchClause]) throws -> Int where D : DynamicObject

    Parameters

    from

    a From clause indicating the entity type

    fetchClauses

    a series of FetchClause instances for the fetch request. Accepts Where, OrderBy, and Tweak clauses.

    Return Value

    the number of DynamicObjects that satisfy the specified FetchClauses

  • Fetches the number of DynamicObjects that satisfy the specified FetchChainableBuilderType built from a chain of clauses.

    let numberOfAdults = dataStack.fetchCount(
        From<MyPersonEntity>()
            .where(\.age > 18)
            .orderBy(.ascending(\.age))
    )
    

    Throws

    CoreStoreError.persistentStoreNotFound if the specified entity could not be found in any store’s schema.

    Declaration

    Swift

    public func fetchCount<B>(_ clauseChain: B) throws -> Int where B : FetchChainableBuilderType

    Parameters

    clauseChain

    a FetchChainableBuilderType built from a chain of clauses

    Return Value

    the number of DynamicObjects that satisfy the specified FetchChainableBuilderType

  • Fetches the NSManagedObjectID for the first DynamicObject that satisfies the specified FetchClauses. Accepts Where, OrderBy, and Tweak clauses.

    Throws

    CoreStoreError.persistentStoreNotFound if the specified entity could not be found in any store’s schema.

    Declaration

    Swift

    public func fetchObjectID<D>(_ from: From<D>, _ fetchClauses: FetchClause...) throws -> NSManagedObjectID? where D : DynamicObject

    Parameters

    from

    a From clause indicating the entity type

    fetchClauses

    a series of FetchClause instances for the fetch request. Accepts Where, OrderBy, and Tweak clauses.

    Return Value

    the NSManagedObjectID for the first DynamicObject that satisfies the specified FetchClauses, or nil if no match was found

  • Fetches the NSManagedObjectID for the first DynamicObject that satisfies the specified FetchClauses. Accepts Where, OrderBy, and Tweak clauses.

    Throws

    CoreStoreError.persistentStoreNotFound if the specified entity could not be found in any store’s schema.

    Declaration

    Swift

    public func fetchObjectID<D>(_ from: From<D>, _ fetchClauses: [FetchClause]) throws -> NSManagedObjectID? where D : DynamicObject

    Parameters

    from

    a From clause indicating the entity type

    fetchClauses

    a series of FetchClause instances for the fetch request. Accepts Where, OrderBy, and Tweak clauses.

    Return Value

    the NSManagedObjectID for the first DynamicObject that satisfies the specified FetchClauses, or nil if no match was found

  • Fetches the NSManagedObjectID for the first DynamicObject that satisfies the specified FetchChainableBuilderType built from a chain of clauses.

    let youngestTeenID = dataStack.fetchObjectID(
        From<MyPersonEntity>()
            .where(\.age > 18)
            .orderBy(.ascending(\.age))
    )
    

    Throws

    CoreStoreError.persistentStoreNotFound if the specified entity could not be found in any store’s schema.

    Declaration

    Swift

    public func fetchObjectID<B>(_ clauseChain: B) throws -> NSManagedObjectID? where B : FetchChainableBuilderType

    Parameters

    clauseChain

    a FetchChainableBuilderType built from a chain of clauses

    Return Value

    the NSManagedObjectID for the first DynamicObject that satisfies the specified FetchChainableBuilderType, or nil if no match was found

  • Fetches the NSManagedObjectID for all DynamicObjects that satisfy the specified FetchClauses. Accepts Where, OrderBy, and Tweak clauses.

    Throws

    CoreStoreError.persistentStoreNotFound if the specified entity could not be found in any store’s schema.

    Declaration

    Swift

    public func fetchObjectIDs<D>(_ from: From<D>, _ fetchClauses: FetchClause...) throws -> [NSManagedObjectID] where D : DynamicObject

    Parameters

    from

    a From clause indicating the entity type

    fetchClauses

    a series of FetchClause instances for the fetch request. Accepts Where, OrderBy, and Tweak clauses.

    Return Value

    the NSManagedObjectID for all DynamicObjects that satisfy the specified FetchClauses, or an empty array if no match was found

  • Fetches the NSManagedObjectID for all DynamicObjects that satisfy the specified FetchClauses. Accepts Where, OrderBy, and Tweak clauses.

    Throws

    CoreStoreError.persistentStoreNotFound if the specified entity could not be found in any store’s schema.

    Declaration

    Swift

    public func fetchObjectIDs<D>(_ from: From<D>, _ fetchClauses: [FetchClause]) throws -> [NSManagedObjectID] where D : DynamicObject

    Parameters

    from

    a From clause indicating the entity type

    fetchClauses

    a series of FetchClause instances for the fetch request. Accepts Where, OrderBy, and Tweak clauses.

    Return Value

    the NSManagedObjectID for all DynamicObjects that satisfy the specified FetchClauses, or an empty array if no match was found

  • Fetches the NSManagedObjectID for all DynamicObjects that satisfy the specified FetchChainableBuilderType built from a chain of clauses.

    let idsOfAdults = dataStack.fetchObjectIDs(
        From<MyPersonEntity>()
            .where(\.age > 18)
            .orderBy(.ascending(\.age))
    )
    

    Throws

    CoreStoreError.persistentStoreNotFound if the specified entity could not be found in any store’s schema.

    Declaration

    Swift

    public func fetchObjectIDs<B>(_ clauseChain: B) throws -> [NSManagedObjectID] where B : FetchChainableBuilderType

    Parameters

    clauseChain

    a FetchChainableBuilderType built from a chain of clauses

    Return Value

    the NSManagedObjectID for all DynamicObjects that satisfy the specified FetchChainableBuilderType, or an empty array if no match was found

  • Queries aggregate values as specified by the QueryClauses. Requires at least a Select clause, and optional Where, OrderBy, GroupBy, and Tweak clauses.

    A query differs from a fetch in that it only retrieves values already stored in the persistent store. As such, values from unsaved transactions or contexts will not be incorporated in the query result.

    Throws

    CoreStoreError.persistentStoreNotFound if the specified entity could not be found in any store’s schema.

    Declaration

    Swift

    public func queryValue<D, U>(_ from: From<D>, _ selectClause: Select<D, U>, _ queryClauses: QueryClause...) throws -> U? where D : DynamicObject, U : QueryableAttributeType

    Parameters

    from

    a From clause indicating the entity type

    selectClause

    a Select<U> clause indicating the properties to fetch, and with the generic type indicating the return type.

    queryClauses

    a series of QueryClause instances for the query request. Accepts Where, OrderBy, GroupBy, and Tweak clauses.

    Return Value

    the result of the the query, or nil if no match was found. The type of the return value is specified by the generic type of the Select<U> parameter.

  • Queries aggregate values as specified by the QueryClauses. Requires at least a Select clause, and optional Where, OrderBy, GroupBy, and Tweak clauses.

    A query differs from a fetch in that it only retrieves values already stored in the persistent store. As such, values from unsaved transactions or contexts will not be incorporated in the query result.

    Throws

    CoreStoreError.persistentStoreNotFound if the specified entity could not be found in any store’s schema.

    Declaration

    Swift

    public func queryValue<D, U>(_ from: From<D>, _ selectClause: Select<D, U>, _ queryClauses: [QueryClause]) throws -> U? where D : DynamicObject, U : QueryableAttributeType

    Parameters

    from

    a From clause indicating the entity type

    selectClause

    a Select<U> clause indicating the properties to fetch, and with the generic type indicating the return type.

    queryClauses

    a series of QueryClause instances for the query request. Accepts Where, OrderBy, GroupBy, and Tweak clauses.

    Return Value

    the result of the the query, or nil if no match was found. The type of the return value is specified by the generic type of the Select<U> parameter.

  • Queries a property value or aggregate as specified by the QueryChainableBuilderType built from a chain of clauses.

    A query differs from a fetch in that it only retrieves values already stored in the persistent store. As such, values from unsaved transactions or contexts will not be incorporated in the query result.

    let averageAdultAge = dataStack.queryValue(
        From<MyPersonEntity>()
            .select(Int.self, .average(\.age))
            .where(\.age > 18)
    )
    

    Throws

    CoreStoreError.persistentStoreNotFound if the specified entity could not be found in any store’s schema.

    Declaration

    Swift

    public func queryValue<B>(_ clauseChain: B) throws -> B.ResultType? where B : QueryChainableBuilderType, B.ResultType : QueryableAttributeType

    Parameters

    clauseChain

    a QueryChainableBuilderType indicating the property/aggregate to fetch and the series of queries for the request.

    Return Value

    the result of the the query as specified by the QueryChainableBuilderType, or nil if no match was found.

  • Queries a dictionary of attribute values as specified by the QueryClauses. Requires at least a Select clause, and optional Where, OrderBy, GroupBy, and Tweak clauses.

    A query differs from a fetch in that it only retrieves values already stored in the persistent store. As such, values from unsaved transactions or contexts will not be incorporated in the query result.

    Throws

    CoreStoreError.persistentStoreNotFound if the specified entity could not be found in any store’s schema.

    Declaration

    Swift

    public func queryAttributes<D>(_ from: From<D>, _ selectClause: Select<D, NSDictionary>, _ queryClauses: QueryClause...) throws -> [[String : Any]] where D : DynamicObject

    Parameters

    from

    a From clause indicating the entity type

    selectClause

    a Select<U> clause indicating the properties to fetch, and with the generic type indicating the return type.

    queryClauses

    a series of QueryClause instances for the query request. Accepts Where, OrderBy, GroupBy, and Tweak clauses.

    Return Value

    the result of the the query. The type of the return value is specified by the generic type of the Select<U> parameter.

  • Queries a dictionary of attribute values as specified by the QueryClauses. Requires at least a Select clause, and optional Where, OrderBy, GroupBy, and Tweak clauses.

    A query differs from a fetch in that it only retrieves values already stored in the persistent store. As such, values from unsaved transactions or contexts will not be incorporated in the query result.

    Throws

    CoreStoreError.persistentStoreNotFound if the specified entity could not be found in any store’s schema.

    Declaration

    Swift

    public func queryAttributes<D>(_ from: From<D>, _ selectClause: Select<D, NSDictionary>, _ queryClauses: [QueryClause]) throws -> [[String : Any]] where D : DynamicObject

    Parameters

    from

    a From clause indicating the entity type

    selectClause

    a Select<U> clause indicating the properties to fetch, and with the generic type indicating the return type.

    queryClauses

    a series of QueryClause instances for the query request. Accepts Where, OrderBy, GroupBy, and Tweak clauses.

    Return Value

    the result of the the query. The type of the return value is specified by the generic type of the Select<U> parameter.

  • Queries a dictionary of attribute values or as specified by the QueryChainableBuilderType built from a chain of clauses.

    A query differs from a fetch in that it only retrieves values already stored in the persistent store. As such, values from unsaved transactions or contexts will not be incorporated in the query result.

    let results = dataStack.queryAttributes(
        From<MyPersonEntity>()
            .select(
                NSDictionary.self,
                .attribute(\.age, as: "age"),
                .count(\.age, as: "numberOfPeople")
            )
            .groupBy(\.age)
    )
    for dictionary in results! {
        let age = dictionary["age"] as! Int
        let count = dictionary["numberOfPeople"] as! Int
        print("There are \(count) people who are \(age) years old."
    }
    

    Throws

    CoreStoreError.persistentStoreNotFound if the specified entity could not be found in any store’s schema.

    Declaration

    Swift

    public func queryAttributes<B>(_ clauseChain: B) throws -> [[String : Any]] where B : QueryChainableBuilderType, B.ResultType == NSDictionary

    Parameters

    clauseChain

    a QueryChainableBuilderType indicating the properties to fetch and the series of queries for the request.

    Return Value

    the result of the the query as specified by the QueryChainableBuilderType

  • The internal NSManagedObjectContext managed by this instance. Using this context directly should typically be avoided, and is provided by CoreStore only for extremely specialized cases.

    Declaration

    Swift

    public func unsafeContext() -> NSManagedObjectContext
  • Performs a transaction asynchronously where NSManagedObject or CoreStoreObject creates, updates, and deletes can be made. The changes are commited automatically after the task closure returns. On success, the value returned from closure will be the wrapped as .success(T) in the completion‘s Result<T>. Any errors thrown from inside the task will be reported as .failure(CoreStoreError). To cancel/rollback changes, call try transaction.cancel(), which throws a CoreStoreError.userCancelled.

    Declaration

    Swift

    public func perform<T>(asynchronous task: @escaping (_ transaction: AsynchronousDataTransaction) throws -> T, completion: @escaping (AsynchronousDataTransaction.Result<T>) -> Void)

    Parameters

    task

    the asynchronous closure where creates, updates, and deletes can be made to the transaction. Transaction blocks are executed serially in a background queue, and all changes are made from a concurrent NSManagedObjectContext.

    completion

    the closure executed after the save completes. The Result argument of the closure will either wrap the return value of task, or any uncaught errors thrown from within task. Cancelled tasks will be indicated by .failure(error: CoreStoreError.userCancelled). Custom errors thrown by the user will be wrapped in CoreStoreError.userError(error: Error).

  • Performs a transaction asynchronously where NSManagedObject or CoreStoreObject creates, updates, and deletes can be made. The changes are commited automatically after the task closure returns. On success, the value returned from closure will be the argument of the success closure. Any errors thrown from inside the task will be wrapped in a CoreStoreError and reported in the failure closure. To cancel/rollback changes, call try transaction.cancel(), which throws a CoreStoreError.userCancelled.

    Declaration

    Swift

    public func perform<T>(asynchronous task: @escaping (_ transaction: AsynchronousDataTransaction) throws -> T, success: @escaping (T) -> Void, failure: @escaping (CoreStoreError) -> Void)

    Parameters

    task

    the asynchronous closure where creates, updates, and deletes can be made to the transaction. Transaction blocks are executed serially in a background queue, and all changes are made from a concurrent NSManagedObjectContext.

    success

    the closure executed after the save succeeds. The T argument of the closure will be the value returned from task.

    failure

    the closure executed if the save fails or if any errors are thrown within task. Cancelled tasks will be indicated by CoreStoreError.userCancelled. Custom errors thrown by the user will be wrapped in CoreStoreError.userError(error: Error).

  • Performs a transaction synchronously where NSManagedObject or CoreStoreObject creates, updates, and deletes can be made. The changes are commited automatically after the task closure returns. On success, the value returned from closure will be the return value of perform(synchronous:). Any errors thrown from inside the task will be thrown from perform(synchronous:). To cancel/rollback changes, call try transaction.cancel(), which throws a CoreStoreError.userCancelled.

    Throws

    a CoreStoreError value indicating the failure. Cancelled tasks will be indicated by CoreStoreError.userCancelled. Custom errors thrown by the user will be wrapped in CoreStoreError.userError(error: Error).

    Declaration

    Swift

    public func perform<T>(synchronous task: ((_ transaction: SynchronousDataTransaction) throws -> T), waitForAllObservers: Bool = true) throws -> T

    Parameters

    task

    the synchronous non-escaping closure where creates, updates, and deletes can be made to the transaction. Transaction blocks are executed serially in a background queue, and all changes are made from a concurrent NSManagedObjectContext.

    waitForAllObservers

    When true, this method waits for all observers to be notified of the changes before returning. This results in more predictable data update order, but may risk triggering deadlocks. When false, this method does not wait for observers to be notified of the changes before returning. This results in lower risk for deadlocks, but the updated data may not have been propagated to the DataStack after returning. Defaults to true.

    Return Value

    the value returned from task

  • Begins a non-contiguous transaction where NSManagedObject or CoreStoreObject creates, updates, and deletes can be made. This is useful for making temporary changes, such as partially filled forms.

    • prameter supportsUndo: undo(), redo(), and rollback() methods are only available when this parameter is true, otherwise those method will raise an exception. Defaults to false. Note that turning on Undo support may heavily impact performance especially on iOS or watchOS where memory is limited.

    Declaration

    Swift

    public func beginUnsafe(supportsUndo: Bool = false) -> UnsafeDataTransaction

    Return Value

    a UnsafeDataTransaction instance where creates, updates, and deletes can be made.

  • Refreshes all registered objects NSManagedObjects or CoreStoreObjects in the DataStack.

    Declaration

    Swift

    public func refreshAndMergeAllObjects()
  • Utility for creating an NSFetchedResultsController from the DataStack. This is useful when an NSFetchedResultsController is preferred over the overhead of ListMonitors abstraction.

    Note

    It is the caller’s responsibility to call performFetch() on the created NSFetchedResultsController.

    Declaration

    Swift

    @nonobjc
    public func createFetchedResultsController<D>(_ from: From<D>, _ sectionBy: SectionBy<D>, _ fetchClauses: FetchClause...) -> NSFetchedResultsController<D> where D : NSManagedObject

    Parameters

    from

    a From clause indicating the entity type

    sectionBy

    a SectionBy clause indicating the keyPath for the attribute to use when sorting the list into sections

    fetchClauses

    a series of FetchClause instances for fetching the object list. Accepts Where, OrderBy, and Tweak clauses.

    Return Value

    an NSFetchedResultsController that observes the DataStack

  • Utility for creating an NSFetchedResultsController from a DataStack. This is useful when an NSFetchedResultsController is preferred over the overhead of ListMonitors abstraction.

    Note

    It is the caller’s responsibility to call performFetch() on the created NSFetchedResultsController.

    Declaration

    Swift

    @nonobjc
    public func createFetchedResultsController<D>(_ from: From<D>, _ sectionBy: SectionBy<D>, _ fetchClauses: [FetchClause]) -> NSFetchedResultsController<D> where D : NSManagedObject

    Parameters

    from

    a From clause indicating the entity type

    sectionBy

    a SectionBy clause indicating the keyPath for the attribute to use when sorting the list into sections

    fetchClauses

    a series of FetchClause instances for fetching the object list. Accepts Where, OrderBy, and Tweak clauses.

    Return Value

    an NSFetchedResultsController that observes the DataStack

  • Utility for creating an NSFetchedResultsController from the DataStack. This is useful when an NSFetchedResultsController is preferred over the overhead of ListMonitors abstraction.

    Note

    It is the caller’s responsibility to call performFetch() on the created NSFetchedResultsController.

    Declaration

    Swift

    @nonobjc
    public func createFetchedResultsController<D>(_ from: From<D>, _ fetchClauses: FetchClause...) -> NSFetchedResultsController<D> where D : NSManagedObject

    Parameters

    from

    a From clause indicating the entity type

    fetchClauses

    a series of FetchClause instances for fetching the object list. Accepts Where, OrderBy, and Tweak clauses.

    Return Value

    an NSFetchedResultsController that observes the DataStack

  • Utility for creating an NSFetchedResultsController from the DataStack. This is useful when an NSFetchedResultsController is preferred over the overhead of ListMonitors abstraction.

    Note

    It is the caller’s responsibility to call performFetch() on the created NSFetchedResultsController.

    Declaration

    Swift

    @nonobjc
    public func createFetchedResultsController<D>(forDataStack dataStack: DataStack, _ from: From<D>, _ fetchClauses: [FetchClause]) -> NSFetchedResultsController<D> where D : NSManagedObject

    Parameters

    from

    a From clause indicating the entity type

    fetchClauses

    a series of FetchClause instances for fetching the object list. Accepts Where, OrderBy, and Tweak clauses.

    Return Value

    an NSFetchedResultsController that observes the DataStack