Getting Started with NoSQL and Java

A look at the NoSQL database landscape, as well a walk-through of a simple Java example that interacts with a NoSQL database.

Jul 27th, 2022 7:07am by Jagadesh Munta

Featued image for: Getting Started with NoSQL and Java

Feature image via Pixabay.

For developers working with Java, connecting to the right database can provide significant benefits to their organization, while also making their jobs easier in the long term. This is especially true for databases that combine the flexibility and agility of NoSQL with the familiarity of SQL. In this article, I’ll briefly dive into the NoSQL database landscape, as well as walk you through the structure of a simple Java example that interacts with a NoSQL database.

The Current State of NoSQL Database Technologies

Jagadesh Munta

Jagadesh is a principal software engineer at Couchbase. He has more than 20 years of experience in the software development life cycle, QA, DevOps and architecture. Prior to joining Couchbase, Jagadesh held technical roles at Oracle and Sun Microsystems.

NoSQL databases store data as JSON documents rather than relational tables with columns and rows. Some NoSQL databases provide programming interfaces in both SQL and native document APIs. Types of NoSQL databases include document databases, key-value stores, wide-column databases and graph databases. NoSQL databases are known to store and process vast amounts of data efficiently and have become a foundational technology for many modern businesses. Many NoSQL databases are available in the cloud as a fully managed Database as a Service (DBaaS) or for on-premises installations. SDKs in various programming languages and APIs are used by developers to interact with such databases. Before we get into the code samples, it would be helpful to look at the sample data and how it’s organized within the database, often referred to as the data model.

Data Model

At the highest level of data organization, this database contains one or more buckets. Each bucket can contain one or more scopes, and each scope can contain one or more collections. Within collections are JSON documents. This hierarchy is similar to the relational database where databases have schemas, tables and rows, etc. This hierarchical data container model of this document database maps very well to the relational model: bucket = database, scope = schema, collection = table, document = row. This mapping allows you to access data either through the document data model in collections or the relational model using SQL. The sample in this example is called “Travel Sample,” a data set for an airline travel information system. The document (JSON) data model for the Travel Sample data set is shown below.

The major entities are airline, airport, route, linking airline and airport and hotel as a separate entity. The diagram below shows the relationship between the various documents in the Airline Travel system. It shows the primary key, ID and type fields that each document contains, with additional representative fields in each type of document.

Now we are ready to look at some basic data access operations on this sample dataset.

Code Examples

Now that the basic concepts are covered, let us see how to connect to the database, establish a context for a bucket and collection to work on, perform simple key-value operations and queries, and finally modify some data in the database.

Connect to the Database Cluster

A connection string typically consists of a host URL (IP name/addresses), followed by a username and password. Using this connection string, you can get a connection object to the database cluster. In this example, we are using localhost (127.0.0.1) as the database host. You may want to replace the DB name, username and password that are appropriate to your database cluster. A connection to the database cluster is represented by a cluster object.

class Program {
    public static void main(String[] args) {
    var cluster = Cluster.connect(
      "dbName", "username", "password"
    );

Set Context to the Appropriate Collection

Let us now establish a context for a very specific dataset: a bucket named “travel-sample” that already contains the Travel Sample data set collection. The code below sets our current context to the default collection within the “travel-sample.”

    var bucket = cluster.bucket("travel-sample");
    var collection = bucket.defaultCollection();

Basic Key-Value Operation (Get a Document)

The key value (KV) or data service offers the simplest way to retrieve or mutate data where the key is known. The get method below retrieves specific data (value) associated with a key. In this case, the key is “airline_10.”

     try {
        var result = collection.get("airline_10");
        System.out.println(result.toString());
          }
     catch (DocumentNotFoundException ex) {
      System.out.println("Document not found!");
    }
  }
}

Query Rows Using SQL

Here is a snippet of code performing a SQL query to retrieve hotel names in the city of Malibu from the Travel Sample data set.

try {
      var query = 
        "SELECT h.name, h.city, h.state " +
        "FROM `travel-sample` h " +
        "WHERE h.type = 'hotel' " +
          "AND h.city = 'Malibu' LIMIT 5;";

      QueryResult result = cluster.query(query);
      for (JsonObject row : result.rowsAsObject()) {
        System.out.println("Hotel: " + row);
      }
    } catch (DocumentNotFoundException ex) {
      System.out.println("Document not found!");
    }
  }
}

Query Using Named or Positional Parameters

