A newer version of this documentation is available.

View Latest

Run Hello World!

You can run queries on Couchbase Server programmatically, as well as manually. A Software Development Kit (SDK) is provided in support of commonly used programming languages, to enable the execution of queries against Couchbase Server. This section provides a brief introduction to this area; and also features an off-the-shelf program that you can study and run.

Understand the Couchbase SDK

Couchbase provides a Software Development Kit (SDK), to make it easy to create applications that use Couchbase Server as a data-repository. The SDK comes in different versions, each of which supports a popular programming language. Supported languages are node.js, Java, .NET, PHP, Python, Go, and C.

Using the SDK, you make N1QL queries programmatically. For example, your application might provide a client-side UI, whereby the user selects one or more values: the application puts the values into a N1QL query-string, and passes this to a server-side program that is supported by the Couchbase SDK. The server-side program performs a N1QL query against Couchbase Server, and returns what it retrieves to your client-side.

This section provides a simple, off-the-shelf example, which works in the way just described. The example uses node.js: this may or may not be the SDK-version you choose to use in the long term; but it allows creation of a server-side program that is easy to read and run, and is therefore a good example with which to start.

Install node.js

To install node.js, use the appropriate installer for your platform; which is available from nodejs.org.

Install the Couchbase SDK for node.js

Bring up a command tool. Then, on all platforms, against the prompt, type the following:

$ npm install couchbase

Then, on non-Windows platforms, add node-gyp:

$ npm install node-gyp

Obtain the Hello World! Example

The program you are to run is located here. It consists of only two program files, and you can save them anywhere you want. There are also five supportive graphics files: these must be saved in the same directory as the html file.

The file nodeJSQueryAgent.js is the server-side program that runs queries on Couchbase Server. The file helloWorldCouchbaseQuery.html is the html client that you bring up in your browser.

We refer to this program as Hello World! simply because it fits an established tradition of introductory code examples. In fact, the words "Hello World" do not appear: instead, you see data retrieved from Couchbase Server’s travel-sample bucket.

Examine the Code

Before running the program, take a look at the principal elements within the code.


Bring up helloWorldCouchbaseQuery.html in a text editor. As you inspect the file, note that the user makes a selection on strings to be searched on, by means of radio-buttons:

if (selectedCountryValue == 0)
	selectedCountry = "United States";
	if (selectedCountryValue == 1)
		selectedCountryStyle = "United Kingdom";
		if (selectedCountryValue == 2)
			selectedCountryStyle = "France";

The selected value is made part of a query-string that returns all documents within the travel-sample bucket that provide a match:

var selectedQuery = 'SELECT * FROM `travel-sample` WHERE country = ' + '\"' + selectedCountryName + '\"';

The query-string is then itself appended to a URL, which features the hostname and port-number at which the node.js server-side program listens:

var nodeJsAddress = "http://localhost:8082/";

var nodeJsTargetURL = nodeJsAddress + '?' + "myQuery=" + selectedQuery;

A getJSON call passes the query-string to the server-side program, and receives a return-value that contains documents:

$.getJSON(nodeJsTargetURL, function(dataReturnedFromCouchbase)

Returned documents, up to a specified numeric maximum (configurable, but here 10), are added to a display-string, which is then shown in the dedicated pane:

for (var currentKeyPosition = 0; currentKeyPosition < 10; currentKeyPosition++)

	$.each(dataReturnedFromCouchbase[currentKeyPosition], function(key, val)

		$.each(val, function(newKey, newVal)
			cbDataDisplayString = cbDataDisplayString + \"<i>\" + JSON.stringify(newKey) + "</i>" + " : "
				+ "<b>" + JSON.stringify(newVal) + "</b>" + '</p>' + '<p>';

	cbDataDisplayString = cbDataDisplayString + '</br></br></br>';

document.getElementById('CouchbaseRetrievalsContent').innerHTML = cbDataDisplayString;


Now bring up nodeJsQueryAgent.js in your text editor. Note that the node.js require construct is used to ensure that the program has access to the right supportive modules. These include the one for Couchbase Server:

var http = require('http');
var url = require('url');
var couchbase = require("couchbase");

Variables are initialized for referencing the Couchbase Server-cluster and the travel-sample bucket:

var myCluster = new couchbase.Cluster('couchbase://localhost');
var myBucket = myCluster.openBucket('travel-sample');

The Couchbase SDK is now used to query Couchbase Server. A Primary Index is created, to allow a N1QL query to access the data that the cluster contains. Then, a N1QL query is made, specifying the query-string received from the html client. The values returned are passed back to the client, as a JSON string.

myBucket.get(theQueryString, function(err, res)
			function (err, rows)
				console.log("Got rows: %j", rows);

				response.writeHead(200, {"Content-Type": "application/json",
							"Access-Control-Allow-Origin": "*"});


Note: The node.js program is specified to listen on port 8082. If you should happen already to have a program listening on that port, change this number to specify a port that is free. You must change the number both here and in the client html file.

Run the Program

In a command tool, navigate to the folder that contains the file nodeJsQueryAgent.js. Then, type the following:

$ node nodeJsQueryAgent.js

This starts the node.js server. Now, bring up the file helloWorldCouchbaseQuery.html in a browser. The initial appearance is as follows:


Select a string to be queried on, by means of the radio buttons in the Airline Countries panel. Then, left-click on the Query Couchbase button. The query is executed, and the returned values are displayed in the Travel-Sample Retrievals panel:



The program you’ve just run, and the other activities provided throughout the Getting Started sequence, have given you an initial indication of the rich array of features offered by Couchbase Server. You can learn more about all aspects of the system from the Couchbase documentation-set: and in the final stage of this Getting Started sequence, Choose Your Next Steps suggestions are provided as to locations you can visit next.