The Basics


To get started, you must initialize Couchbase Lite with the relevant application context Open the file

public DbManager(@Nonnull DbExecutor exec) {
    this.exec = exec;


    final ConsoleLogger logger = Database.log.getConsole();

Create a Database

There is no limit to how many databases can be created or opened on the device. You can think of a database as a namespace for documents and several databases can be used in the same app (one database per user of the app is a common pattern).

The snippet below creates an empty database for the guest user in a directory named guest.

Open the file We will review the openGuestDb() method.

 public void openGuestDb() {

We create a folder for the guest user database if one does not exist and specify that as the database directory in the DatabaseConfiguration object.

  final DatabaseConfiguration config = new DatabaseConfiguration();
  config.setDirectory(new File(DB_DIR, GUEST_USER).getCanonicalPath());

The Couchbase Lite Database is created with specified name and DatabaseConfiguration object.

  database = new Database(DB_NAME, config);

Try it out

  • Build and Run the Travel Sample Mobile App

  • On the Login screen select the “Proceed as Guest” option.

  • This will log you into the app in Guest Mode. Signing in as Guest will create a new empty database for the “guest” account if one does not exist.

  • Confirm that you see the "Bookmarks" page. It will be empty the very first time.

Create and Update a Document

Bookmarked hotels are persisted in a separate document with a type of bookmarkedhotels.

The first time a hotel is bookmarked, the bookmarkedhotels document is created with the document ID of that hotel document in the hotels property. The hotel’s information is persisted in a separate hotels type document.

Subsequently, every time a hotel is bookmarked, the process repeats.

  "_id": "hotel1",
  "name": "San Francisco Hotel",
  "address": "123, Park Street, San Francisco"

  "type": "bookmarkedhotels",
  "hotels": ["hotel1", "hotel2"]

Open the file You will review the addBookmarksAsync method.

    private Void addBookmarksAsync(@Nonnull Set<Hotel> hotels) throws CouchbaseLiteException {

First, you need to get an instance of the database.

  final Database database = db.getDatabase();

The following snippet persists the hotel instance (Set<Hotel>) as a new Document in the database. This will allow us to access bookmarked hotel documents while being offline.

  final Set<String> ids = new HashSet<>();
  for (Hotel hotel : hotels) {
  final String id = hotel.getId();

  final Document hotelDoc = database.getDocument(id);
  if (hotelDoc == null) {; }

  bookmarkIds(database, ids);

Next you will get the document with ID user::guest or create one if it doesn’t exist.

This is implemented in the bookmarkIds private method.

private void bookmarkIds(@Nonnull Set<String> ids) throws CouchbaseLiteException {


The document is created with the type property set to bookmarkedhotels and a new hotels array to store the document IDs of the bookmarked hotels.

  final MutableDocument guestDoc = db.getGuestDoc();

  final Set<String> currentBookmarks = new HashSet<>();

  final MutableArray bookmarks = guestDoc.getArray(PROP_BOOKMARKS);
  if (bookmarks != null) {
      for (int i = 0; i < bookmarks.count(); i++) { currentBookmarks.add(bookmarks.getString(i)); }


Next, the selected hotel’s ID is added to the hotels array.

  final MutableArray newBookmarks = new MutableArray();
  for (String bookmark : currentBookmarks) { newBookmarks.addString(bookmark); }

  guestDoc.setArray(PROP_BOOKMARKS, newBookmarks);

Finally, you will save the document.


Try it out

  • As a Guest User, tap on the “ADD” button.

  • In "location" text field , enter "L" as if you were starting to type "London". You will see list of hotels.

  • The list of hotels is pulled from Couchbase Server via the Travel Sample Web Services API. When searching for hotels in Guest mode, the app sends a GET request to the Python Web App which performs a Full-Text Search query on Couchbase Server. Search results will not be displayed unless there is an open connection to the Python web app and the Full-Text Search index has been created in Couchbase Server.

  • Tap on the first hotel cell to bookmark it.

  • Click on "ADD" button

  • Click on "DONE" button

  • Verify that you see the bookmarked hotel in the "Bookmarks" screen.

    java save doc

Delete a Document

A document can be deleted using the delete method. This operation actually creates a new tombstoned revision in order to propagate the deletion to other clients.

Open the file You will review the removeBookmarksAsync method.

Void removeBookmarksAsync(@Nonnull Set<Hotel> hotels) throws CouchbaseLiteException {


When a hotel is bookmarked, it gets inserted in the Couchbase Lite database for offline access. So when the user unbookmarks a hotel, the document needs to be removed from the database. That’s what the code below is doing.

  final Database database = db.getDatabase();

  final Set<String> ids = new HashSet<>();
  for (Hotel hotel : hotels) { ids.add(hotel.getId()); }


  for (String id : ids) {
      final Document hotelDoc = database.getDocument(id);
      if (hotelDoc == null) {
          LOGGER.log(Level.WARNING, "Hotel not found in remove bookmark: " + id);

In addition to deleting the document of type "hotel" as shown above, the unbookmarking process removes the hotel ID from the hotels array in the "bookmarkedhotels" document.

Try it out

  • On BOOKMARKS page, select the first row to unbookmark

  • Click on "REMOVE" button

  • Verify that you do not see the hotel in the list

    java unbookmark