Core Data Lab

Tips and Tricks


Core Data Lab is an app to view and track the SQLite data of a Core Data app. It shows all entities, attributes and relationships conform the object model. The app includes tools to view, filter, edit and export data, to track data changes, to inspect the model, and more.

Core Data Lab is a project based app. All settings regarding selected database and object model combinations are stored in a project document file together with other settings like ad-hoc data filters.

To properly view the data inside a Core Data database, the associated Core Data object model file is needed. This concerns the compiled object model file with a .mom extension, not the object model in your Xcode project. The compiled object model file is normally located in a sub folder ending with .momd of the Resources folder within an app bundle. Core Data Lab doesn't bother you with browsing within app bundles, you simply select an app to select the associated model file.

Core Data Lab saves selected database and object model combinations in a project file, so you don't have to reselect the same files again each time you want to work with the data of your Core Data app.

There are several ways to make a new project in Core Data Lab:

The most flexible way to start a new Core Data Lab project is by using the Project assistant.

  • Choose File > New Project > Project Assistant in the menu.
  • Follow the instructions.

After making a new project, you can always adjust all choices you made earlier in the Project assistant.

If you app concerns an iOS, iPadOS, watchOS or tvOS app which has been run in a simulator, you can make a new Core Data project by simply selecting the database and app combination in the Simulator browser.

  • Choose File > New Project > Browse Simulators in the menu.
  • Select a device in the left panel of the Simulator browser.
  • Select an app and database combination in the right panel of the Simulator browser.
  • Confirm your selection by clicking on the Select button.
  • A new project will be opened based on the selected app and database.

After selecting a Core Data app, you can start a search action for matching databases.

  • Choose File > New Project > Select App… in the menu.
  • Select a Core Data app in the open file dialog.
  • Confirm by clicking on the Select App button.
  • Choose Project > Search Database in the menu.
  • The Search database dialog is being opened.
    • If this is the first time, an additional dialog is presented to select a default search path.
    • Otherwise the search dialog will start immediately to search for databases that match one of the Core Data object models in the selected app.
    • You can cancel the running search operation at any time, and select another search path by clicking on the Search Path button.
  • Select a database from the search results list and click on the Select Database button.

After selecting a Core Data object model, you can start a search action for matching databases.

  • Choose File > New Project > Select Model… in the menu.
  • Select a Core Data object model in the open file dialog.
  • Confirm by clicking on the Select Model button.
  • Choose Project > Search Database in the menu.
  • The Search database dialog is being opened.
    • If this is the first time, an additional dialog is presented to select a default search path.
    • Otherwise the search dialog will start immediately to search for databases that match the selected Core Data object model.
    • You can cancel the running search operation at any time, and select another search path by clicking on the Search Path button.
  • Select a database from the search results list and click on the Select Database button.

After selecting a Core Data database, you can start a search action for matching apps.

  • Choose File > New Project > Select Database… in the menu.
  • Select a SQLite based Core Data database in the open file dialog.
  • Confirm by clicking on the Select Database button.
  • Choose Project > Search App in the menu.
  • The Search app dialog is being opened.
    • If this is the first time, an additional dialog is presented to select a default search path.
    • Otherwise the search dialog will start immediately to search for apps that matches the selected Core Data database.
    • You can cancel the running search operation at any time, and select another search path by clicking on the Search Path button.
  • Select an app from the search results list and click on the Select App button.

After selecting a database, you can manually select an app. Or vice versa.

  • Choose File > New Project > Select Database… in the menu.
  • Select a SQLite based Core Data database in the open file dialog.
  • Confirm by clicking on the Select Database button.
  • Choose Project > Select App in the menu.
  • Select a Core Data app in the open file dialog.
  • Confirm by clicking on the Select App button.
  • Core Data Lab will check whether the selected combination is compatible. A warning will be shown when this is not the case, otherwise the selected combination will be loaded in the project window.
Sidebar

The sidebar on the left side of the document window shows the following item categories:

  • Entities: a Core Data object model always contains at least one or more entities.
  • Fetch Requests: this category is only shown when you have defined one or more fetch requests in the Core Data object model.
  • Saved Predicates: all predicates you have made and saved in Core Date Lab are listed here.

You can filter items in the sidebar by using the filter box at the bottom of the sidebar.

List view

The middle and main part of the Core Data Lab document window shows the data of the item selected in the sidebar, presented as a table view. You can change the sorting of the presented data by clicking on the header of the column that you want to sort on.

Relationships viewer

If the project consists of a valid database and object model, you'll see two sub panels at the lower side of the document window. The first sub panel shows data related to the selected row according to the selected relationship in the dropdown situated on top of the sub panel. With this dropdown you can switch to another relationship, if available.

Content viewer

If the project consists of a valid database and object model combination, you'll see two sub panels at the lower side of the document window. The second sub panel is a field level viewer. It shows only the content of one field of the selected row in the main list view or a selected row in the relationship view. The dropdown on top of the content viewer let you switch to any field of the entity of the selected row. Default the first field is being shown. The content view automatically detects and shows web site URL's, image URL's, XML URL's, JSON URL's. In addition to this it also detects and show the content of binary fields containing images, XML, JSON or PLIST data.

