This post is a step-by-step guide for using an Xcode Playground for exploring the new querying API in Couchbase Mobile 2.0. The Couchbase Lite 2.0 Release introduces a simplified query API based on N1QL, Couchbase’s declarative query language that extends SQL for JSON. If you are familiar with SQLite, you will feel right at home with the new Query Builder interface . The query API is designed using the Fluent API Design Pattern, and it uses method cascading to read to like a Domain Specific Language (DSL). This makes the interface very intuitive and easy to understand.

The Xcode Playground is an interactive environment that allows you to write and execute swift code immediately, and offers a convienent way to learn and explore APIs without having to create a full-blown Xcode App project. This is a perfect use case for exploring the Coucbase Lite 2.0 API. We will not be creating a playground here. We will be using one that we have put together specifically for Query API testing.

While the Xcode playground demonstrates the queries in swift, given the unified nature of the QueryBuilder API across the various Couchbase Lite platforms, barring language specific idioms, you should be able to easily translate the queries to any of the other platform languages supported in Couchbase Lite. So, even if you are not a Swift developer, you should be able to leverage the Xcode playground for API exploration. This post makes no assumptions about your familiarity with Swift or iOS Development so even if you are a complete newbie to iOS development, you should be able to follow along. Of course, you would need a Mac!

You can learn more about the QueryBuilder API in our API References guide.

Recommended Reading

These blog posts discuss the various querying capabilities in detail
Fundamentals of the Query API
Query of Array Collections
Full Text Search capabilities.
Basic JOIN Query


If you were using 1.x versions of Couchbase Mobile, you are probably familiar with Map-Views for creating indexes and queries. In 2.0, you no longer have to create views and map functions! Instead, a simple interface allows you to create indexes and you can use a Query Builder interface to construct your queries. The new query interface is simpler to use and much more powerful in comparison.


If you prefer, here is a video recording of everything that’s discussed in this blog post


The Playground is compatible with Swift 3.1+


  • Clone the couchbase-lite-ios-api-playground repo from GitHub by running the following command from the terminal

  • We will use Carthage to download and install CouchbaseLite. Carthage is a dependency management system for Cocoa Applications. Note that Couchbase Lite for iOS is distributed through Cocoapods , Carthage or you can download it directly from our Downloads page. We will be using Carthage here.
    If you do not have Carthage, please follow these instructions to install Carthage on your MacOS
  • Verify your carthage installation by typing following command in your terminal window. The version of carthage installed will be displayed

  • Switch to the folder containing the Cartfile. This is located in the carthage folder. The Cartfile specifies the project dependencies, which in our case is the Couchbase Lite framework.

  • Download Couchbase Lite using Carthage. The version of Couchbase Lite used is specified in the Cartfile. We will use the --no-build option to specify that carthage should not build the source but should only check out the files from the specified GitHub repo. This saves time.

  • Verify that the Couchbase Lite framework was succesfully checked out by running this command in your terminal


We will be using two pre-built Couchbase Lite databases to exercise our queries. In order for the Xcode Playground to be able to access these databases, they must be located in a special “Shared Playground Data” folder within the Documents folder on your Mac.
The following steps are required the first time you are setting up for Playground. Subseqently, you will have to follow these steps only if you are changing the database.

  • Create a folder named “Shared Playground Data” within your “Documents” folder on your Mac (if one does not exist)

  • Copy the “travel-sample.cblite2” folder that is pulled from the couchbase-lite-ios-api-playground repo into the “Shared Playground Data”. This prebuilt database will be used for trying out the queries.

  • Copy the “joindb.cblite2” folder folder that is pulled from the couchbase-lite-ios-api-playground repo into the “Shared Playground Data”. This prebuilt database will be used for trying out the queries related to JOINs.

  • Verify that the files were copied succesfully by using this command

Exploring the Project

Earlier in this post, I mentioned that the Xcode Playground does not require a full-blown App Project. That is still true. However, in our case, we need to be able to build and link the CouchbaseLite.framework with the Playground. There may be other options but the way I did it was to create a dummy Xcode project called CBLTestBed.xcodeproj that includes the Playground as well as the CouchbaseLite.xcodeproj.

So when I build the CBLTestBed project, it would build the CouchbaseLiteSwift framework that is then imported by the Playground. Let’s examine this further.

  • Open the CBLTestBed.xcodeproj using Xcode

  • You shoule see CBLQueryPlayground.playground and CouchbaseLite.xcodeproj contained within the CBLTestBed.xcodeproj
  • Let’s examine the CBLQueryPlayground.playground. You should see several playground pages in your project explorer. You can begin with any Playground page but it would probably be most logical to begin with the “ToC” page. This is the “Table Of Contents” and provides an entry point to other pages.
  • Check “Render Documentation” checkbox in the Utilities Window to turn on rendering of the playground pages
  • From the “ToC” page, you can navigate to any of the other playground pages. Each playground page includes a set of Query examples that exercises the query API against the “travel-sample.cblite” database or the “joindb.cblite” database as appropriate. As discussed in the “Setup” section, these databases are located in the “~/Documents/Shared\ Playground\ Data/” folder.
  • Every Playground page follows the same pattern. We open the local database and then invoke functions that does the querying using the QueryBuilder API.
    So, this is the basic structure ….


Build and Run

In order to be able to execute the Playground, you would have to first build the CouchbaseLiteSwift framework. You can do this by building the containing CBLTestBed.xcodeproj.

  • Select the “CBLTestBed” scheme and select a simulator as target. Build the project using Cmd-B.
  • Once the project is succesfully built, you can execute a playground by clicking on the “Run” button
  • The results should be displayed in the output console
  • Of course, since this is a playground, you can also examine the results inline

Exploring other Query Options

The queries provided with the sample playground are intended to be used as a reference. It should be straightforward to see that you can update the queries to explore other querying options.

So, for instance, in example below,  change the “type” property and “limit” value to something else and see what happens to the results. You can add you own queries as well.


What Next

This blog post demonstrated the use of Xcode Playgrounds as a convienent way to explore and test the new query API in Couchbase Mobile 2.0. If you would like to add new queries, please submit a Github PR.

If you have questions or feedback, please leave a comment below or feel free to reach out to me at Twitter @rajagp or email me  The Couchbase Forums are another good place to reach out with questions.



Posted by Priya Rajagopal, Senior Director, Product Management

Priya Rajagopal is a Senior Director of Product Management at Couchbase responsible for developer platforms for the cloud and the edge. She has been professionally developing software for over 20 years in several technical and product leadership positions, with 10+ years focused on mobile technologies. As a TISPAN IPTV standards delegate, she was a key contributor to the IPTV standards specifications. She has 22 patents in the areas of networking and platform security.

One Comment

  1. the carthage update –platform ios –no-build does not work, it probably was meant to be carthage update –platform ios –-no-build?

Leave a reply