--- title: "User Profile Sample: Couchbase Lite Query Introduction" pubDate: 2026-08-17T09:53:44.266Z antora: editUrl: https://github.com/couchbaselabs/userprofile-couchbase-mobile-android/edit/query/content/modules/userprofile-query-android/pages/userprofile_query.adoc xref: xref:tutorials:userprofile-query-android:userprofile_query.adoc[] --- [Consult the llms.txt file for a full list of contents](/llms.txt) [View original HTML](/tutorials/userprofile-query-android/userprofile_query.html) # User Profile Sample: Couchbase Lite Query Introduction ## [](#introduction)Introduction Couchbase Lite brings powerful querying and Full-Text-Search(FTS) capabilities to the edge. Its query interface is based on [N1QL](https://www.couchbase.com/products/n1ql), Couchbase's declarative query language, which implements the emerging SQL++ standard. The query API is designed using the [Fluent API Design Pattern](https://en.wikipedia.org/wiki/Fluent%5Finterface), and uses method cascading to read like a Domain Specific Language (DSL). This makes the interface very intuitive and easy to understand. Couchbase Lite can be used as a standalone embedded database within your mobile app. What You Will Learn This tutorial will walk through a simple Android app that will: * Demonstrate how you can bundle, load and use a **_prebuilt_** instance of Couchbase Lite * Introduce you to the basics of the `QueryBuilder` interface You can learn more about Couchbase Mobile [here](https://developer.couchbase.com/mobile) ## [](#prerequisites)Prerequisites This tutorial assumes familiarity with building [Android](https://www.android.com/)apps using [Java](https://www.java.com)and with the basics of Couchbase Lite. * If you are unfamiliar with the basics of Couchbase Lite, it is recommended that you walk through the [Standalone tutorial](../userprofile-standalone-android/userprofile%5Fbasic.md), covering the fundamentals of using Couchbase Lite as a standalone database * [Android Studio](https://developer.android.com/studio) * Android device or emulator running API level 22 or above * Android SDK 29+ * Android Build Tools 29+ * [JDK 8](https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html) * git (Optional) This is required if you would prefer to pull the source code from GitHub repo. * Create a [free github account](https://github.com)if you don't already have one * git can be downloaded from [git-scm.org](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) ## [](#app-overview)App Overview We will be working with a very simple "User Profile" app. If you have walked through the [Standalone tutorial](../userprofile-standalone-android/userprofile%5Fbasic.md), you will quickly realize that this version extends the functionality introduced in that tutorial. This app does the following: * Allows users to log in and create or update his/her user profile information, which was also possible in the [Standalone tutorial](../userprofile-standalone-android/userprofile%5Fbasic.md) * As part of profile information, users can now select a `University` from a list of possible options. This list of universities is queried (using the new Query API) from a local _prebuilt_ "University" Couchbase Lite database that is bundled in the app. * When saved, the user profile information is persisted as a `Document` in a local Couchbase Lite database. So, when the user logs back in again, the profile information is loaded from the `Database`. ![App Overview](_images/university_app_overview.gif) ## [](#installation)Installation Clone the **_query_** branch of the `User Profile Demo` solution from GitHub. Assuming that you have installed [Git](https://git-scm.com/downloads)you can use the following command to do this: ```bash git clone -b query https://github.com/couchbaselabs/userprofile-couchbase-mobile-android.git ``` ### [](#installing-couchbase-lite)Installing Couchbase Lite This [sample project](https://github.com/couchbaselabs/userprofile-couchbase-mobile-android/tree/query/content/modules/userprofile-query-android/examples/src)already contains the appropriate additions for downloading, and utilizing the Android Couchbase Lite dependency module. However, in the future, to include Couchbase Lite support within an Android app add the the following within [app/build.gradle](https://github.com/couchbaselabs/userprofile-couchbase-mobile-android/tree/query/content/modules/userprofile-query-android/examples/src/app/build.gradle). ```gradle dependencies { ... implementation 'com.couchbase.lite:couchbase-lite-android-ee:3.0.0' } ``` Try it out 1. Open [build.gradle](https://github.com/couchbaselabs/userprofile-couchbase-mobile-android/tree/query/content/modules/userprofile-query-android/examples/src/build.gradle)using Android Studio. 2. Build and run the project. 3. Verify that you see the login screen. ![User Profile Login Screen Image](_images/user_profile_login.png) ## [](#sample-app-architecture)Sample App Architecture The sample app follows the [MVP pattern](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93presenter), separating the internal data model, from a passive view through a presenter that handles the logic of our application and acts as the conduit between the model and the view. ![MVP Architecture](_images/mvp_architecture.png) In the Android Studio project, the code is structured by feature. You can select the Android option in the left navigator to view the files by package. ![MVP Android Studio](_images/mvp_as.png) Each package comprises the following: * **Activity**: This is where all the view logic resides. * **Presenter**: This is where all the business logic resides to fetch and persist data to a web service or the embedded Couchbase Lite database. * **Contract**: An interface that the `Presenter` and `Activity` implement. ![MVP Package](_images/mvp_package.png) ## [](#data-model)Data Model Couchbase Lite is a JSON Document Store. A Document is a logical collection of named fields and values. The values are any valid JSON types. In addition to the standard JSON types, Couchbase Lite supports some special types like `Date` and `Blob`. While it is not required or enforced, it is a recommended practice to include a _"type"_ property that can serve as a namespace for related. ### [](#the-user-profile-document)The User Profile Document The app deals with a single `Document` with a _"type"_ property of _"user"_. The document ID is of the form _"user::"_. An example of a document would be ```json { "type":"user", "name":"Jane Doe", "email":"jame.doe@earth.org", "address":"101 Main Street", "image":CBLBlob (image/jpg), "university":"Missouri State University" } ``` ### [](#user-profile)UserProfile For the purpose of this tutorial the _"user"_ `Document` is first stored within an `Object` of type `Map`. ```java Map profile = new HashMap<>(); profile.put("name", nameInput.getText().toString()); profile.put("email", emailInput.getText().toString()); profile.put("address", addressInput.getText().toString()); profile.put("university", universityText.getText().toString()); byte[] imageViewBytes = getImageViewBytes(); if (imageViewBytes != null) { profile.put("imageData", new com.couchbase.lite.Blob("image/jpeg", imageViewBytes)); } ``` The `Map` object functions used as a data storage mechanism between the app's UI and the backing functionality of the Couchbase Lite `Document` object. ### [](#university-document)The University Document The app comes bundled with a collection of Documents of type _"university"_. Each `Document` represents a university. ```json { "type":"university","web_pages": [ "http://www.missouristate.edu/" ], "name": "Missouri State University", "alpha_two_code": "US", "state-province": MO, "domains": [ "missouristate.edu" ], "country": "United States" } ``` ### [](#the-university-record)The University Record When _"university"_ `Document` is retrieved from the database it is stored within an `Object` of type `Map`. ```java Map properties = new HashMap<>(); (1) properties.put("name", row.getDictionary("universities").getString("name")); (2) properties.put("country", row.getDictionary("universities").getString("country")); (2) properties.put("web_pages", row.getDictionary("universities").getArray("web_pages")); (3) ``` ## [](#using-a-prebuilt-database)Using a Prebuilt Database There are several reasons why you may want to bundle your app with a prebuilt database. This would be suited for data that does not change or change that often, so you can avoid the bandwidth and latency involved in fetching/syncing this data from a remote server. This also improves the overall user experience by reducing the start-up time. In our app, the instance of Couchbase Lite that holds the pre-loaded _"university"_ data is separate from the Couchbase Lite instance that holds _"user"_ data hold the pre-loaded data. A separate Couchbase Lite instance is not required. However, in our case, since there can be many users potentially using the app on a given device, it makes more sense to keep it separate. This is to avoid duplication of pre-loaded data for every user. ### [](#location-of-the-cblite-file)Location of the cblite file The pre-built database is in the form of a `cblite` file. It will be be in your app project bundle * In the `universities.zip` file within the `Assets` folder. ![Prebuilt Database Location](_images/cblite_location.png) Note: The cblite folder will be extracted from the zip file. ### [](#prebuilt-database)Loading the Prebuilt Database * Open the [**DatabaseManager.java**](https://github.com/couchbaselabs/userprofile-couchbase-mobile-android/tree/query/content/modules/userprofile-query-android/examples/src/app/src/main/java/com/couchbase/userprofile/util/DatabaseManager.java)file and locate the `openPrebuiltDatabase()` function. The prebuilt database is common to all users of the app (on the device). So it will be loaded once and shared by all users on the device. ```java public void openPrebuiltDatabase(Context context) ``` * First, we create an instance of `DatabaseConfiguration` object and specify the path where the database would be located ```java DatabaseConfiguration config = new DatabaseConfiguration(); config.setDirectory(context.getFilesDir().toString()); ``` * Then we determine if the "universities" database already exists at the specified location. It would not be present if this is the first time we are using the app, in which case, we locate the _"universities.cblite"_ resource in the App's main bundle and we copy it over to the Database folder. If the database is already present at the specified Database location, we simply open the database. ```java if (!dbFile.exists()) { AssetManager assetManager = context.getAssets(); try { File path = new File(context.getFilesDir().toString()); unzip(assetManager.open("universities.zip"), path); universityDatabase = new Database("universities", config); createUniversityDatabaseIndexes(); } catch (IOException e) { e.printStackTrace(); } catch (CouchbaseLiteException e) { e.printStackTrace(); } } else { try { universityDatabase = new Database("universities", config); } catch (CouchbaseLiteException e) { e.printStackTrace(); } } ``` ### [](#indexing-the-prebuilt-database)Indexing the Prebuilt Database * Creating indexes for non-FTS based queries is optional. However, in order to speed up queries, you can create indexes on the properties that you would query against. Indexing is handled eagerly. * In the [**DatabaseManager.java**](https://github.com/couchbaselabs/userprofile-couchbase-mobile-android/tree/query/content/modules/userprofile-query-android/examples/src/app/src/main/java/com/couchbase/userprofile/util/DatabaseManager.java) file, locate the `createUniversityDatabaseIndexes()` function. We create an index on the `name` and `location` properties of the documents in the _university_ database. ```java private void createUniversityDatabaseIndexes() { try { universityDatabase.createIndex("nameLocationIndex", IndexBuilder.valueIndex(ValueIndexItem.expression(Expression.property("name")), ValueIndexItem.expression(Expression.property("location")))); } catch (CouchbaseLiteException e) { e.printStackTrace(); } } ``` ### [](#closing-the-database)Closing the Database When a user logs out, we close the Prebuilt Database along with other user-specific databases * In the [**DatabaseManager.java**](https://github.com/couchbaselabs/userprofile-couchbase-mobile-android/tree/query/content/modules/userprofile-query-android/examples/src/app/src/main/java/com/couchbase/userprofile/util/DatabaseManager.java) file, locate the `closePrebuiltDatabase()` function. ```java public void closePrebuiltDatabase() ``` * Closing the database is pretty straightforward ```java userprofileDatabase.close(); ``` Try It Out 1. The app should be running in the simulator 2. Log into the app with any email Id and password. Let's use the values _"[demo@example.com](mailto:demo@example.com)"_ and _"password"_ for user Id and password fields respectively. If this is the first time that _any_ user is signing in to the app, the pre-built database will be loaded from the App Bundle. In addition, new user-specific Database will be created / opened. 3. Confirm that the console log output has a message similar to the one below. In my example, I am logging in with a user email Id of _"[demo@example.com](mailto:demo@example.com)"_. ```bash 2019-06-12 13:07:12.542 24206-24206/com.couchbase.userprofile I/CB-Update: Will open Prebuilt DB at path /data/user/0/com.couchbase.userprofile/files ``` 4. The above log message indicate the location of the Prebuilt database as well as the Database for the user. This would be within the _files_ folder. ## [](#exploring-the-query-api)Exploring the Query API The Query API in Couchbase Lite is extensive. In our app, we will be using the `QueryBuilder` API to make a simple _pattern matching_ query using the `like` operator. ### [](#fetching-university-document)Fetching University Document From the "Your Profile" screen, when the user taps on the "University" cell, a search screen is displayed where the user can enter the search criteria (name and optionally, the location) for the university. When the search criteria is entered, the local _"universities"_ Database is queried for the [University](#university-document) documents that match the specified search criteria. * Open the [**UniversitiesPresenter.java**](https://github.com/couchbaselabs/userprofile-couchbase-mobile-android/tree/query/content/modules/userprofile-query-android/examples/src/app/src/main/java/com/couchbase/userprofile/universities/UniversitiesPresenter.java) file and locate the `fetchUniversities` function. ```java public void fetchUniversities(String name) { fetchUniversities(name, null); } public void fetchUniversities(String name, String country) ``` * We build the Query using the `QueryBuilder` API that will look for Documents that match the specified criteria. ```java Expression whereQueryExpression = Function.lower(Expression.property("name")).like(Expression.string("%" + name.toLowerCase() + "%")); (1) if (country != null && !country.isEmpty()) { Expression countryQueryExpression = Function.lower(Expression.property("country")).like(Expression.string("%" + country.toLowerCase() + "%")); (2) whereQueryExpression = whereQueryExpression.and(countryQueryExpression); } Query query = QueryBuilder.select(SelectResult.all()) (3) .from(DataSource.database(database)) (4) .where(whereQueryExpression); (5) ``` | **1** | Build a QueryExpression that uses the like operator to look for the specified _"name"_ string in the _"name"_ property. Notice couple of things here:(a) The use of **wildcard "%" operator** to denote that we are looking for the presence of the string anywhere in the _"name"_ property(b) The use of Function.lower() to convert the search string into lowercase equivalent. This is because the like operator does _case-sensitive matching_, so we must convert the search string and the property value to lowercase equivalents and compare the two. | | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **2** | If the location criteria was specified in the search, then Build a QueryExpression that uses the like operator to look for the specified _"location"_ string in the _"location"_ property. | | **3** | The SelectResult.all() specifiees that we are interested in all properties in Documents that match the specified criteria | | **4** | The DataSource.database(db) specified the Data Source | | **5** | We include the where clause that is the logical ANDing of the QueryExpression in <1> and <2> | * We run the Query by calling the `execute()` method on the Query that was constructed in the previous step ```java try { rows = query.execute(); } catch (CouchbaseLiteException e) { e.printStackTrace(); return; } List> data = new ArrayList<>(); Result row; while((row = rows.next()) != null) { Map properties = new HashMap<>(); (1) properties.put("name", row.getDictionary("universities").getString("name")); (2) properties.put("country", row.getDictionary("universities").getString("country")); (2) properties.put("web_pages", row.getDictionary("universities").getArray("web_pages")); (3) data.add(properties); } ``` | **1** | Create an instance of [UniversityRecord](#university-document) (via HashMap). | | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | **2** | Use specific type getters to fetch property values. The [UniversityRecord](#university-document) instance is populated with these property values. | | **3** | Getters also available for array types. This returns a Couchbase Lite ArrayObject type. | Try It Out 1. You should have followed the steps discussed in the "Try It Out" section under [Loading the Prebuilt Database](#prebuilt-database) 2. Tap on "University" table cell 3. You should see a screen show that allows you enter the search criteria for the university 4. Enter "Missouri State" for name . You can optionally enter "united states" for location 5. Confirm that you see a list of universities that match the criteria ![University List](_images/university_list.gif) 6. Select a university 7. Press "Done" button 8. Confirm that the university you selected shows up in the University table cell ![University Selection](_images/university_selection.gif) 9. You can optionally fill in other entries in the User Profile screen 10. Tap "Done" button 11. Confirm that you see an alert message "Succesfully Updated Profile". The Document will be updated this time. 12. Tap "Log Off" and log out of the app 13. Log back into the app with the same user email Id and password that you used earlier. In my example, I used _"[demo@example.com](mailto:demo@example.com)"_ and _"password"_. So I will log in with those credentials again. 14. Confirm that you see the profile screen with the _university_ value that you set earlier. ![Log Off and Log Back On](_images/profile_update.gif) ## [](#learn-more)Learn More Congratulations on completing this tutorial! This tutorial walked you through an example of how to use a pre-built Couchbase Lite database. We looked at a simple Query example. Check out the following links for further details on the Query API. Further Reading * [Fundamentals of the Couchbase Lite Query API](https://blog.couchbase.com/sql-for-json-query-interface-couchbase-mobile/) * [Handling Arrays in Queries](https://blog.couchbase.com/querying-array-collections-couchbase-mobile/) * [Couchbase Lite Full Text Search API](https://blog.couchbase.com/full-text-search-couchbase-mobile-2-0/) * [Couchbase Lite JOIN Query](https://blog.couchbase.com/join-queries-couchbase-mobile/)