iPhone in Action

Errors: The model used to open the store is incompatible (and other Core Data errors)

On one of my first trials with Core Data, I found that my program started crashing for no particular problem a couple of days after I'd start working with my particular data model. Looking at my log file I could see the crash, but not really what was causing it. This highlights one of the first problems with the Core Data: though it creates some default methods for setting up your managed object model, your managed object context, and your persistent store coordinator, it does no error management or reporting, instead somewhat unhelpfully offering the comment "Handle error".

Reporting Core Data Errors

So, if you're facing a mysterious Core Data error, that means that you probably should have filled in some error reporting in those places. It's easy enough to do, as the default templates set up NSError objects and fills them. All you have to do is, at the simplest level, report out the results to NSLog. Here's an example of "handling the error" in the Persistent Store Coordinator:

if (![persistentStoreCoordinator addPersistentStoreWithType:NSSQLiteStoreType configuration:nil URL:storeUrl options:nil error:&error]) {
    NSLog(@"Could Not Start Persistent Store: %@, %@", error, [error userInfo]);
}

You could do something similar in each other place marked as "handle error" in the standard Core Data templates. Once you've done that you'll then be able to extract errors from your "system.log"  that will be more sensible than the crash you were seeing, but may still be somewhat confusing.

Solving the Incompatible Store Error

Here's the complete text of the error I got out of my crashing Core Data program once I reported the Core Data errors:

The model used to open the store is incompatible with the one used to create the store

You'll see this error if you've made a change to your data model (the creation of which was described in Core Data, part 2) without reinitiating your program from scratch afterward.

If you've been testing things on your iPhone or in the Simulator, this means you must totally delete the previous build of your program from your iPhone/Simulator, to get rid of the data that's hiding there in the Documents folder from your previous usage.

If you've prefilled a database (as I'll discuss in Core Data, part 4), you must redo that prefilling.

I find the fact that a program chokes rather than the data model updating itself rather unfriendly, and I'm not sure of the best way to resolve the issue if you've got a live app that you want to improve (though if you have ideas for that, please post them in the comments below). However if you're just running into an error because you're modifying your model as you develop a program, this article should tell you everything you need to know.

Next Up: Core Data reading and writing.

Core Data, Part 2: The Data Model

See Part 1 for the start of this series on Core Data.

In the previous article, I talked about the three main elements of Core Data: the Managed Object Model, the Managed Object Context, and the Persistent Storage Coordinator. This article expands on the Managed Object Model, explaining how to easily create the data structures for your Core Data program.

Using the Data UI

Xcode makes it really easy to set up a data structure to use. Once you've created a Core Data project (as discussed in the previous article) all you need to do is click on your .xcdatamodel file, which you'll find in the "Resources" folder of your Groups & Files.

When you click on the file, you'll see a little data editor that features several different elements. Across the top are panels for "Entities" and "Properties". To the right of that is a space for an editing panel that'll be empty until you click on an entity or property. Across the bottom is what looks like a sheet of graph paper; it'll be filled with your interconnected entities when you create them.

The following graphic shows an example of a filled-in data model:

Here's what all the elements are:

Entity. This is an individual data object. In a database it would be a table. In the above example, "Card", "CardText", "CardPics", "CardPower", and "Cardstack" are all entities. To create one you just click the "+" symbol in the entity window. Afterward you'll need to fill it with properties (which includes attributes and relationships).

Property. A property in Core Data is pretty much the same thing as a property in the rest of Objective-C; it's an individual variable within an object (or here, within an entity). There are two types of properties: attributes and relationships. You can create either one by first clicking on an Entity in the entity window, then clicking on the "+" in the property window. You'll be given the option to create an attribute or a relationship.

Attribute. This is a individual variable stored inside an object, which is stored as a sort of property. In a database it'd be a column. Once you've created an attribute (as discussed above, under "property"), you must set its type. This can either be done by clicking in the "Type" column within the property panels or else by clicking generally on the attribute, then filling in data in the editing panel, to the right. Once you've named your attribute and set its type, you're usually done with it ... though some more work is possible.

One of the cool things about Core Data is that you can use it to help manage your variables by setting minimum, maximum, and default values (though these are all optional--unlike the attribute type).

Relationship. A relationship is a connection from one entity to another. It's stored as a type of property. In a database a relationship would be represented by a join from one table to another. The fact that you can just set it up as a relationship in Core Data is another big advantage, because you don't have to worry about giving your tables unique IDs that they can join on, nor do you have to worry about indexing your tables to make their lookups and joins efficient. Instead, you can just deal with the data!

When you create a relationship you'll need to further define it in the editing panel to the right (after you click on the relationship to bring that panel up).

First you must define the Destination. This is the table (entity) that you're joining to.

Then you must define if it is a "To-Many" relationship. If your Entity has a "To-Many" relationship, that means that it's connected with multiple versions of the other entity. For example, imagine that you have three Entities in a model: a magazine Entity, a cover Entity, and a page Entity. Each magazine has a one-to-one relationship with a cover (which doesn't require any additional work: a one-to-one relationship is the default assumption for a relationship) but it has a one-to-many relationship with pages (which requires you to check the "to-many" box).

Usually you'll want to set up a reflective relationship. If one entity links to a second one, the second one should also link to the first. In the above example, the pages should know which magazine they go with. To allow this, set up a relationship in each direction, and then when you're done click on the "inverse" pop-up of one of the two reflective relationships and set it to the other. Where your graph-paper diagram previously showed two arrows, now it should show one (with arrow-heads on each side).