Details view

The panel on the right side shows all fields of the selected row in one vertical column. If you have opened the database with a valid object model, you can also edit the data, unless you have opened the database as read-only. As soon as you have changed a field value, a Cancel and Save button pair will be shown at the bottom of the Details view panel. Clicking Cancel will revert all data changes, clicking Save will store all changes you have made for the selected data row.

Details window

If you want to edit the data of a row in a more spacious view, then you can open a row in a separate window or tab. Double-click a row to open the data in a window, or use the context menu of a selected row to open the data in a tab.

If an entity is selected in the sidebar, you can filter the related data by using the Predicate editor, which becomes visible after clicking on the filter button in the toolbar.

  • The first row in the predicate editor defines whether all, some or none of the conditions must be true. You may change this, but in most cases you need the default 'All' setting.
  • The second and up following rows in the middle panel of the Query editor consists of 2 or more rows, representing selection criteria and conditions:
    • Click on the + button on the right side to add a new condition row.
    • Click on the - button to remove a condition row.
    • The first drop down in the condition row is filled with selection criteria fields related to the selected entity. Make adjustments if needed.
    • The second drop down in the condition row is the operator that being applied to the selected criteria field. Adjust this if needed.
    • Depending on the selected operator, a third entry field is presented. Enter the criteria value that you want to use as a filter condition.
    • Apply the current combination of conditions rows to the current view by pressing Enter on the keyboard.
  • You can save a predicate by clicking on the Save button. This will also save the sorting of the table view, if you have changed this.

Anytime data is saved in a Core Data managed object context connected to a SQLite based persistent store, the related database files will change. These changes are monitored by Core Data Lab and can be used to track data changes.

  • Click on the Start button in the toolbar to start tracking data changes, or choose Data > Track Changes in the menu.
  • Data changes are displayed with distinctive background colors:
    • Mutated data is being presented with a purple background. Each tracked change will be presented in a separate row, changed data is being displayed with a dark font color, unchanged data with a grayed out font color.
    • Created data is being presented with a green background. Subsequence changes to a new data row are treated as data mutations, and do have a purple background.
    • Deleted data is being presented with a red background.
  • Tracking colors can be changed in the Colors section of the Core Data Lab Preferences.
  • All tracked data changes can be exported by using menu Data > Export to JSON or menu Data > Export to CSV.
  • Click on the Stop button in the toolbar to stop tracking data changes or choose Data > Stop Tracking in the menu.

Data of a selected row can be edited in the Details panel or a Details window, when the database is opened together with a valid Core Data object model.

Details view

The panel on the right side of the project window shows all fields of the selected row in one vertical column. As soon as you change a field value, a Cancel and Save button pair will be shown at the bottom of the Details view panel. Clicking Cancel will revert all data changes, clicking Save will store all changes you have made for the selected data row.

Details window

If you want to edit the data of a row in a more spacious view, then you can open a row in a separate window or tab. Double-click a row to open the data in a window, or use the context menu of a selected row to open the data in a tab.

Data can be exported to JSON or CSV format, if the project contains a valid database and object model combination.

  • To export all content of any item selected in the sidebar, or just the content of one selected row, choose Data > Export to JSON or Export to CSV in the menu.
  • An open file dialog will be presented, to select a target file name.

The project settings dialog shows the full paths of the database and object model or related app, their reachability status and whether the combination is compatible. You can also prevent any editing of the database in Core Data Lab by clicking on the Read-only check button.

The following settings can be changed in the Preferences dialog, and apply to all projects:

General preferences

The File Access section shows access paths needed for the search forms and simulator browser. If needed you can change any path by clicking on the Change button.

  • Home directory: is being used by the Simulator browser.
  • App search directory: is being used by the App search form. This path also be changed in search form.
  • Database search directory: is being used by the Database search form. Can also be changed in the search form itself.

In the New Projects section you can change the default directory for saving new projects.

Search preferences
In the App Search section you can fine tune settings that are used by the App search form:
  • Skip paths containing: this token field contains all paths segments that should be skipped when searching for an app for a selected database.
  • Skip hidden paths: when enabled, hidden paths will be skipped when searching for a matching app.
In the Database Search section you can fine tune settings that are used by the Database search form:
  • Skip paths containing: this token field contains all paths segments that should be skipped when searching for a database for a selected app or model.
  • Only include files with extension: when disabled, all files in the set database search path will be checked for compatibility. This can be extremely time consuming. When enabled, only files with extensions listed in the token field under the checkbox will be checked for compatibility.
  • Skip hidden paths: when enabled, hidden paths will be skipped when searching for a matching database.
Colors preferences
This section lets you change the background colors that are used when tracking data changes.
Tables preferences
This section lets you change the alignment of numeric columns, and lets you set the default width of string and numeric columns.
This section lets you change the styling of the table view grids.
Advanced preferences
Determines how tabbed detail windows are attached to an existing window:
  • Main document window: the tab is added to the document window.
  • First standalone window: the tab is added to the first standalone window. If there is no any standalone window, the tab is opened as a separate window.
  • Last standalone window: the tab is added to the last standalone window. If there is no any standalone window, the tab is opened as a separate window.