Developer's Intro
Edit this article in GitHub
Version 2.3

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 mnunberg.json. It can be anywhere on your file system:

{
    "name": "Mark Nunberg",
    "email": "mark.nunberg@couchbase.com",
    "privs": ["admin"],
    "location": {
        "country": "United States",
        "state": "NV",
        "city": "Reno"
    },
    "following": [
        "u:tgreenstein", "u:ingenthr", "u:potus"
    ],
    "likes": ["doge", "pastries"]
}

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

$ cbc create --mode insert mnunberg < mnunberg.json
mnunberg 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 mnunberg
{
    "name": "Mark Nunberg",
    "email": "mark.nunberg@couchbase.com",
    "privs": ["admin"],
    "location": {
        "country": "United States",
        "state": "NV",
        "city": "Reno"
    },
    "following": [
        "u:tgreenstein", "u:ingenthr", "u:potus"
    ],
    "likes": ["doge", "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 criteria. 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:tgreenstein",
                "u:ingenthr",
                "u:potus"
            ],
            "likes": [
                "doge",
                "pastries"
            ]

Updating documents

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

    ...
    "likes": ["doge", "pastries", "couchbase"]
    ....
Then use the cbc tool to update the document in Couchbase:
$ cbc create --mode replace mnunberg < mnunberg.json

Deleting documents

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

$ cbc rm mnunberg

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.