If you look at the graph in the image above, you should now be able to puzzle it out. Each of the five Entities has a number of Attributes and some Relations. The Relations are sometimes one-to-one (with one arrow) and sometimes one-to-many (with two arrows). They're all reflective.

With a good knowledge of these basic ideas in hand, you should now be able to design a data model, just as easily as if you were creating tables in a database.

Creating Entity Classes

With the above methodology, you can create entities that you'll be able to use from within your Objective-C code, accessing and setting properties. However, sometimes you'll want to do more than just read and write data, such as designing special default information, minimums, and maximums that go beyond the simple data that you can enter from the data designer. In order to do this type of work, you'll want to create a class associated with an entity.

To do this, click on an individual entity inside the modeler and then chose "File > New File". You should see as an option for the file type "Managed Object Class". Select that, and you'll be given a list of all your entities. If you click on one, a subclass of NSManagedObject will be created for the entity in question.

The actual use of that new subclass is beyond the scope of at least the next few articles, but keep it in mind when we start talking about the standard stuff that you can have an entity do, as whenever you access an NSManagedObject class that's the exact sort of thing that you can create a special version of.

Next Up: An annoying error.

Core Data, Part 1: An Introduction

In my last post I published SKDatabase, a more complete database library than we were able to offer in iPhone in Action. But, when I did, I noted that it was already obsolete, thanks to the inclusion of Core Data in iPhone OS 3.0. And that's the topic of this post. To complement the information that we offered in chapter 16 of iPhone in Action, covering lots of different ways to read and store data, I'll be writing about the new functionality of Core Data over the next several posts.

What Core Data Is

Core Data is an abstract data model. You'll generally interact only with the front end of Core Data, telling it what data to retrieve, what data to modify, and what data to save. Though you can define a specific type of storage to use (such as a database or an XML file), you are not required to, and generally you don't need to know the details of what sort of data storage is being used at all.

The object of Core Data is to free you from worries about anything but the data objects themselves, and though I find some of the terminology of Core Data a bit overly complex, once you get past that, the actual system has a lot to recommend it.

Core Data will, however, take some time to learn, and if you're just programming a one-time piece of software, and you don't have the time to learn a whole new system, then you might want to stick with something you already understand, such as one of the other methods we cover in chapter 16, or the expanded database library which I recently posted. But if you plan to do lots of iPhone programming involving data storage, then ... read on ...

Core Data's Three Main Concepts

Core Data centers around three main concepts (and two subconcepts). I find their names to be very intimidating, but once you get past them, they make sense as object-oriented data elements.

The Managed Object Model. Before you can do any data storage, you need to define what data you're  storing. The Managed Object Model is that definition. Under SQL, it'd be the structure of your tables: how many tables there are, how many columns each table has, and what data type each column uses. Under the Managed Object Model, tables become entities, columns become attributes, and relationships represent table joins ... but in general, they're the same things with fancy names.

By extension, a Managed Object is an individual data element.

The Persistent Storage Coordinator. This is what actually stores your data for you. It integrates your Managed Object Model (data structure) with your Persistent Store. The store itself, to do away with Apple's ten-dollar words, is simply the back-end that you're storing to. By default it's a SQLite database.

A Peristent Storage Coordinator can be a little fancier than this suggests. It can actually manage a number of different Persistent Stores, and make sure that you don't have to worry about which data elements are being stored where. But at the most basic level, you can just consider the Persistent Storage Coordinator to be the thing that turns your program's data into stored data.

The Managed Object Context. This is the one element in Core Data that doesn't have a simple correlation with the data work that you've already been doing. The Managed Object Context is like a whiteboard. It's a temporary storage area. You can pull things out of your Persistent Store and write them to the Context; from there you can directly access the data from your program. Likewise you can modify the data in the Context and you can write new data to it.

So how is the Managed Object Context separate from the Persistent Store? Most notably, it's temporary. Often times, you'll tell Core Data to save information to the Persistent Store (via the Persistent Storage Coordinator) as soon as you enter that data--but you could also use the Managed Object Context to store totally ephemeral information, without changing your startup date.

Go back and reread those definitions until you're comfortable with them. If you have them in hand, Core Data will be a lot less intimidating.

Getting Started

The easiest way to get started with Core Data is create a "New Project" that is a "Window-based Application". When you select the Window-based template, you should see a checkbox under options that says "Use Core Data for storage". If you check that, your new project will be all set up for Core Data.

When you look at your new project, you'll see that the AppDelegate's header file includes three properties: managedObjectModel, managedObjectContext, and persistentStoreCoordinator. These define the three elements that we've just been discussing. For many Core Data programs, you'll only need to deal with the managedObjectContext property.

You'll also see some standard method calls within the AppDelegate for managedObjectContext, managedObjectModel, and persistentStoreCoordinator. You probably won't have to mess with those at all, though do note that the last method is the one that sets a SQLite file as the default sort of Persistent Store.

Finally, in your "Resources" section (in the column to the left of Xcode), you should see a .xcdatamodel file. That's the file which contains the actual data structure for your project--or the Managed Object Model if you prefer. It's really easy to set up, thanks to a built-in Xcode UI, which will be the topic of the next article in this series.

Coming Next: Part 2: Designing the Data Model.