Query methods can have named or positional parameters. Below is a named parameter example: The code proceeds to access the travel-sample database (specifically the name, city and state buckets). The queryOptions() method allows the customization of various SQL query options.

 try {
      var query = 
        "SELECT h.name, h.city, h.state " +
        "FROM `travel-sample` h " +
        "WHERE h.type = $type " +
          "AND h.city = $city LIMIT 5;";

      QueryResult result = cluster.query(query,
        queryOptions().parameters(
          JsonObject.create()
            .put("type", "hotel")
            .put("city", "Malibu")
        ));
          result.rowsAsObject().stream().forEach(
        e-> System.out.println(
          "Hotel: " + e.getString("name") + ", " + e.getString("city"))
      );
    } catch (CouchbaseException ex) {
      System.out.println("Exception: " + ex.toString());
    }
  }
}

Positional parameters allow the order of the method parameters to be replaced with placeholders.

    try {
      var query = 
        "SELECT h.name, h.city, h.state " +
        "FROM `travel-sample` h " +
        "WHERE h.type = $1 " +
          "AND h.city = $2 LIMIT 5;";
          
      QueryResult result = cluster.query(query,
        queryOptions().parameters(JsonArray.from("hotel", "Malibu"))      );
    result.rowsAsObject().stream().forEach(
        e-> System.out.println(
          "Hotel: " + e.getString("name") + ", " + e.getString("city"))
      );
  } catch (CouchbaseException ex) {
      System.out.println("Exception: " + ex.toString());
    }
  }
}

Using Subdocument Lookup Operations

Subdocuments are parts of the document that you can atomically and efficiently update and retrieve. In the code below, the lookupIn operation queries the “airport_1254” document for a certain path (here, it’s the geo.alt path). This code allows us to retrieve the document path using the `subdoc get` operation: (get("geo.alt")).

try {
      LookupInResult result = collection.lookupIn(
        "airport_1254",
        Collections.singletonList(get("geo.alt"))
      );

      var str = result.contentAs(0, String.class);
      System.out.println("Altitude = " + str);
     } catch (DocumentNotFoundException ex) {
      System.out.println("Document not found!");
    }
  }
}

Using Subdocument Mutate Operations

Mutation operations modify one or more paths in the document. In the code below, the mutateIn operation is used to modify the airline_10 by using a full doc-level upsert, which will create the value of an existing path with parameters (country, Canada).

   try {
      LookupInResult result = collection.lookupIn(
        "airline_10", Collections.singletonList(get("country"))
      );
      var str = result.contentAs(0, String.class);
      System.out.println("Sub-doc before: ");
      System.out.println(str);
      
    } catch (PathNotFoundException e) {
      System.out.println("Sub-doc path not found!");
    }
    try {
      collection.mutateIn("airline_10", Arrays.asList(
        upsert("country", "Canada")
      ));
    } catch (PathExistsException e) {
      System.out.println("Sub-doc path exists!");
    }
    try {
      LookupInResult result = collection.lookupIn(
        "airline_10", Collections.singletonList(get("country"))
      );
      var str = result.contentAs(0, String.class);
      System.out.println("Sub-doc after: ");
      System.out.println(str);
  } catch (PathNotFoundException e) {
      System.out.println("Sub-doc path not found!");
    }
    
  }
}

Using the Upsert Function

Upsert is used to insert a new record or update an existing one. If the document doesn’t exist, it will be created. Upsert is a combination of insert and update. The .put method allows the user to insert a mapping into a map. If an existing key is passed, the new value replaces the previous value.

    JsonObject content = JsonObject.create()
      .put("country", "Iceland")
      .put("callsign", "ICEAIR")
      .put("iata", "FI")
      .put("icao", "ICE")
      .put("id", 123)
      .put("name", "Icelandair")
      .put("type", "airline");

    collection.upsert("airline_123", content);
      
    try {
      LookupInResult lookupResult = collection.lookupIn(
        "airline_123", Collections.singletonList(get("name"))
      );

      var str = lookupResult.contentAs(0, String.class);
      System.out.println("New Document name = " + str);
    } catch (PathNotFoundException ex) {
      System.out.println("Document not found!");
    }
    
  }
}

The sample data set and code examples used above are from the distributed NoSQL cloud database Couchbase. Speaking of Databases as a Service, check out Couchbase Capella to see how modern enterprises are able to deliver flexibility across various use cases with built-in multimodel and mobile synchronization capabilities, and drive millisecond data response at scale. These and many more examples can be found and run from Couchbase Playground. To connect with other like-minded developers in the community for more inspiration, check out the Couchbase Forums. For those just getting started with Java, another great resource to consider is the free online Java developer certification course offered by Couchbase Academy.