A hands-on guide to the CloudKit dashboard

If you already finished all the Hacking with Swift projects so far, you'll know I hate tangents. I'm here to teach you something cool, and I prefer to do that using as little waffle as possible – and tangents are apt to create the Perfect Storm for waffle. But in this case it's important, so please bear with me.

If you haven't already done so, you need to run your app, record a whistle, and tap Submit now. All being well it will work first time (if not you probably missed something!), but how do you know it's worked? I mean really be sure that's it worked? And what do you do if you want to change a data type because you made a mistake, or perhaps even delete the whole thing and start again?

Apple has a solution for this, and it's called the CloudKit Dashboard. Now that you have submitted your first record to iCloud, you can launch https://icloud.developer.apple.com/dashboard in your web browser and look behind the iCloud curtain as it were. The CloudKit dashboard shows you exactly what data your app is storing, who can access it, and how much of your free quota you're using.

So, just briefly, it's time for a tangent: I want to explain a few things about CloudKit Dashboard, because it's important. Yes, it is important – later code won't run unless you read my instructions, so please don't skip ahead.

When you log into CloudKit Dashboard, you may need to select your project in the top-left corner of the window. The default view you'll see is Schema > Record Types, and you'll see two Record Types already there: Users and Whistles. The first of those was created automatically for you by Apple, and tracks anonymized user IDs for your app. The second of these was created by you just a few minutes ago: as soon as you called saveRecord() CloudKit transformed your record into a database in iCloud, and added your test whistle there.

If you select the Whistles record type you'll see that CloudKit has identified that the comments and genre fields are both strings, and the audio field is an asset. You'll also see a line saying "Metadata Indexes" with the number 1 and an arrow below it. Please click that now to reveal some fields that CloudKit has created for you: ID, Created By, Date Created, Date Modified and Modified By. These are great for searching, but you can't sort using these fields by default.

We're going to want to sort by the Date Created field later on, so please click Sort next to Date Created. While you're there, please also check Query next to ID so that we can query all records easily. With that done, click the Save button in the bottom-right of your browser window to commit that change.

That was the critical stuff needed to continue this tutorial, but there are a few other niceties while you're here:

Any of your rows can be deleted by hovering over them and clicking the X on the right-hand side. System rows like Created By cannot be deleted.

You can add fields by clicking the Add Field button at the end of your own fields, then giving it a name and type.

You can browse all the data that has been uploaded by clicking Default Zone in the left-hand menu and choosing a schema name.

When browsing individual records, you'll see links to download or remove the assets attached to the record.

You'll also see a trash icon above the record, which is what you click when you want to delete it.

So, the CloudKit Dashboard is basically a miniature CMS that lets you peek into your data and confirm everything is working OK. But it does one more thing, which is to provide usage data for your app, which is important because CloudKit is free only if you stay below certain usage limits.

To see how much of your quota you're using, click Usage now from the left-hand menu. You'll see a scrolling list of charts that show you how many users you have, how many requests per second they've made, how much storage data transfer you're using for assets, and how much database storage you're using. CloudKit shows you a solid line to represent how much you've actually used, then a dashed line to show its projections about how much you're likely to use if current trends continue.

Note that all quota directly depends on the number of users you have – as you add more users, Apple adds more quota. So, the first graph directly affects all the others.

What these charts don't show is how your usage maps against your quota, and there's a good reason for that: as soon as you add in your quota, your usage becomes so tiny that you won't be able to see it! Don't believe me? Try it now: at the top right of each chart are check boxes saying either "Usage" and "Quota", or "Usage" and "Limit" – select the one that is currently unchecked, and you'll see what I mean.

So, that's CloudKit Dashboard: it's the perfect debugging tool because it shows you exactly what content is being stored. If the data you see is bad it means your writing code is bad. If the data there is good but your app isn't showing correctly, it means your reading code is bad. Simple!

Tangent over. Back to the code!

Go from iOS to macOS the easy way!

If you like Hacking with Swift, you'll love Hacking with macOS – learn to build macOS apps today, using 18 real-world projects!