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
Background
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.
TL;DR
If you prefer, here is a video recording of everything that’s discussed in this blog post
Pre-requisites
- Xcode 8.3.3+ , latest version downloadable from Mac App Store
The Playground is compatible with Swift 3.1+
Installation
- Clone the couchbase-lite-ios-api-playground repo from GitHub by running the following command from the terminal
|
1 |
$ git clone https://github.com/couchbaselabs/couchbase-lite-ios-api-playground |
- 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
|
1 |
$ carthage version |
- 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.
|
1 |
$ cd /path/to/couchbase-lite-ios-api-playground/carthage |
- Download Couchbase Lite using Carthage. The version of Couchbase Lite used is specified in the Cartfile. We will use the
--no-buildoption to specify that carthage should not build the source but should only check out the files from the specified GitHub repo. This saves time.
|
1 |
$ carthage update –platform ios –no-build |
- Verify that the Couchbase Lite framework was succesfully checked out by running this command in your terminal
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
$ cd /path/to/couchbase-lite-ios-api-playground/carthage $ ls -l Carthage/Checkouts/couchbase-lite-ios/ total 24 -rw-r–r– 1 priya.rajagopal 141224203 957 Apr 11 17:06 CouchbaseLite.podspec drwxr-xr-x@ 6 priya.rajagopal 141224203 192 Apr 11 17:09 CouchbaseLite.xcodeproj -rw-r–r– 1 priya.rajagopal 141224203 987 Apr 11 17:06 CouchbaseLiteSwift.podspec -rw-r–r– 1 priya.rajagopal 141224203 10273 Apr 11 17:06 LICENSE drwxr-xr-x 117 priya.rajagopal 141224203 3744 Apr 11 17:06 Objective-C -rw-r–r– 1 priya.rajagopal 141224203 2426 Apr 11 17:06 README.md drwxr-xr-x 11 priya.rajagopal 141224203 352 Apr 11 17:06 Scripts drwxr-xr-x 70 priya.rajagopal 141224203 2240 Apr 11 17:06 Swift drwxr-xr-x 4 priya.rajagopal 141224203 128 Apr 11 17:06 docs drwxr-xr-x 4 priya.rajagopal 141224203 128 Apr 11 17:06 vendor drwxr-xr-x 13 priya.rajagopal 141224203 416 Apr 11 17:06 xcconfigs |
Setup
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)
|
1 |
$ mkdir ~/Documents/Shared\ Playground\ Data/ |
- 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.
|
1 2 |
$ cd /path/to/couchbase-lite-ios-api-playground/ $ cp -r travel-sample.cblite2 ~/Documents/Shared\ Playground\ Data/ |
- 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.
|
1 2 |
$ cd /path/to/couchbase-lite-ios-api-playground/ $ cp -r joindb.cblite2 ~/Documents/Shared\ Playground\ Data/ |
- Verify that the files were copied succesfully by using this command
|
1 |
$ ls -l ~/Documents/Shared\ Playground\ Data/ |
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.xcodeprojusing Xcode
|
1 2 |
$ cd /path/to/couchbase-lite-ios-api-playground/ $ open CBLTestBed.xcodeproj/ |
- You shoule see
CBLQueryPlayground.playgroundandCouchbaseLite.xcodeprojcontained within theCBLTestBed.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 ….
|
1 2 3 4 5 6 7 8 9 10 |
do { // Open or Create Couchbase Lite Database if let db:Database = try createOrOpenDatabase() { let results1 = try queryForDocumentsByTestingArrayContainment(db, limit: 5) print("\n*****\nResponse to queryForDocumentsByTestingArrayContainment : \n \(results1)") } } catch { print ("Exception is (error.localizedDescription)") } |
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.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
func queryForDocumentsOfSpecificTypeFromDB(_ db:Database,limit:Int = 10 ) throws -> [Data]? { let searchQuery = QueryBuilder .select(SelectResult.all()) .from(DataSource.database(db)) .where(Expression.property("type").equalTo(Expression.string("hotel"))) .limit(Expression.int(limit)) var matches:[Data] = [Data]() do { for row in try searchQuery.execute() { matches.append(row.toDictionary()) } } return matches } |
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 priya.rajagopal@couchbase.com. The Couchbase Forums are another good place to reach out with questions.
English
the
carthage update –platform ios –no-builddoes not work, it probably was meant to becarthage update –platform ios –-no-build?