A newer version of this documentation is available.

View Latest

Developer’s Intro

Using Couchbase

Once you’ve installed the server, 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 CLI 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/default --mode insert josmith < josmith.json

josmith is the document’s ID, which is redirected (<) to the cbc command’s standard input. The default bucket — the database configured the first time you access the administration console — exists solely for development and testing. Remove it before you put Couchbase into production.

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.