Explanation of NSIncrementalStore in plain english Explanation of NSIncrementalStore in plain english ios ios

Explanation of NSIncrementalStore in plain english


NOTE: this API was bleeding-edge when I wrote this in 2012 and details have changed. Feel free to update this if you wish. I'm not working on any Cocoa/ObjC projects at the moment so I am not a good person to keep this up-to-date, unfortunately. It does seem that the overall gist is correct.

Core Data provides a set of tools that help manage object persistence, i.e. the ability to save and then fetch back sets of objects (NSManagedObject) from some kind of storage.

When you work with Core Data objects, you do so using an NSManagedObjectContext, which you get from an NSPersistentStoreCoordinator. The PSC in turn talks to one or more NSPersistentStore subclasses, which handle the actual operations on the store. (Think create/read/update/delete against a database.)

Core Data supports two primary kinds of store: NSPersistentStore and NSAtomicStore. A persistent store can be thought of as a database: you can incrementally save, update and fetch arbitrary sets of records from it. An atomic store is an 'all or none' representation of an object graph. It is intended to be an in-memory representation of a structured file.

The store types that Core Data comes with are:

  • NSSQLLiteStoreType (NSPersistentStore)
  • NSInMemoryStoreType (NSPersistentStore)
  • NSXMLStoreType (NSAtomicStore)
  • NSBinaryStoreType (NSAtomicStore)

NSPersistentStore is explicitly forbidden to be subclassed, so until now, there has been no way to create your own non-atomic store backend. That is, if you wanted to persist and query representations of your objects piecemeal as opposed to in one big lump ('load the entire graph', 'save the entire graph') you've been out of luck. Until iOS5 introduced NSIncrementalStore.

NSIncrementalStore is an abstract class (descended from NSPersistentStore) whose methods you implement to provide an adapter between a data store that you control and the world of Core Data. You can use it to wrap a remote API, or if you were so inclined you could wrap something like NULevelDB or NanoStore (though I'm not sure why you'd do that).


You would use NSIncrementalStore to access a remote server through Core Data. In stead of reading from and writing to a local file, you'd push request to the server and get a response back which you'd push into Core Data. Likewise for save, etc.

Note, however, that this is non-trivial to do. It's a very powerful feature, but unless you're an expert in Core Data usage, I'd strongly discourage it, since there are endless opportunities to shoot yourself in the foot unless you know a lot about how Core Data's interaction with the storage layer works.

If using an uploaded solves your problem, then do that instead.


In a nutshell, if you use the SQLite store with your Core Data you are already using an incremental store. All the benefits of incremental stores (i.e. mainly not having to load the entire store into memory) are already at your disposal.

As for the concrete application of the NSIncrementalStore API, I would suggest that you first define exactly which problem you want to solve. If you require this API or not would be determined by the specific needs of your programming task.


EDIT in response to question edit

I would simply do it like this: In your Core Data entities on the device you can have an attribute BOOL uploaded. When the web service becomes available, start an upload and pull all the objects not uploaded yet.

To upload, transform your objects into NSArray and NSDictionary, perhaps into JSON format and POST to your web site. When the web site responds that it saved the data, mark all the objects as uploaded.