Developer’s Intro

Using Couchbase

Once you’ve installed the server, and created a test bucket, you can start storing, retrieving, and querying documents with Couchbase. You can start with an SDK, the command-line cbc tool, or the web browser.

Every item in a database goes through the basic CRUD cycle, which is typical of an application’s use of data. CRUD stands for create, read, update, and delete:

  • Create: when data is first inserted into the cluster

  • Read: when an application retrieves the data

  • Update: when data is modified to reflect a change in the state represented by the data

  • Delete: when the data is no longer needed

The following examples use the java-sdk::common/webui-cli-access.adoc#cli-access interface to demonstrate the basic CRUD operations. If you don’t know how to use or install the command line client, don’t worry - we’ll walk through the steps in the next chapter.

Creating documents

Create the document josmith.json. It can be anywhere on your file system:

{
    "name": "Jo Smith",
    "email": "jo.smith@example.com",
    "privs": ["admin"],
    "location": {
        "country": "United States",
        "state": "NV",
        "city": "Reno"
    },
    "following": [
        "u:asmith", "u:bsmith", "u:potus"
    ],
    "likes": ["dogs", "pastries"]
}

Now, insert the document into Couchbase using the cbc utility:

$ cbc create -u username -P password -U couchbase://hostname-or-ip/myTestBucket --mode insert josmith < josmith.json

josmith is the document’s ID, which is redirected (<) to the cbc command’s standard input.

Reading documents by ID

Documents can be retrieved using their IDs. Retrieving a document by ID is extremely fast. The following query takes about 1 millisecond.

$ cbc cat -u username -P password -U couchbase://hostname-or-ip/josmith
{
    "name": "Jo Smith",
    "email": "jo.smith@example.com",
    "privs": ["admin"],
    "location": {
        "country": "United States",
        "state": "NV",
        "city": "Reno"
    },
    "following": [
        "u:asmith", "u:bsmith", "u:potus"
    ],
    "likes": ["dogs", "pastries"]
}

Reading documents by querying

Retrieving a document may be done using a unique identifier assigned by the application at the document’s creation, or by inspecting its contents to see if it matches a certain criterion. ID lookups are quicker, but querying documents allows for richer search capabilities (for example, "Give me all likes and followed users located in the US" versus "Give me a user with the ID e3d882a4").

$ cbc n1ql \
  'SELECT following, likes FROM default WHERE location.country = "United States"'
       {
            "following": [
                "u:asmith",
                "u:bsmith",
                "u:potus"
            ],
            "likes": [
                "dogs",
                "pastries"
            ]

Updating documents

Updating a document means changing the existing document. For example, take the file above and edit the likes field:

    ...
    "likes": ["dogs", "pastries", "couchbase"]
    ....

Then use the cbc tool to update the document in Couchbase:

$ cbc create --mode replace josmith < josmith.json

Deleting documents

This example shows how to delete the document with the ID josmith.

$ cbc rm josmith

Couchbase clients

Clients access data by connecting to a Couchbase cluster over the network. The most common type of client is a Couchbase SDK, which is a full programmatic API that enables applications to take the best advantage of Couchbase. The command line client provides a quick and streamlined interface for simple access and is suitable if you just want to access an item without writing any code.