REST API overview¶
A newer version of this software is available
You are viewing the documentation for an older version of this software. To find the documentation for the current version, visit the Couchbase documentation home page.
The Couchbase REST API enables you to manage a Couchbase Server deployment as well as perform operations such as storing design documents and querying for results. The REST API conforms to Representational State Transfer (REST) constraints, in other words, the REST API follows a RESTful architecture.
Use the REST API to manage clusters, server nodes, and buckets, and to retrieve run-time statistics within your Couchbase Server deployment. If you want to develop your own Couchbase-compatible SDK, you will also use the REST API within your library to handle views. Views enable you to index and query data based on functions that you define.
Tip
The REST API should not be used to read or write data to the server. Data operations, such as set and get for example, are handled by Couchbase SDKs. See the Couchbase SDKs.
In addition, the Couchbase Web Console uses many of the same REST API endpoints that are used for a REST API request. This is especially for administrative tasks such as creating a new bucket, adding a node to a cluster, or changing cluster settings.
Please provide RESTful requests; you will not receive any handling instructions, resource descriptions, nor should you presume any conventions for URI structure for resources represented. The URIs in the REST API may have a specific URI or may even appear as RPC or some other architectural style using HTTP operations and semantics.
In other words, build your request starting from Couchbase Cluster URIs, and be aware that URIs for resources may change from version to version. Also note that the hierarchies shown here enable your reuse of requests, since they follow a similar pattern for accessing different parts of the system.
The REST API is built on a number of basic principles:
-
JSON Responses
The Couchbase Management REST API returns many responses as JavaScript Object Notation (JSON). On that note, you may find it convenient to read responses in a JSON reader. Some responses may have an empty body, but indicate the response with standard HTTP codes. For more information, see RFC 4627 ( http://www.ietf.org/rfc/rfc4627.txt ) and www.json.org.
-
HTTP Basic Access Authentication
The Couchbase Management REST API uses HTTP basic authentication. The browser-based Using the Web Console and Command-line Interface also use HTTP basic authentication.
-
Versatile Server Nodes
All server nodes in a cluster share the same properties and can handle any requests made via the REST API.; you can make a REST API request on any node in a cluster you want to access. If the server node cannot service a request directly, due to lack of access to state or some other information, it will forward the request to the appropriate server node, retrieve the results, and send the results back to the client.
In order to use the REST API you should be aware of the different terms and concepts discussed in the following sections.
Types of resources¶
There are a number of different resources within the Couchbase Server and these resources will require a different URI/RESTful-endpoint in order to perform an operations:
Server nodes¶
A Couchbase Server instance, also known as ‘node’, is a physical or virtual machine running Couchbase Server. Each node is as a member of a cluster.
Cluster/Pool¶
A cluster is a group of one or more nodes; it is a collection of physical resources that are grouped together and provide services and a management interface. A single default cluster exists for every deployment of Couchbase Server. A node, or instance of Couchbase Server, is a member of a cluster. Couchbase Server collects run-time statistics for clusters, maintaining an overall pool-level data view of counters and periodic metrics of the overall system. The Couchbase Management REST API can be used to retrieve historic statistics for a cluster.
Buckets¶
A bucket is a logical grouping of data within a cluster. It provides a name space for all the related data in an application; therefore you can use the same key in two different buckets and they are treated as unique items by Couchbase Server.
Couchbase Server collects run-time statistics for buckets, maintaining an overall bucket-level data view of counters and periodic metrics of the overall system. Buckets are categorized by storage type: 1) memcached buckets are for in-memory, RAM-based information, and 2) Couchbase buckets, which are for persisted data.
Views¶
Views enable you to index and query data based on logic you specify. You can also use views to perform calculations and aggregations, such as statistics, for items in Couchbase Server. For more information, see Views and Indexes.
Cross datacenter replication (XDCR)¶
Cross Datacenter Replication (XDCR) is new functionality as of Couchbase Server 2.0. It enables you to automatically replicate data between clusters and between data buckets. There are two major benefits of using XDCR as part of your Couchbase Server implementation: 1) enables you to restore data from one Couchbase cluster to another cluster after system failure. 2) provide copies of data on clusters that are physically closer to your end users. For more information, see Cross Datacenter Replication (XDCR).
HTTP request headers¶
You will use the following HTTP request headers when you create your request:
| Header | Supported Values | Description of Use | Required |
|---|---|---|---|
| Accept | Comma-delimited list of media types or media type patterns. | Indicates to the server what media type(s) this client is prepared to accept. | Recommended |
| Authorization | Basic plus username and password (per RFC 2617). |
Identifies the authorized user making this request. | No, unless secured |
| Content-Length | Body Length (in bytes) | Describes the size of the message body. | Yes, on requests that contain a message body. |
| Content-Type | Content type | Describes the representation and syntax of the request message body. | Yes, on requests that contain a message body. |
| Host | Origin hostname | Required to allow support of multiple origin hosts at a single IP address. | All requests |
| X-YYYYY-Client-Specification-Version | String | Declares the specification version of the YYYYY API that this client was programmed against. | No |
HTTP status codes¶
The Couchbase Server will return one of the following HTTP status codes in response to your REST API request:
| HTTP Status | Description |
|---|---|
| 200 OK | Successful request and an HTTP response body returns. If this creates a new resource with a URI, the 200 status will also have a location header containing the canonical URI for the newly created resource. |
| 201 Created | Request to create a new resource is successful, but no HTTP response body returns. The URI for the newly created resource returns with the status code. |
| 202 Accepted | The request is accepted for processing, but processing is not complete. Per HTTP/1.1, the response, if any, SHOULD include an indication of the request’s current status, and either a pointer to a status monitor or some estimate of when the request will be fulfilled. |
| 204 No Content | The server fulfilled the request, but does not need to return a response body. |
| 400 Bad Request | The request could not be processed because it contains missing or invalid information, such as validation error on an input field, a missing required value, and so on. |
| 401 Unauthorized | The credentials provided with this request are missing or invalid. |
| 403 Forbidden | The server recognized the given credentials, but you do not possess proper access to perform this request. |
| 404 Not Found | URI you provided in a request does not exist. |
| 405 Method Not Allowed | The HTTP verb specified in the request (DELETE, GET, HEAD, POST, PUT) is not supported for this URI. |
| 406 Not Acceptable | The resource identified by this request cannot create a response corresponding to one of the media types in the Accept header of the request. |
| 409 Conflict | A create or update request could not be completed, because it would cause a conflict in the current state of the resources supported by the server. For example, an attempt to create a new resource with a unique identifier already assigned to some existing resource. |
| 500 Internal Server Error | The server encountered an unexpected condition which prevented it from fulfilling the request. |
| 501 Not Implemented | The server does not currently support the functionality required to fulfill the request. |
| 503 Service Unavailable | The server is currently unable to handle the request due to temporary overloading or maintenance of the server. |
Clusters REST API¶
One of the first ways to discover the URI endpoints for the REST API is to find the clusters available. For this you provide the Couchbase Server IP address, port number, and append ‘/pools’.
Example Request
curl -u admin:password http://localhost:8091/pools
Replace the admin, password, and localhost values in the above example with your actual values.
As a raw HTTP request:
GET /pools
Host: localhost:8091
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/json
X-memcachekv-Store-Client-Specification-Version: 0.1
The corresponding HTTP response contains a JSON document describing the cluster configuration:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: nnn
{"pools": [
{
"name":"default",
"uri":"/pools/default",
"streamingUri":"/poolsStreaming/default"
}
],
"isAdminCreds":false,
"uuid":"c25913df-59a2-4886-858c-7119d42e36ab",
"implementationVersion":"1.8.1-927-rel-enterprise",
"componentsVersion":
{
"ale":"8cffe61",
"os_mon":"2.2.6",
"mnesia":"4.4.19",
"inets":"5.6",
"kernel":"2.14.4",
"sasl":"2.1.9.4",
"ns_server":"1.8.1-927-rel-enterprise",
"stdlib":"1.17.4"}
}
Couchbase Server returns only one cluster per group of systems and the cluster will typically have a default name.
Couchbase Server returns the build number for the server in
implementation_version, the specifications supported are in the
componentsVersion. While this node can only be a member of one cluster, there
is flexibility which allows for any given node to be aware of other pools.
The Client-Specification-Version is optional in the request, but advised. It allows for implementations to adjust representation and state transitions to the client, if backward compatibility is desirable.
Viewing cluster details¶
At the highest level, the response for this request describes a cluster, as mentioned previously. The response contains a number of properties which define attributes of the cluster and controllers which enable you to make certain requests of the cluster.
Warning
Since buckets could be renamed and there is no way to determine the name for the default bucket for a cluster, the system attempts to connect non-SASL, non-proxied to a bucket named "default". If it does not exist, Couchbase Server drops the connection.
Do not rely on the node list returned by this request to connect to a Couchbase Server. Instead, issue an HTTP Get call to the bucket to get the node list for that specific bucket.
GET /pools/default
Host: localhost:8091
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/json
X-memcachekv-Store-Client-Specification-Version: 0.1
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: nnn
{
"name":"default",
"nodes":[{
"hostname":"10.0.1.20",
"status":"healthy",
"uptime":"14",
"version":"1.6.0",
"os":"i386-apple-darwin9.8.0",
"memoryTotal":3584844000.0,
"memoryFree":74972000,
"mcdMemoryReserved":64,
"mcdMemoryAllocated":48,
"ports":{
"proxy":11213,
"direct":11212
},
"otpNode":"ns_1@localhost",
"otpCookie":"fsekryjfoeygvgcd",
"clusterMembership":"active"
}],
"storageTotals":{
"ram":{
"total":2032558080,
"used":1641816064
},
"hdd":{
"total":239315349504.0,
"used": 229742735523.0
}
},
"buckets":{
"uri":"/pools/default/buckets"
},
"controllers":{
"ejectNode":{
"uri":"/pools/default/controller/ejectNode"
},
"addNode":{
"uri":"/controller/addNode"
},
"rebalance":{
"uri":"/controller/rebalance"
},
"failover":{
"uri":"/controller/failOver"
},
"reAddNode":{
"uri":"/controller/reAddNode"
},
"stopRebalance":{
"uri":"/controller/stopRebalance"
}
},
"rebalanceProgress":{
"uri":"/pools/default/rebalanceProgress"
},
"balanced": true,
"etag":"asdas123",
"initStatus":
"stats":{
"uri":"/pools/default/stats"
}
}
The controllers in this list all accept parameters as x-www-form-urlencoded,
and perform the following functions:
| Function | Description |
|---|---|
| ejectNode | Eject a node from the cluster. Required parameter: “otpNode”, the node to be ejected. |
| addNode | Add a node to this cluster. Required parameters: “hostname”, “user” and “password”. Username and password are for the Administrator for this node. |
| rebalance | Rebalance the existing cluster. This controller requires both “knownNodes” and “ejectedNodes”. This allows a client to state the existing known nodes and which nodes should be removed from the cluster in a single operation. To ensure no cluster state changes have occurred since a client last got a list of nodes, both the known nodes and the node to be ejected must be supplied. If the list does not match the set of nodes, the request will fail with an HTTP 400 indicating a mismatch. Note rebalance progress is available via the rebalanceProgress uri. |
| failover | Failover the vBuckets from a given node to the nodes which have replicas of data for those vBuckets. The “otpNode” parameter is required and specifies the node to be failed over. |
| reAddNode | The “otpNode” parameter is required and specifies the node to be re-added. |
| stopRebalance | Stop any rebalance operation currently running. This takes no parameters. |
Adding nodes to clusters¶
This is a REST request made to a Couchbase cluster to add a given node to the
cluster. You add a new node with the at the RESTful endpoint
server_ip:port/controller/addNode. Provide an administrative
username and password as parameters:
curl -u admin:password \
10.2.2.60:8091/controller/addNode \
-d "hostname=10.2.2.64&user=admin&password=password"
Here we create a request to the cluster at 10.2.2.60:8091 to add a given node by
using method, controller/addNode and by providing the IP address for the node
as well as credentials. Replace the admin, password, 10.2.2.60, and
10.2.2.64 values in the above example with your actual values.
If successful, Couchbase Server will respond:
HTTP/1.1 200 OK
{"otpNode":"ns_1@10.4.2.6"}
Joining nodes into clusters¶
This is a REST request made to an individual Couchbase node to add that node to a given cluster. You cannot merge two clusters together into a single cluster using the REST API, however, you can add a single node to an existing cluster. You will need to provide several parameters to add a node to a cluster:
curl -u admin:password -d clusterMemberHostIp=192.168.0.1 \
-d clusterMemberPort=8091 \
-d user=admin -d password=password
http://localhost:8091/node/controller/doJoinCluster
Replace the admin, password, and 192.168.0.1 values in the above example with your actual values.
The following arguments are required:
Argument | Description
——————–|———————————————————————————————–
clusterMemberHostIp | Hostname or IP address to a member of the cluster the node receiving this POST will be joining
clusterMemberPort | Port number for the RESTful interface to the system
If your cluster requires credentials, you will need to provide the following
parameters in your request:
| Argument | Description |
|---|---|
| user | Administration user |
| password | Password associated with the Administration user |
POST /node/controller/doJoinCluster
Host: localhost:8091
Authorization: Basic xxxxxxxxxxxx
Accept: */*
Content-Length: xxxxxxxxxx
Content-Type: application/x-www-form-urlencoded
clusterMemberHostIp=192.168.0.1&clusterMemberPort=8091&user=admin&password=admin123
200 OK with Location header pointing to pool details of pool just joined - successful join
400 Bad Request - missing parameters, etc.
401 Unauthorized - credentials required, but not supplied
403 Forbidden bad credentials - invalid credentials
Removing nodes from clusters¶
When a node is temporarily or permanently down, you may want to remove it from a cluster:
curl -u admin:password -d otpNode=ns_1@192.168.0.107 \
http://192.168.0.106:8091/controller/ejectNode
Replace the admin, password, 192.168.0.107, and 192.168.0.106 values in the above example with your actual values.
POST /controller/ejectNode
Host: localhost:8091
Authorization: Basic xxxxxxxxxxxx
Accept: */*
Content-Length: xxxxxxxxxx
Content-Type: application/x-www-form-urlencoded
otpNode=ns_1@192.168.0.1
200 OK - node ejected
400 Error, the node to be ejected does not exist
401 Unauthorized - Credentials were not supplied and are required
403 Forbidden - Credentials were supplied and are incorrect
Rebalancing nodes¶
To start a rebalance process through the REST API you must supply two arguments containing the list of nodes that have been marked to be ejected, and the list of nodes that are known within the cluster.
Initiating a rebalance¶
You can obtain the information about ejected and known node by getting the current node configuration from Managing Couchbase Nodes. This is to ensure that the client making the REST API request is aware of the current cluster configuration. Nodes should have been previously added or marked for removal as appropriate.
The information must be supplied via the ejectedNodes and knownNodes
parameters as a POST operation to the /controller/rebalance endpoint.
Example
curl -v -X -u admin:password POST 'http://192.168.0.77:8091/controller/rebalance' \
-d 'ejectedNodes=&knownNodes=ns_1%40192.168.0.77%2Cns_1%40192.168.0.56'
Replace the admin, password, 192.168.0.77, and 192.168.0.56 values in the above example with your actual values.
The corresponding raw HTTP request:
POST /controller/rebalance HTTP/1.1
Authorization: Basic QWRtaW5pc3RyYXRvcjpUYW1zaW4=
User-Agent: curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0 OpenSSL/0.9.8r zlib/1.2.5
Host: 192.168.0.77:8091
Accept: */*
Content-Length: 63
Content-Type: application/x-www-form-urlencoded
The response will be 200 (OK) if the operation was successfully submitted.
If the wrong node information has been submitted, JSON with the mismatch error will be returned:
{"mismatch":1}
Progress of the rebalance operation can be obtained by using Getting Rebalance Progress.
Getting Rebalance Progress¶
There are two endpoints for rebalance progress. One is a general request which
outputs high-level percentage completion at /pools/default/rebalanceProgress.
The second possible endpoint is one corresponds to the detailed rebalance report
available in Web Console, see Monitoring a
Rebalance for details
and definitions.
Example
This first request returns a JSON structure containing the current progress information:
curl -u admin:password '192.168.0.77:8091/pools/default/rebalanceProgress'
Replace the admin, password, localhost, and 192.168.0.77 values in the above example with your actual values.
As a pure REST API call, it appears as follows:
GET /pools/default/rebalanceProgress HTTP/1.1
Authorization: Basic QWRtaW5pc3RyYXRvcjpUYW1zaW4=
User-Agent: curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0 OpenSSL/0.9.8r zlib/1.2.5
Host: 192.168.0.77:8091
Accept: */*
The response data packet contains a JSON structure showing the rebalance progress for each node. The progress figure is provided as a percentage (shown as a floating point value between 0 and 1).
{
"status":"running",
"ns_1@192.168.0.56":{"progress":0.2734375},
"ns_1@192.168.0.77":{"progress":0.09114583333333337}
}
For more details about the rebalance, use the following request:
curl -u admin:password 'http://localhost:8091/pools/default/tasks'
Replace the admin, password, and localhost values in the above example with your actual values.
GET /pools/default/rebalanceProgress HTTP/1.1
Authorization: Basic QWRtaW5pc3RyYXRvcjpUYW1zaW4=
User-Agent: curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0 OpenSSL/0.9.8r zlib/1.2.5
Host: 192.168.0.77:8091
Accept: */*
The response data packet contains a JSON structure showing detailed progress:
{
type: "rebalance",
recommendedRefreshPeriod: 0.25,
status: "running",
progress: 9.049479166666668,
perNode: {
ns_1@10.3.3.61: {
progress: 13.4765625
},
ns_1@10.3.2.55: {
progress: 4.6223958333333375
}
},
detailedProgress: {
bucket: "default",
bucketNumber: 1,
bucketsCount: 1,
perNode: {
ns_1@10.3.3.61: {
ingoing: {
docsTotal: 0,
docsTransferred: 0,
activeVBucketsLeft: 0,
replicaVBucketsLeft: 0
},
outgoing: {
docsTotal: 512,
docsTransferred: 69,
activeVBucketsLeft: 443,
replicaVBucketsLeft: 511
}
},
ns_1@10.3.2.55: {
ingoing: {
docsTotal: 512,
docsTransferred: 69,
activeVBucketsLeft: 443,
replicaVBucketsLeft: 0
},
outgoing: {
docsTotal: 0,
docsTransferred: 0,
activeVBucketsLeft: 0,
replicaVBucketsLeft: 443
}
}
}
}
}
This shows percentage complete for each individual node undergoing rebalance. For each specific node, it provides the current number of docs transferred and other items. For details and definitions of these items, see Monitoring a Rebalance.
If you rebalance fails, you will see this response:
[
{
"type": "rebalance",
"status": "notRunning",
"errorMessage": "Rebalance failed. See logs for detailed reason. You can try rebalance again."
}
]
Adjusting Rebalance during Compaction¶
If you perform a rebalance while a node is undergoing index compaction, you may experience delays in rebalance. There is REST API parameter as of Couchbase Server 2.0.1 you can use to improve rebalance performance. If you do make this selection, you will reduce the performance of index compaction which can result in larger index file size.
Example
To make this request:
curl -X POST -u admin:password 'http://localhost:8091/internalSettings'
-d 'rebalanceMovesBeforeCompaction=256'
Replace the admin, password, localhost, and 256 values in the above example with your actual values.
This needs to be made as POST request to the /internalSettings endpoint. By
default this setting is 16, which specifies the number of vBuckets which will
moved per node until all vBucket movements pauses. After this pause the system
triggers index compaction. Index compaction will not be performed while vBuckets
are being moved, so if you specify a larger value, it means that the server will
spend less time compacting the index, which will result in larger index files
that take up more disk space.
Managing auto-failover¶
This section provides information about retrieving, enabling, disabling and resetting auto-failover.
Retrieving auto-failover settings¶
Use this request to retrieve any auto-failover settings for a cluster. Auto-failover is a global setting for all clusters. You need to be authenticated to read this value. Example:
curl -u admin:password http://localhost:8091/settings/autoFailover
Replace the admin, password, and localhost values in the above example with your actual values.
If successful Couchbase Server returns any auto-failover settings for the cluster:
{"enabled":false,"timeout":30,"count":0}
The following parameters and settings appear:
enabled: either true if auto-failover is enabled or false if it is not.timeout: seconds that must elapse before auto-failover executes on a cluster.count: can be 0 or 1. After one auto-failover occurs, count is set to 1 and Couchbase server will not perform auto-failure for the cluster again unless you reset the count to 0. If you want to failover more than one node at a time in a cluster, you will need to do so manually.count: Value is 0 or 1. After one auto-failover occurs, count is set to 1 and Couchbase Server will not perform another auto-failover for the cluster unless the count is reset to 0. If you want to failover more than one node at a time in a cluster, you have to do it manually.count: Value is 0 or 1. It shows whether any node in a cluster can be automatically failed-over. After one auto-failover occurs, the count is set to 1 and Couchbase Server does not perform another auto-failover for the cluster unless the count is reset to 0. To failover more than one node at a time in a cluster, perform a manual failover.
Possible errors include:
HTTP/1.1 401 Unauthorized
This endpoint isn't available yet.
GET /settings/autoFailover HTTP/1.1
Host: localhost:8091
Authorization: Basic YWRtaW46YWRtaW4=
Accept: */*
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: nnn
{ "enabled": false, "timeout": 30, "count": 0 }
Enabling and disabling auto-failover¶
This is a global setting you apply to all clusters. You need to be authenticated to change this value. An example of this request:
curl "http://localhost:8091/settings/autoFailover" \
-i -u admin:password -d 'enabled=true&timeout=600'
Replace the admin, password, localhost, and 600 values in the above example with your actual values.
Possible parameters are:
enabled(true|false) (required): Indicates whether Couchbase Server will perform auto-failover for the cluster or not.timeout(integer that is greater than or equal to 30) (required; optional when enabled=false): The number of seconds a node must be down before Couchbase Server performs auto-failover on the node.
POST /settings/autoFailover HTTP/1.1
Host: localhost:8091
Content-Type: application/x-www-form-urlencoded
Authorization: Basic YWRtaW46YWRtaW4=
Content-Length: 14
enabled=true&timeout=60
HTTP/1.1 200 OK
The possible errors include:
400 Bad Request, The value of "enabled" must be true or false.
400 Bad Request, The value of "timeout" must be a positive integer bigger or equal to 30.
401 Unauthorized
This endpoint isn't available yet.
Resetting auto-failover¶
This resets the number of nodes that Couchbase Server has automatically failed-over. You can send a request to set the auto-failover number to 0. This is a global setting for all clusters. You need to be authenticated to change this value. No parameters are required:
curl -X POST -i -u admin:password \
http://localhost:8091/settings/autoFailover/resetCount
Replace the admin, password, and localhost values in the above example with your actual values.
POST /settings/autoFailover/resetCount HTTP/1.1
Host: localhost:8091
Content-Type: application/x-www-form-urlencoded
Authorization: Basic YWRtaW46YWRtaW4=
HTTP/1.1 200 OK
Possible errors include:
This endpoint isn't available yet.
401 Unauthorized
Setting maximum buckets for clusters¶
By default the maximum number of buckets recommended for a Couchbase Cluster is ten. This is a safety mechanism to ensure that a cluster does not have resource and CPU overuse due to too many buckets. This limit is configurable using the REST API.
The Couchbase REST API has changed to enable you to change the default maximum number of buckets used in a Couchbase cluster. The maximum allowed buckets in this request is 128, however the suggested maximum number of buckets is ten per cluster. The following illustrates the endpoint and parameters used:
curl -X POST -u admin:password -d maxBucketCount=6 http://localhost:8091/internalSettings
Replace the admin, password, localhost, and 6 values in the above example with your actual values.
For this request you need to provide administrative credentials for the cluster. The following HTTP request will be sent:
About to connect() to 127.0.0.1 port 8091 (#0)
Trying 127.0.0.1...
connected
Connected to 127.0.0.1 (127.0.0.1) port 8091 (#0)
Server auth using Basic with user 'Administrator'
POST /internalSettings HTTP/1.1
If Couchbase Server successfully changes the bucket limit for the cluster, you will get a HTTP 200 response:
HTTP/1.1 200 OK
Server: Couchbase Server 2.0.0r_501_gb614829
Pragma: no-cache
Date: Wed, 31 Oct 2012 21:21:48 GMT
Content-Type: application/json
Content-Length: 2
Cache-Control: no-cache
If you provide an invalid number, such as 0, a negative number, or an amount over 128 buckets, you will get this error message:
["Unexpected server error, request logged."]
Setting maximum parallel indexers¶
You can set the number of parallel indexers that will be used on each node when
view indexes are updated. To get the current setting of the number of parallel
indexers, use a GET request.
| Get Maximum Parallel Indexers | Description |
|---|---|
| Method | GET /settings/maxParallelIndexers
|
| Request Data | None |
| Response Data | JSON of the global and node-specific parallel indexer configuration |
| Authentication Required | no |
For example:
GET http://127.0.0.1:8091/settings/maxParallelIndexers
This returns a JSON structure of the current settings, providing both the globally configured value, and individual node configuration:
{
"globalValue" : 4,
"nodes" : {
"ns_1@127.0.0.1" : 4
}
}
To set the value, POST to the URL specifying a URL-encoded value to the
globalValue argument.
| Set Maximum Parallel Indexers | Description |
|---|---|
| Method | POST /settings/maxParallelIndexers
|
| Request Data | None |
| Response Data | JSON of the global and node-specific parallel indexer configuration |
| Authentication Required | yes |
| Payload Arguments | |
globalValue |
Required parameter. Numeric. Sets the global number of parallel indexers. Minimum of 1, maximum 1024. |
| Return Codes | |
| 400 | globalValue not specified or invalid |
View settings for email notifications¶
The response to this request will specify whether you have email alerts set, and which events will trigger emails. This is a global setting for all clusters. You need to be authenticated to read this value:
curl -u admin:password http://localhost:8091/settings/alerts
Replace the admin, password, and localhost values in the above example with your actual values.
GET /settings/alerts HTTP/1.1
Host: localhost:8091
Authorization: Basic YWRtaW46YWRtaW4= Accept: */*
{
"recipients": ["root@localhost"],
"sender":"couchbase@localhost",
"enabled":true,
"emailServer":{"user":"","pass":"","host":"localhost","port":25,"encrypt":false},
"alerts":
["auto_failover_node",
"auto_failover_maximum_reached",
"auto_failover_other_nodes_down",
"auto_failover_cluster_too_small"]
}
Possible errors include:
This endpoint isn't available yet.
Enabling and disabling email notifications¶
This is a global setting for all clusters. You need to be authenticated to change this value. If this is enabled, Couchbase Server sends an email when certain events occur. Only events related to auto-failover trigger notification:
curl -i -u admin:password \
-d 'enabled=true&sender=couchbase@localhost&recipients=admin@localhost,membi@localhost&emailHost=localhost&emailPort=25&emailEncrypt=false' http://localhost:8091/settings/alerts
Replace the admin, password, localhost, couchbase@localhost, admin@localhost, membi@localhost, 25, and false values in the above example with your actual values.
Possible parameters include:
enabled: (true|false) (required). Whether to enable or disable email notificationssender(string) (optional, default: couchbase@localhost). Email address of the sender.recipients(string) (required). A comma separated list of recipients of the of the emails.emailHost(string) (optional, default: localhost). Host address of the SMTP serveremailPort(integer) (optional, default: 25). Port of the SMTP serveremailEncrypt(true|false) (optional, default: false). Whether you want to use TLS or notemailUser(string) (optional, default: “”): Username for the SMTP serveremailPass(string) (optional, default: “”): Password for the SMTP serveralerts(string) (optional, default: auto_failover_node, auto_failover_maximum_reached, auto_failover_other_nodes_down, auto_failover_cluster_too_small). Comma separated list of alerts that should cause an email to be sent. Possible values are: auto_failover_node, auto_failover_maximum_reached, auto_failover_other_nodes_down, auto_failover_cluster_too_small.
POST /settings/alerts HTTP/1.1
Host: localhost:8091
Content-Type: application/x-www-form-urlencoded
Authorization: Basic YWRtaW46YWRtaW4=
Content-Length: 14 enabled=true&sender=couchbase@localhost&recipients=admin@localhost,membi@localhost&emailHost=localhost&emailPort=25&emailEncrypt=false�
HTTP/1.1 200 OK
Possible HTTP errors include:
400 Bad Request
401 Unauthorized
JSON object ({"errors": {"key": "error"}}) with errors.
Possible errors returned in a JSON document include:
alerts: alerts contained invalid keys. Valid keys are: [list_of_keys].
email_encrypt: emailEncrypt must be either true or false.
email_port: emailPort must be a positive integer less than 65536.
enabled: enabled must be either true or false.
recipients: recipients must be a comma separated list of valid email addresses.
sender: sender must be a valid email address.
general: No valid parameters given.
Sending test emails¶
This is a global setting for all clusters. You need to be authenticated to change this value. In response to this request, Couchbase Server sends a test email with the current configurations. This request uses the same parameters used in setting alerts and additionally an email subject and body.
curl -i -u admin:password http://localhost:8091/settings/alerts/testEmail \
-d 'subject=Test+email+from+Couchbase& \
body=This+email+was+sent+to+you+to+test+the+email+alert+email+server+settings.&enabled=true& \
recipients=vmx%40localhost&sender=couchbase%40localhost& \
emailUser=&emailPass=&emailHost=localhost&emailPort=25&emailEncrypt=false& \
alerts=auto_failover_node%2Cauto_failover_maximum_reached%2Cauto_failover_other_nodes_down%2Cauto_failover_cluster_too_small'
Replace the admin, password, localhost, vmx%40localhost, couchbase%40localhost, 25, and false values in the above example with your actual values.
POST /settings/alerts/sendTestEmail HTTP/1.1
Host: localhost:8091
Content-Type: application/x-www-form-urlencoded
Authorization: Basic YWRtaW46YWRtaW4=
200 OK
Possible errors include:
400 Bad Request: Unknown macro: {"error"} 401 Unauthorized
This endpoint isn't available yet.
Managing internal cluster settings¶
You can set a number of internal settings the number of maximum number of
supported buckets supported by the cluster. To get the current setting of the
number of parallel indexers, use a GET request.
| Get Internal Settings | Description |
|---|---|
| Method | GET /internalSettings
|
| Request Data | None |
| Response Data | JSON of current internal settings |
| Authentication Required | no |
| Return Codes | |
| 200 | Settings returned |
For example:
GET http://127.0.0.1:8091/internalSettings
This returns a JSON structure of the current settings:
{
"indexAwareRebalanceDisabled":false,
"rebalanceIndexWaitingDisabled":false,
"rebalanceIndexPausingDisabled":false,
"maxParallelIndexers":4,
"maxParallelReplicaIndexers":2,
"maxBucketCount":20
}
To set a configuration value, POST to the URL a payload containing the updated
values.
| Set Configuration Value | Description |
|---|---|
| Method | POST /settings/maxParallelIndexers
|
| Request Data | None |
| Response Data | JSON of the global and node-specific parallel indexer configuration |
| Authentication Required | yes |
| Payload Arguments | |
globalValue |
Required parameter. Numeric. Sets the global number of parallel indexers. Minimum of 1, maximum 1024. |
| Return Codes | |
| 400 | globalValue not specified or invalid |
For example, to update the maximum number of buckets:
curl -v -X POST http://admin:password@localhost:8091/internalSettings \
-d maxBucketCount=20
Replace the admin, password, localhost, and 20 values in the above example with your actual values.
Disabling consistent query results on rebalance¶
If you perform queries during rebalance, this new feature will ensure that you receive the query results that you would expect from a node as if it is not being rebalanced. During node rebalance, you will get the same results you would get as if the data were on an original node and as if data were not being moved from one node to another. In other words, this new feature ensures you get query results from a new node during rebalance that are consistent with the query results you would have received from the node before rebalance started.
By default this functionality is enabled; although it is possible to disable this functionality via the REST API, under certain circumstances described below.
Note
Be aware that rebalance may take significantly more time if you have implemented views for indexing and querying. While this functionality is enabled by default, if rebalance time becomes a critical factor for your application, you can disable this feature via the REST API.
We do not recommend you disable this functionality for applications in production without thorough testing. To do so may lead to unpredictable query results during rebalance.
To disable this feature, provide a request similar to the following:
curl -v -u admin:password -X POST http://localhost:8091/internalSettings \
-d indexAwareRebalanceDisabled=true
Replace the admin, password, and localhost values in the above example with your actual values.
If successful Couchbase Server will send a response:
HTTP/1.1 200 OK
Content-Type: application/json
For more information about views and how they function within a cluster, see View Operation.
Server nodes REST API¶
A Couchbase Server instance, also known as ‘node’, is a physical or virtual machine running Couchbase Server. Each node is as a member of a cluster.
To view information about nodes that exist in a Couchbase Cluster, you use this request:
curl -u admin:password http://localhost:8091/pools/nodes
Replace admin, password, and localhost values in the above example with your actual values.
Couchbase server returns this response in JSON:
{"storageTotals":
{
"ram":
{
"quotaUsed":10246684672.0,
"usedByData":68584936,
"total":12396216320.0,
"quotaTotal":10246684672.0,
"used":4347842560.0},
"hdd":
{"usedByData":2560504,
"total":112654917632.0,
"quotaTotal":112654917632.0,
"used":10138942586.0,
"free":102515975046.0}
},
"name":"nodes",
"alerts":[],
"alertsSilenceURL":"/controller/resetAlerts?token=0",
"nodes":
[{"systemStats":
{
"cpu_utilization_rate":2.5,
"swap_total":6140452864.0,
"swap_used":0
},
"interestingStats":
{
"curr_items":0,
"curr_items_tot":0,
"vb_replica_curr_items":0
},
"uptime":"5782",
"memoryTotal":6198108160.0,
"memoryFree":3777110016.0,
"mcdMemoryReserved":4728,
"mcdMemoryAllocated":4728,
"clusterMembership":"active",
"status":"healthy",
"hostname":"10.4.2.5:8091",
"clusterCompatibility":1,
"version":"1.8.1-937-rel-community",
"os":"x86_64-unknown-linux-gnu",
"ports":
{
"proxy":11211,
"direct":11210
}
.......
}],
"buckets":
{"uri":"/pools/nodes/buckets?v=80502896" },
"controllers":{"addNode":{"uri":"/controller/addNode"},
"rebalance":{"uri":"/controller/rebalance"},
"failOver":{"uri":"/controller/failOver"},
"reAddNode":{"uri":"/controller/reAddNode"},
"ejectNode":{"uri":"/controller/ejectNode"},
"testWorkload":{"uri":"/pools/nodes/controller/testWorkload"}},
"balanced":true,
"failoverWarnings":["failoverNeeded","softNodesNeeded"],
"rebalanceStatus":"none",
"rebalanceProgressUri":"/pools/nodes/rebalanceProgress",
"stopRebalanceUri":"/controller/stopRebalance",
"nodeStatusesUri":"/nodeStatuses",
"stats":{"uri":"/pools/nodes/stats"},
"counters":{"rebalance_success":1,"rebalance_start":1},
"stopRebalanceIsSafe":true}
Retrieving statistics¶
To retrieve statistics about a node, you can first retrieve a list of nodes in a cluster with this request:
curl -u admin:password http://localhost:8091/pools/default/buckets/default/nodes
Replace the admin, password, and values in the above example with your actual values.
You can send this request using the IP address and port for any node in the cluster. This sends the following HTTP request:
GET /pools/default/buckets/default/nodes HTTP/1.1
User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8r zlib/1.2.5
Host: 10.4.2.4:8091
Accept: */*
If Couchbase Server successfully handles the request, you will get a response similar to the following example:
{"servers":[
{"hostname":"10.4.2.6:8091",
"uri":"/pools/default/buckets/default/nodes/10.4.2.6%3A8091",
"stats":
{"uri":"/pools/default/buckets/default/nodes/10.4.2.6%3A8091/stats"}}
....
You can then make a REST request to the specific IP address and port of given
node shown in the response and add /stats as the endpoint:
curl -u admin:password http://10.4.2.4:8091/pools/default/buckets/default/nodes/10.4.2.4%3A8091/stats
Replace the admin, password, and 10.4.2.4 values in the above example with your actual values.
This sends the following HTTP request:
GET /pools/default/buckets/default/nodes/10.4.2.4%3A8091/stats HTTP/1.1
User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8r zlib/1.2.5
Host: 10.4.2.4:8091
Accept: */*
If Couchbase Server successfully handles the request, you will get a response similar to the following example:
{"hostname":"10.4.2.4:8091","hot_keys":[{"name":"[2012-11-05::3:47:01]"
....
"samplesCount":60,"isPersistent":true,"lastTStamp":1352922180718,"interval":1000}}
The statistics returned will be for the individual bucket associated with that node.
Provisioning nodes¶
Creating a new cluster or adding a node to a cluster is called provisioning.
You need to:
Create a new node by installing a new Couchbase Server.
Configure disk path for the node.
Optionally configure memory quota for each node within the cluster. Any nodes you add to a cluster will inherit the configured memory quota. The default memory quota for the first node in a cluster is 60% of the physical RAM.
Add the node to your existing cluster.
Whether you are adding a node to an existing cluster or starting a new cluster, the node’s disk path must be configured. Your next steps depends on whether you create a new cluster or you want to add a node to an existing cluster. If you create a new cluster you will need to secure it by providing an administrative username and password. If you add a node to an existing cluster you will need the URI and credentials to use the REST API with that cluster.
Configuring index paths¶
The path for the index files can be configured through the use of the
index_path parameter:
Example as follows:
curl -X POST -u admin:password \
-d index_path=/var/tmp/text-index \
http://localhost:8091/nodes/self/controller/settings
Replace the admin, password, localhost, and /var/tmp/text-index values in the above example with your actual values.
As a raw HTTP request:
POST /nodes/self/controller/settings HTTP/1.1
Host: localhost:8091
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Authorization: Basic YWRtaW46YWRtaW4=
Content-Length: xx path=/var/tmp/test
The HTTP response will contain the response code and optional error message:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 0
As of Couchbase Server 2.0.1 if you try to set the data path at this endpoint, you will receive this error:
ERROR: unable to init 10.3.4.23 (400) Bad Request
{u'error': u'Changing data of nodes that are part of provisioned cluster is not supported'}
Setting usernames and passwords¶
While this can be done at any time for a cluster, it is typically the last step you complete when you add node into being a new cluster. The response will indicate the new base URI if the parameters are valid. Clients will want to send a new request for cluster information based on this response.
For example, using curl :
curl -u admin:password -d username=Administrator \
-d password=letmein \
-d port=8091 \
http://localhost:8091/settings/web
Replace the admin, password, localhost, letmein, and Administrator values in the above example with your actual values.
The raw HTTP request:
POST /settings/web HTTP/1.1
Host: localhost:8091
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Authorization: Basic YWRtaW46YWRtaW4=
Content-Length: xx
username=Administrator&password=letmein&port=8091
The corresponding HTTP response data:
HTTP/1.1 200 OK
Content-Type: application/json
Server: Couchbase Server 2.0
Pragma: no-cache
Date: Mon, 09 Aug 2010 18:50:00 GMT
Content-Type: application/json
Content-Length: 39
Cache-Control: no-cache no-store max-age=0
{"newBaseUri":"http://localhost:8091/"}
Note
The port number must be specified when username/password is updated.
Configuring node memory quota¶
The node memory quota configures how much RAM to be allocated to Couchbase for every node within the cluster.
| Set Memory | Description |
|---|---|
| Method | POST /pools/default
|
| Request Data | Payload with memory quota setting |
| Response Data | Empty |
| Authentication Required | yes |
| Return Codes | |
| 200 | OK |
| 400 | Bad Request JSON: The RAM Quota value is too small. |
| 401 | Unauthorized |
For example, to set the memory quota for a cluster at 400MB:
curl -X POST -u admin:password -d memoryQuota=400 http://localhost:8091/pools/default
Replace the admin, password, localhost, and 400 values in the above example with your actual values.
As a raw HTTP request:
POST /pools/default HTTP/1.1
Host: localhost:8091
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Authorization: Basic YWRtaW46YWRtaW4=
Content-Length: xx
memoryQuota=400
The HTTP response will contain the response code and optional error message:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 0
Providing hostnames¶
There are several ways you can provide hostnames for Couchbase. You can
provide a hostname when you install a Couchbase Server node, when you add it
to an existing cluster for online upgrade, or via a REST API call. If a node
restarts, any hostname you establish will be used. You cannot provide a hostname
for a node that is already part of a Couchbase cluster; the server will reject
the request and return error 400 reason: unknown ["Renaming is disallowed for
nodes that are already part of a cluster"].
To see the specific REST request, see Using hostnames.
Requesting node failover¶
You can use this request to failover a node in the cluster. When you failover a node, it indicates the node is no longer available in a cluster and replicated data at another node should be available to clients. You can also choose to perform node failover using the Web Console.
Using the REST API endpoint host:port/controller/failOver, provide your
administrative credentials and the parameter optNode which is an internal name
for the node:
curl -v -X POST -u admin:password http://localhost:8091/controller/failOver -d otpNode=ns_2@10.3.3.63
Replace the admin, password, localhost, and 10.3.3.63, values in the above example with your actual values.
The HTTP request will be similar to the following:
POST /controller/failOver HTTP/1.1
Authorization: Basic
Upon success, Couchbase Server will send a response as follows:
HTTP/1.1 200 OK
If you try to failover a node that does not exist in the cluster, you will get a
HTTP 404 error. To learn more about how to retrieve optNode information for
the nodes in a cluster, see Managing Clusters.
Rack Awareness REST API¶
The Rack Awareness feature allows logical groupings of servers on a cluster where each server group physically belongs to a rack or availability zone. This feature provides the ability to specify that active and corresponding replica partitions be created on servers that are part of a separate rack or zone. For purposes of the server group REST API, racks or availability zones are represented as flat space of server groups with group names. To enable Rack Awareness, all servers in a cluster must be upgraded to use the Rack Awareness feature.
Note
The Rack Awareness feature with its server group capability is an Enterprise Edition feature.
The Server groups REST API provides the following capability:
- Creates server groups
- Edits server groups
- Deletes server groups
- Assigns servers to server groups.
HTTP Methods¶
The following summarizes the HTTP methods used for managing server groups.
| HTTP method | URI path | Description |
|---|---|---|
| GET | /pools/default/serverGroups | Retrieves information about a server group. |
| POST | /pools/default/serverGroups | Creates a server group with a specific name. |
| PUT | /pools/default/serverGroups/<:uuid> | Updates the server group information. |
| PUT | /pools/default/serverGroups?rev=<:number> | Updates a server’s group memberships. |
| DELETE | /pools/default/serverGroups/<:uuid> | Deletes a specific server group. |
Retrieving server group information¶
GET /pools/default/serverGroups retrieves information about server groups. Provides group information, "groups": [(<groupInfo>)+],
where each server group has unique URIs and UUIDs.
Syntax
curl -X GET -u <administrator>:<password>
http://<host>:<port>/pools/default/serverGroups
Example
curl -X GET -u Admin:myPassword
http://192.168.0.1:8091/pools/default/serverGroups
Returns
{"groups":
[
{
"name":"<groupName>",
"uri": "/pools/default/serverGroups?rev=<integer>",
"addNodeURI":"/pools/default/serverGroups/0",
"nodes":[(<nodeInfo>)+]
}
]
}
| Group info | Description |
|---|---|
"groups": [(<groupInfo>)+] |
Information about server groups. |
"name":"<groupName>" |
Specifies the name of the group. If the group name has a space, for example, Group A, use double quotes (for example, "Group A"). If the name does not have spaces (for example, GroupA) double quotes are not required. |
"uri":"/pools/default/serverGroups?rev=<integer>" |
Specifies the URI path and revision integer. |
"uri":"/pools/default/serverGroups/<:uuid>" |
Specifies the URI path and UUID string. |
"addNodeURI":"/pools/default/serverGroups/<:uuid>/addNode |
Specifies the URI path and UUID string for adding servers to a server group. |
"nodes": [(<nodeInfo>+)] |
Information about the servers. |
Creating server groups¶
POST /pools/default/serverGroups creates a server group with a specific name. In the following example, Group A is created. If the group name has a space, for example, Group A, use double quotes; for example, "Group A".
Syntax
curl -X POST -u <administrator>:<password>
http://<host>:<port>/pools/default/serverGroups
-d name="<groupName>"
Example
curl -X POST -u Admin:myPassword
http://192.168.0.1:8091/pools/default/serverGroups
-d name="Group A"
Renaming server groups¶
PUT /pools/default/serverGroups/<:uuid> renames the server group. Find the UUID for the server group by using GET, add the UUID to the URI path, and specify a new group name. In this example, Group A is renamed to Group B. The UUID for the server group is located in the full URI information for that server group. The UUID remains the same for the server group after changing the name.
For example, the UUID for Group A is located in the following group information:
"name":"Group A",
"uri":"/pools/default/serverGroups/246b5de857e100dbfd8b6dee0406420a"
Syntax
curl -X PUT -u <administrator>:<password>
http://<host>:<port>/pools/default/serverGroups/<uuid>
-d name="<newGroupName>"
Example
curl -X PUT -u Admin:myPassword
http://192.168.0.1:8091/pools/default/serverGroups/246b5de857e100dbfd8b6dee0406420a
-d name="Group B"
Deleting server groups¶
DELETE /pools/default/serverGroups/<:uuid> deletes a specific server group. The server group must be empty for a successful request. In the following example, the UUID is the same UUID used in the renaming example.
Syntax
curl -X DELETE -u <administrator>:<password>
http://<host>:<port>/pools/default/serverGroups/<uuid>
Example
curl -X DELETE -u Admin:myPassword
http://192.168.0.1:8091/pools/default/serverGroups/246b5de857e100dbfd8b6dee0406420a
Adding servers to server groups¶
POST /pools/default/serverGroups/<:uuid>/addNode adds a server to a cluster and assigns it to the specified server group.
Syntax
curl -X POST -dhostname=<host>:<port>
-u <administrator>:<password>
http://<host>:<port>/pools/default/serverGroups/<uuid>/addNode
Example
curl -X POST -dhostname=192.168.0.2:8091
-u Admin:myPassword
http://192.168.0.1:8091/pools/default/serverGroups/246b5de857e100dbfd8b6dee0406420a/addNode
The server group’s UUID is in the group information
"name":"Group 2",
"uri":"/pools/default/serverGroups/d55339548767ceb51b241c61e3b9f036",
"addNodeURI":"/pools/default/serverGroups/d55339548767ceb51b241c61e3b9f036/addNode",
Updating server group memberships¶
PUT /pools/default/serverGroups?rev=<:number> updates the server’s group memberships.
In the following examples, the group name is optional. If the group name is provided,
it must match the current group name.
All servers must be mentioned and all groups must be mentioned.
The URI is used to identify the group.
This request only allows moving servers between server groups. It does not allow server group renaming or removal. In this example, the servers for Group 2 are moved to Group 1.
The following is the group information that is needed to update the server and server group memberships:
{
"groups": [( { ("name": <groupName:string>,)?
"uri": "/pools/default/serverGroups/"<uuid>,
"nodes": [(<otpNode>)*]
}
Syntax
curl -d @<inputFile> -X PUT
-u <administrator>:<password>
http://<host>:<port>/pools/default/serverGroups?rev=<number>
Example
In this example, a JSON file is used.
curl -d@file.json -X PUT
http://Administrator:asdasd@192.168.0.1:8091/pools/default/serverGroups?rev=120137811
Example
In this example, the JSON data is provided on the command line.
curl -v -X PUT
-u Administrator:password
http://192.168.171.144:8091/pools/default/serverGroups?rev=28418649
-d '{"groups":
[{"nodes": [{"otpNode": "ns_1@192.168.171.144"},
{"otpNode": "ns_1@192.168.171.145"}],
"name": "Group 1",
"uri": "/pools/default/serverGroups/0"},
{"nodes": [],
"name": "Group 2",
"uri": "/pools/default/serverGroups/3ca074a8456e1d4940cfa3b7badc1e22"}] }'
Note
The PUT request is transactional. The request either succeeds completely or fails without impact. If all nodes or groups are not passed, a generic error message: "Bad input" occurs and the server group is removed.
Buckets REST API¶
The bucket management and configuration REST API endpoints are provided to fine
level control over the individual buckets in the cluster, their configuration,
and specific operations such as FLUSH.
| HTTP method | URI path | Description |
|---|---|---|
| GET | /pools/default/buckets | Retrieves all bucket and bucket operations information from a cluster. |
| GET | /pools/default/buckets/default | Retrieves information for a single bucket associated with a cluser. |
| GET | /pools/default/buckets/bucket_name/stats | Retrieves bucket statistics for a specific bucket. |
| POST | /pools/default/buckets | Creates a new Couchbase bucket. |
| DELETE | /pools/default/buckets/bucket_name | Deletes a specific bucket. |
| POST | /pools/default/buckets/default/controller/doFlush | Flushes a specific bucket. |
Viewing buckets and bucket operations¶
If you create your own SDK for Couchbase, you can use either the proxy path or the direct path to connect to Couchbase Server. If your SDK uses the direct path, your SDK will not be insulated from most reconfiguration changes to the bucket. This means your SDK will need to either poll the bucket’s URI or connect to the streamingUri to receive updates when the bucket configuration changes. Bucket configuration can happen for instance, when nodes are added, removed, or if a node fails.
To retrieve information for all bucket for cluster:
curl -u admin:password http://localhost:8091/pools/default/buckets
Replace the admin, password, and localhost values in the above example with your actual values.
GET /pools/default/buckets
Host: localhost:8091
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/json
X-memcachekv-Store-Client-Specification-Version: 0.1
HTTP/1.1 200 OK
Server: Couchbase Server 1.6.0
Pragma: no-cache
Date: Wed, 03 Nov 2010 18:12:19 GMT
Content-Type: application/json
Content-Length: nnn
Cache-Control: no-cache no-store max-age=0
[
{
"name": "default",
"bucketType": "couchbase",
"authType": "sasl",
"saslPassword": "",
"proxyPort": 0,
"uri": "/pools/default/buckets/default",
"streamingUri": "/pools/default/bucketsStreaming/default",
"flushCacheUri": "/pools/default/buckets/default/controller/doFlush",
"nodes": [
{
"uptime": "784657",
"memoryTotal": 8453197824.0,
"memoryFree": 1191157760,
"mcdMemoryReserved": 6449,
"mcdMemoryAllocated": 6449,
"clusterMembership": "active",
"status": "unhealthy",
"hostname": "10.1.15.148:8091",
"version": "1.6.0",
"os": "windows",
"ports": {
"proxy": 11211,
"direct": 11210
}
}
],
"stats": {
"uri": "/pools/default/buckets/default/stats"
},
"nodeLocator": "vbucket",
"vBucketServerMap": {
"hashAlgorithm": "CRC",
"numReplicas": 1,
"serverList": [
"192.168.1.2:11210"
],
"vBucketMap": [ [ 0, -1 ], [ 0, -1 ], [ 0, -1 ], [ 0, -1 ], [ 0, -1 ], [ 0, -1 ]]
},
"replicaNumber": 1,
"quota": {
"ram": 104857600,
"rawRAM": 104857600
},
"basicStats": {
"quotaPercentUsed": 24.360397338867188,
"opsPerSec": 0,
"diskFetches": 0,
"itemCount": 0,
"diskUsed": 0,
"memUsed": 25543728
}
},
{
"name": "test-application",
"bucketType": "memcached",
"authType": "sasl",
"saslPassword": "",
"proxyPort": 0,
"uri": "/pools/default/buckets/test-application",
"streamingUri": "/pools/default/bucketsStreaming/test-application",
"flushCacheUri": "/pools/default/buckets/test-application/controller/doFlush",
"nodes": [
{
"uptime": "784657",
"memoryTotal": 8453197824.0,
"memoryFree": 1191157760,
"mcdMemoryReserved": 6449,
"mcdMemoryAllocated": 6449,
"clusterMembership": "active",
"status": "healthy",
"hostname": "192.168.1.2:8091",
"version": "1.6.0",
"os": "windows",
"ports": {
"proxy": 11211,
"direct": 11210
}
}
],
"stats": {
"uri": "/pools/default/buckets/test-application/stats"
},
"nodeLocator": "ketama",
"replicaNumber": 0,
"quota": {
"ram": 67108864,
"rawRAM": 67108864
},
"basicStats": {
"quotaPercentUsed": 4.064150154590607,
"opsPerSec": 0,
"hitRatio": 0,
"itemCount": 1385,
"diskUsed": 0,
"memUsed": 2727405
}
}
]
Getting single bucket information¶
To retrieve information for a single bucket associated with a cluster, you make this request, where the last default can be replaced with the name of a specific bucket, if you have named buckets:
curl -u admin:password \
http://localhost:8091/pools/default/buckets/default
Replace the admin, password, and localhost values in the above example with your actual values.
Couchbase Server returns a large JSON document with bucket information including internal vBucket information:
{
"name":"default",
"bucketType":"membase",
"authType":"sasl",
"saslPassword":"",
"proxyPort":0,
"uri":"/pools/default/buckets/default",
"streamingUri":"/pools/default/bucketsStreaming/default",
"flushCacheUri":"/pools/default/buckets/default/controller/doFlush",
"nodes":[
{
"systemStats":
{
"cpu_utilization_rate":1.5151515151515151,
"swap_total":6140452864.0,
"swap_used":0
},
......
"replicaNumber":1,
"quota":
{
"ram":10246684672.0,
"rawRAM":5123342336.0
},
"basicStats":
{
"quotaPercentUsed":0.5281477251650123,
"opsPerSec":0,"diskFetches":0,
"itemCount":0,
"diskUsed":7518856,
"memUsed":54117632
}
}
]
}
GET http://10.4.2.5:8091/pools/default/buckets/default?_=1340926633052
HTTP/1.1 200 OK
Getting bucket statistics¶
You can use the REST API to get statistics at the bucket level from Couchbase Server. Your request URL should be taken from stats.uri property of a bucket response. By default this request returns stats samples for the last minute and for heavily used keys. You use provide additional query parameters in a request to get a more detailed level of information:
zoom - provide statistics sampling for that bucket stats at a particular interval (minute | hour | day | week | month | year). For example zoom level of minute will provide bucket statistics from the past minute, a zoom level of day will provide bucket statistics for the past day, and so on. If you provide no zoom level, the server returns samples from the past minute.
haveTStamp - request statistics from this timestamp until now. You provide the timestamp as UNIX epoch time. You can get a timestamp for a timeframe by making a REST request to the endpoint with a zoom level.
The following is a sample request to the endpoint with no parameters:
curl -u admin:password http://localhost:8091/pools/default/buckets/bucket_name/stats
Replace the admin, password, localhost, and bucket_name values in the above example with your actual values.
The actual request appears as follows:
GET /pools/default/buckets/<bucket name>/stats
Host: localhost:8091
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/json X-memcachekv-Store-Client-Specification-Version: 0.1
Upon success, you will see output similar to the following:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: nnn
{
"op": {
"samples": {
"hit_ratio": [
0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0
],
"ep_cache_miss_rate": [ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
0 ],
.....
"samplesCount": 60,
"isPersistent": true,
"lastTStamp":513777166.0,
"interval": 1000
},
"hot_keys": [
{
"name": "48697",
"ops": 0.0009276437847866419
},
{
"name": "8487",
"ops": 0.0009276437847866419
},
{
"name": "77262",
"ops": 0.0009276437847866419
},
{
"name": "58495",
"ops": 0.0009276437847866419
},
{
"name": "21003",
"ops": 0.0009276437847866419
},
{
"name": "26850",
"ops": 0.0009276437847866419
},
{
"name": "73717",
"ops": 0.0009276437847866419
},
{
"name": "86218",
"ops": 0.0009276437847866419
},
{
"name": "80344",
"ops": 0.0009276437847866419
},
{
"name": "83457",
"ops": 0.0009276437847866419
}
]
}
}
The following are sample requests at this endpoint with optional parameters. Replace the admin, password, localhost, bucket_name, and 1376963720000 values in the below examples with your actual values.
curl -X GET -u admin:password -d zoom=minute http://localhost:8091/pools/default/buckets/bucket_name/stats
This will sample statistics from a bucket for the last minute.
curl -X GET -u admin:password -d zoom=day http://localhost:8091/pools/default/buckets/bucket_name/stats
This will sample statistics from a bucket for the past day.
Using zoom level of a month:
curl -X GET -u admin:password -d zoom=month http://localhost:8091/pools/default/buckets/bucket_name/stats
This will sample statistics from a bucket for the last month.
Using zoom level of an hour from a specific timestamp:
curl -X GET -u admin:password -d zoom=hour&haveTStamp=1376963720000 http://localhost:8091/pools/default/buckets/bucket_name/stats
This will sample statistics from a bucket from the timestamp until the server receives the REST request.
Sample output for each of these requests appears in the same format and with the same fields. Depending on the level of bucket activity, there may be more detail for each field or less. For the sake of brevity we have omitted sample output for each category.
{
"hot_keys": [],
"op": {
"interval": 1000,
"lastTStamp": 1376963580000,
"isPersistent": true,
"samplesCount": 1440,
"samples": {
"timestamp": [1376955060000, 1376955120000, 1376955180000, 1376955240000, ... ],
"xdc_ops": [0, 0, 0, 0, ... ],
"vb_total_queue_age": [0, 0, 0, 0, ... ],
"vb_replica_queue_size": [0, 0, 0, 0, ... ],
"vb_replica_queue_fill": [0, 0, 0, 0, ... ],
"vb_replica_queue_drain": [0, 0, 0, 0, ... ],
"vb_replica_queue_age": [0, 0, 0, 0, ... ],
"vb_replica_ops_update": [0, 0, 0, 0, ... ],
"vb_replica_ops_create": [0, 0, 0, 0, ... ],
"vb_replica_num_non_resident": [0, 0, 0, 0, ... ],
"vb_replica_num": [0, 0, 0, 0, ... ],
"vb_replica_meta_data_memory": [0, 0, 0, 0, ... ],
"vb_replica_itm_memory": [0, 0, 0, 0, ... ],
"vb_replica_eject": [0, 0, 0, 0, ... ],
"vb_replica_curr_items": [0, 0, 0, 0, ... ],
"vb_pending_queue_size": [0, 0, 0, 0, ... ],
"vb_pending_queue_fill": [0, 0, 0, 0, ... ],
"vb_pending_queue_drain": [0, 0, 0, 0, ... ],
"vb_pending_queue_age": [0, 0, 0, 0, ... ],
"vb_pending_ops_update": [0, 0, 0, 0, ... ],
"vb_pending_ops_create": [0, 0, 0, 0, ... ],
"vb_pending_num_non_resident": [0, 0, 0, 0, ... ],
"vb_pending_num": [0, 0, 0, 0, ... ],
"vb_pending_meta_data_memory": [0, 0, 0, 0, ... ],
"vb_pending_itm_memory": [0, 0, 0, 0, ... ],
"vb_pending_eject": [0, 0, 0, 0, ... ],
"vb_pending_curr_items": [0, 0, 0, 0, ... ],
"vb_active_queue_size": [0, 0, 0, 0, ... ],
"vb_active_queue_fill": [0, 0, 0, 0, ... ],
"vb_active_queue_drain": [0, 0, 0, 0, ... ],
"vb_active_queue_age": [0, 0, 0, 0, ... ],
"vb_active_ops_update": [0, 0, 0, 0, ... ],
"vb_active_ops_create": [0, 0, 0, 0, ... ],
"vb_active_num_non_resident": [0, 0, 0, 0, ... ],
"vb_active_num": [1024, 1024, 1024, 1024, ... ],
"vb_active_meta_data_memory": [0, 0, 0, 0, ... ],
"vb_active_itm_memory": [0, 0, 0, 0, ... ],
"vb_active_eject": [0, 0, 0, 0, ... ],
"ep_ops_create": [0, 0, 0, 0, ... ],
"ep_oom_errors": [0, 0, 0, 0, ... ],
"ep_num_value_ejects": [0, 0, 0, 0, ... ],
"ep_num_ops_set_ret_meta": [0, 0, 0, 0, ... ],
"ep_num_ops_set_meta": [0, 0, 0, 0, ... ],
"ep_num_ops_get_meta": [0, 0, 0, 0, ... ],
"ep_num_ops_del_ret_meta": [0, 0, 0, 0, ... ],
"ep_num_ops_del_meta": [0, 0, 0, 0, ... ],
"ep_num_non_resident": [0, 0, 0, 0, ... ],
"ep_meta_data_memory": [0, 0, 0, 0, ... ],
"ep_mem_low_wat": [402653184, 402653184, 402653184, 402653184, ... ],
"ep_mem_high_wat": [456340275, 456340275, 456340275, 456340275, ... ],
"ep_max_data_size": [536870912, 536870912, 536870912, 536870912, ... ],
"ep_kv_size": [0, 0, 0, 0, ... ],
"ep_item_commit_failed": [0, 0, 0, 0, ... ],
"ep_flusher_todo": [0, 0, 0, 0, ... ],
"ep_diskqueue_items": [0, 0, 0, 0, ... ],
"ep_diskqueue_fill": [0, 0, 0, 0, ... ],
"ep_diskqueue_drain": [0, 0, 0, 0, ... ],
"ep_bg_fetched": [0, 0, 0, 0, ... ],
"disk_write_queue": [0, 0, 0, 0, ... ],
"disk_update_total": [0, 0, 0, 0, ... ],
"disk_update_count": [0, 0, 0, 0, ... ],
"disk_commit_total": [0, 0, 0, 0, ... ],
"disk_commit_count": [0, 0, 0, 0, ... ],
"delete_misses": [0, 0, 0, 0, ... ],
"delete_hits": [0, 0, 0, 0, ... ],
"decr_misses": [0, 0, 0, 0, ... ],
"decr_hits": [0, 0, 0, 0, ... ],
"curr_items_tot": [0, 0, 0, 0, ... ],
"curr_items": [0, 0, 0, 0, ... ],
"curr_connections": [9, 9, 9, 9, ... ],
"avg_bg_wait_time": [0, 0, 0, 0, ... ],
"avg_disk_commit_time": [0, 0, 0, 0, ... ],
"avg_disk_update_time": [0, 0, 0, 0, ... ],
"vb_pending_resident_items_ratio": [0, 0, 0, 0, ... ],
"vb_replica_resident_items_ratio": [0, 0, 0, 0, ... ],
"vb_active_resident_items_ratio": [0, 0, 0, 0, ... ],
"vb_avg_total_queue_age": [0, 0, 0, 0, ... ],
"vb_avg_pending_queue_age": [0, 0, 0, 0, ... ],
"couch_total_disk_size": [8442535, 8449358, 8449392, 8449392, ... ],
"couch_docs_fragmentation": [0, 0, 0, 0, ... ],
"couch_views_fragmentation": [0, 0, 0, 0, ... ],
"hit_ratio": [0, 0, 0, 0, ... ],
"ep_cache_miss_rate": [0, 0, 0, 0, ... ],
"ep_resident_items_rate": [100, 100, 100, 100, ... ],
"vb_avg_active_queue_age": [0, 0, 0, 0, ... ],
"vb_avg_replica_queue_age": [0, 0, 0, 0, ... ],
"bg_wait_count": [0, 0, 0, 0, ... ],
"bg_wait_total": [0, 0, 0, 0, ... ],
"bytes_read": [103.5379762658911, 103.53627151841438, 103.53627262555834, 103.53739884434893, ... ],
"bytes_written": [20793.105529503482, 20800.99759272974, 20802.109356966503, 20803.59949917707, ... ],
"cas_badval": [0, 0, 0, 0, ... ],
"cas_hits": [0, 0, 0, 0, ... ],
"cas_misses": [0, 0, 0, 0, ... ],
"cmd_get": [0, 0, 0, 0, ... ],
"cmd_set": [0, 0, 0, 0, ... ],
"couch_docs_actual_disk_size": [8442535, 8449358, 8449392, 8449392, ... ],
"couch_docs_data_size": [8435712, 8435712, 8435712, 8435712, ... ],
"couch_docs_disk_size": [8435712, 8435712, 8435712, 8435712, ... ],
"couch_views_actual_disk_size": [0, 0, 0, 0, ... ],
"couch_views_data_size": [0, 0, 0, 0, ... ],
"couch_views_disk_size": [0, 0, 0, 0, ... ],
"couch_views_ops": [0, 0, 0, 0, ... ],
"ep_ops_update": [0, 0, 0, 0, ... ],
"ep_overhead": [27347928, 27347928, 27347928, 27347928, ... ],
"ep_queue_size": [0, 0, 0, 0, ... ],
"ep_tap_rebalance_count": [0, 0, 0, 0, ... ],
"ep_tap_rebalance_qlen": [0, 0, 0, 0, ... ],
"ep_tap_rebalance_queue_backfillremaining": [0, 0, 0, 0, ... ],
"ep_tap_rebalance_queue_backoff": [0, 0, 0, 0, ... ],
"ep_tap_rebalance_queue_drain": [0, 0, 0, 0, ... ],
"ep_tap_rebalance_queue_fill": [0, 0, 0, 0, ... ],
"ep_tap_rebalance_queue_itemondisk": [0, 0, 0, 0, ... ],
"ep_tap_rebalance_total_backlog_size": [0, 0, 0, 0, ... ],
"ep_tap_replica_count": [0, 0, 0, 0, ... ],
"ep_tap_replica_qlen": [0, 0, 0, 0, ... ],
"ep_tap_replica_queue_backfillremaining": [0, 0, 0, 0, ... ],
"ep_tap_replica_queue_backoff": [0, 0, 0, 0, ... ],
"ep_tap_replica_queue_drain": [0, 0, 0, 0, ... ],
"ep_tap_replica_queue_fill": [0, 0, 0, 0, ... ],
"ep_tap_replica_queue_itemondisk": [0, 0, 0, 0, ... ],
"ep_tap_replica_total_backlog_size": [0, 0, 0, 0, ... ],
"ep_tap_total_count": [0, 0, 0, 0, ... ],
"ep_tap_total_qlen": [0, 0, 0, 0, ... ],
"ep_tap_total_queue_backfillremaining": [0, 0, 0, 0, ... ],
"ep_tap_total_queue_backoff": [0, 0, 0, 0, ... ],
"ep_tap_total_queue_drain": [0, 0, 0, 0, ... ],
"ep_tap_total_queue_fill": [0, 0, 0, 0, ... ],
"ep_tap_total_queue_itemondisk": [0, 0, 0, 0, ... ],
"ep_tap_total_total_backlog_size": [0, 0, 0, 0, ... ],
"ep_tap_user_count": [0, 0, 0, 0, ... ],
"ep_tap_user_qlen": [0, 0, 0, 0, ... ],
"ep_tap_user_queue_backfillremaining": [0, 0, 0, 0, ... ],
"ep_tap_user_queue_backoff": [0, 0, 0, 0, ... ],
"ep_tap_user_queue_drain": [0, 0, 0, 0, ... ],
"ep_tap_user_queue_fill": [0, 0, 0, 0, ... ],
"ep_tap_user_queue_itemondisk": [0, 0, 0, 0, ... ],
"ep_tap_user_total_backlog_size": [0, 0, 0, 0, ... ],
"ep_tmp_oom_errors": [0, 0, 0, 0, ... ],
"ep_vb_total": [1024, 1024, 1024, 1024, ... ],
"evictions": [0, 0, 0, 0, ... ],
"get_hits": [0, 0, 0, 0, ... ],
"get_misses": [0, 0, 0, 0, ... ],
"incr_hits": [0, 0, 0, 0, ... ],
"incr_misses": [0, 0, 0, 0, ... ],
"mem_used": [27347928, 27347928, 27347928, 27347928, ... ],
"misses": [0, 0, 0, 0, ... ],
"ops": [0, 0, 0, 0, ... ],
"replication_active_vbreps": [0, 0, 0, 0, ... ],
"replication_bandwidth_usage": [0, 0, 0, 0, ... ],
"replication_changes_left": [0, 0, 0, 0, ... ],
"replication_commit_time": [0, 0, 0, 0, ... ],
"replication_data_replicated": [0, 0, 0, 0, ... ],
"replication_docs_checked": [0, 0, 0, 0, ... ],
"replication_docs_latency_aggr": [0, 0, 0, 0, ... ],
"replication_docs_latency_wt": [0, 0, 0, 0, ... ],
"replication_docs_rep_queue": [0, 0, 0, 0, ... ],
"replication_docs_written": [0, 0, 0, 0, ... ],
"replication_meta_latency_aggr": [0, 0, 0, 0, ... ],
"replication_meta_latency_wt": [0, 0, 0, 0, ... ],
"replication_num_checkpoints": [0, 0, 0, 0, ... ],
"replication_num_failedckpts": [0, 0, 0, 0, ... ],
"replication_rate_replication": [0, 0, 0, 0, ... ],
"replication_size_rep_queue": [0, 0, 0, 0, ... ],
"replication_waiting_vbreps": [0, 0, 0, 0, ... ],
"replication_work_time": [0, 0, 0, 0, ... ]
}
}
}
Using the bucket streaming URI¶
The individual bucket request is exactly the same as what would be obtained from the item in the array for the entire buckets list described previously. The streamingUri is exactly the same except it streams HTTP chunks using chunked encoding. A response of “\n\n\n\n” delimits chunks. This will likely be converted to a “zero chunk” in a future release of this API, and thus the behavior of the streamingUri should be considered evolving.
GET /pools/default/buckets/default
Host: localhost:8091
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/json
X-memcachekv-Store-Client-Specification-Version: 0.1
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: nnn
{
"name": "default",
"bucketType": "couchbase",
"authType": "sasl",
"saslPassword": "",
"proxyPort": 0,
"uri": "/pools/default/buckets/default",
"streamingUri": "/pools/default/bucketsStreaming/default",
"flushCacheUri": "/pools/default/buckets/default/controller/doFlush",
"nodes": [
{
"uptime": "308",
"memoryTotal": 3940818944.0,
"memoryFree": 1608724480,
"mcdMemoryReserved": 3006,
"mcdMemoryAllocated": 3006,
"replication": 1.0,
"clusterMembership": "active",
"status": "healthy",
"hostname": "172.25.0.2:8091",
"clusterCompatibility": 1,
"version": "1.6.4r_107_g49a149d",
"os": "i486-pc-linux-gnu",
"ports": {
"proxy": 11211,
"direct": 11210
}
},
{
"uptime": "308",
"memoryTotal": 3940818944.0,
"memoryFree": 1608724480,
"mcdMemoryReserved": 3006,
"mcdMemoryAllocated": 3006,
"replication": 1.0,
"clusterMembership": "active",
"status": "healthy",
"hostname": "172.25.0.3:8091",
"clusterCompatibility": 1,
"version": "1.6.4r_107_g49a149d",
"os": "i486-pc-linux-gnu",
"ports": {
"proxy": 11211,
"direct": 11210
}
},
{
"uptime": "308",
"memoryTotal": 3940818944.0,
"memoryFree": 1608597504,
"mcdMemoryReserved": 3006,
"mcdMemoryAllocated": 3006,
"replication": 1.0,
"clusterMembership": "active",
"status": "healthy",
"hostname": "172.25.0.4:8091",
"clusterCompatibility": 1,
"version": "1.6.4r_107_g49a149d",
"os": "i486-pc-linux-gnu",
"ports": {
"proxy": 11211,
"direct": 11210
}
}
],
"stats": {
"uri": "/pools/default/buckets/default/stats"
},
"nodeLocator": "vbucket",
"vBucketServerMap": {
"hashAlgorithm": "CRC",
"numReplicas": 1,
"serverList": [
"172.25.0.2:11210",
"172.25.0.3:11210",
"172.25.0.4:11210"
],
"vBucketMap": [
[1,0],
[2,0],
[1,2],
[2,1],
[1,2],
[0,2],
[0,1],
[0,1]
]
},
"replicaNumber": 1,
"quota": {
"ram": 1887436800,
"rawRAM":145600
},
"basicStats": {
"quotaPercentUsed": 14.706055058373344,
"opsPerSec": 0,
"diskFetches": 0,
"itemCount": 65125,
"diskUsed": 139132928,
"memUsed": 277567495
}
}
Creating and editing buckets¶
You can create a new bucket with a POST command sent to the URI for buckets in a cluster. This can be used to create either a Couchbase or a Memcached type bucket. The bucket name cannot have a leading underscore.
To create a new Couchbase bucket, or edit the existing parameters for an
existing bucket, you can send a POST to the REST API endpoint. You can also
use this same endpoint to get a list of buckets that exist for a cluster.
Note
Be aware that when you edit bucket properties, if you do not specify an existing bucket property Couchbase Server may reset this the property to be the default. So even if you do not intend to change a certain property when you edit a bucket, you should specify the existing value to avoid this behavior.
The REST API returns a successful response when preliminary files for a data bucket are created on one node. Because you may be using a multi-node cluster, bucket creation may not yet be complete for all nodes when a response is sent. Therefore it is possible that the bucket is not available for operations immediately after this REST call successful returns.
To ensure a bucket is available, the recommended approach is try to read a key from the bucket. If you receive a ‘key not found’ error, or the document for the key, the bucket exists and is available to all nodes in a cluster. You can do this via a Couchbase SDK with any node in the cluster. See the Couchbase Developer Guide for more information.
Method - POST /pools/default/buckets
Request Data - List of payload parameters for the new bucket
Response Data - JSON of the bucket confirmation or error condition
Authentication Required - yes
| Payload Arguments | Description |
|---|---|
authType |
Required parameter. Type of authorization to be enabled for the new bucket as a string. Defaults to blank password if not specified. “sasl” enables authentication. “none” disables authentication. |
bucketType |
Required parameter. Type of bucket to be created. String value. “memcached” configures as Memcached bucket. “couchbase” configures as Couchbase bucket |
flushEnabled |
Optional parameter. Enables the ‘flush all’ functionality on the specified bucket. Boolean. 1 enables flush all support, 0 disables flush all support. Defaults to 0. |
name |
Required parameter. Name for new bucket. |
parallelDBAndViewCompaction |
Optional parameter. String value. Indicates whether database and view files on disk can be compacted simultaneously. Defaults to “false.” |
proxyPort |
Required parameter. Numeric. Proxy port on which the bucket communicates. Must be a valid network port which is not already in use. You must provide a valid port number if the authorization type is not SASL. |
ramQuotaMB |
Required parameter. RAM Quota for new bucket in MB. Numeric. The minimum you can specify is 100, and the maximum can only be as great as the memory quota established for the node. If other buckets are associated with a node, RAM Quota can only be as large as the amount memory remaining for the node, accounting for the other bucket memory quota. |
replicaIndex |
Optional parameter. Boolean. 1 enable replica indexes for replica bucket data while 0 disables. Default of 1. |
replicaNumber |
Optional parameter. Numeric. Number of replicas to be configured for this bucket. Required parameter when creating a Couchbase bucket. Default 1, minimum 0, maximum 3. |
saslPassword |
Optional Parameter. String. Password for SASL authentication. Required if SASL authentication has been enabled. |
threadsNumber |
Optional Parameter. Integer from 2 to 8. Change the number of concurrent readers and writers for the data bucket. For detailed information about this feature, see Using Multi- Readers and Writers. |
| Return Codes | |
| 202 | Accepted |
| 204 | Bad Request JSON with errors in the form of {“errors”: {…. }} name: Bucket with given name already exists ramQuotaMB: RAM Quota is too large or too small replicaNumber: Must be specified and must be a non-negative integer proxyPort: port is invalid, port is already in use |
| 404 | Object Not Found |
When you create a bucket you must provide the authType parameter:
If you set
authTypetonone, then you must specify a proxyPort number.If you set
authTypetosasl, then you may optionally provide asaslPasswordparameter.
The ramQuotaMB parameter specifies how much memory, in megabytes, you want to
allocate to each node for the bucket. The minimum supported value is 100MB.
If the items stored in a memcached bucket take space beyond the
ramQuotaMB, Couchbase Sever typically will evict items on least-requested-item basis. Couchbase Server may evict other infrequently used items depending on object size, or whether or not an item is being referenced.In the case of Couchbase buckets, the system may return temporary failures if the
ramQuotaMBis reached. The system will try to keep 25% of the available ramQuotaMB free for new items by ejecting old items from occupying memory. In the event these items are later requested, they will be retrieved from disk.
For example:
curl -X POST -u admin:password -d name=newbucket -d ramQuotaMB=200 -d authType=none \
-d replicaNumber=2 -d proxyPort=11215 http://localhost:8091/pools/default/buckets
Replace the admin, password, localhost, newbucket, 200, 2, and 11215 values in the above example with your actual values.
The parameters for configuring the bucket are provided as payload data, with each parameter and value provided as a key/value pair, separated by an ampersand.
The HTTP request should include the parameters setting in the payload of the
POST request:
POST /pools/default/buckets
HTTP/1.1
Host: localhost:8091
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Authorization: Basic YWRtaW46YWRtaW4=
Content-Length: xx
name=newbucket&ramQuotaMB=20&authType=none&replicaNumber=2&proxyPort=11215
If the bucket creation was successful, HTTP response 202 (Accepted) will be returned with empty content.
202 Accepted
If the bucket could not be created, because the parameter was missing or incorrect, HTTP response 400 will be returned, with a JSON payload containing the error reason.
Getting bucket configuration¶
To obtain the information about an existing bucket, use the main REST API bucket endpoint with the bucket name. For example:
GET /pools/default/buckets/bucketname
HTTP/1.1 200 OK
Content-Type: application/com.couchbase.store+json
Content-Length: nnn
{
"name" : "Another bucket",
"bucketRules" :
{
"cacheRange" :
{
"min" : 1,
"max" : 599
},
"replicationFactor" : 2
}
"nodes" : [
{
"hostname" : "10.0.1.20",
"uri" : "/addresses/10.0.1.20",
"status" : "healthy",
"ports" :
{
"routing" : 11211,
"kvcache" :1
}
},
{
"hostname" : "10.0.1.21",
"uri" : "/addresses/10.0.1.21",
"status" : "healthy",
"ports" :
{
"routing" : 11211,
"kvcache" :1
}
}
]
}
Clients MUST use the nodes list from the bucket, not the pool to indicate which are the appropriate nodes to connect to.
Modifying bucket parameters¶
You can modify existing bucket parameters by posting the updated parameters used to create the bucket to the bucket’s URI. Do not omit a parameter in your request since this is equivalent to not setting it in many cases. We recommend you do a request to get current bucket settings, make modifications as needed and then make your POST request to the bucket URI.
For example, to edit the bucket customer :
curl -v -X POST -u admin:password -d name=customer \
-d flushEnabled=0 -d replicaNumber=1 -d authType=none \
-d ramQuotaMB=200 -d proxyPort=11212 \
http://localhost:8091/pools/default/buckets/customer
Replace the admin, password, localhost, customer, 0, 1, 200, 11212, and customer values in the above example with your actual values.
Available parameters are identical to those available when creating a bucket. See bucket parameters.
If the request is successful, HTTP response 200 will be returned with an empty data content.
Warning
The bucket name cannot be changed via the REST API.
Increasing bucket memory quota¶
You can increase and decrease a bucket’s ramQuotaMB from its current level. However, while increasing will do no harm, decreasing should be done with proper sizing. Decreasing the bucket’s ramQuotaMB lowers the watermark, and some items may be unexpectedly ejected if the ramQuotaMB is set too low.
Note
There are some known issues with changing the ramQuotaMB for memcached bucket types.
Example of a request:
curl -X POST -u admin:password -d ramQuotaMB=25 -d authType=none \
-d proxyPort=11215 http://localhost:8091/pools/default/buckets/newbucket
Replace the admin, password, localhost, 25, 11215, and new_bucket values in the above example with your actual values.
The response will be 202, indicating the quota will be changed asynchronously throughout the servers in the cluster. An example:
HTTP/1.1 202 OK
Server: Couchbase Server 1.6.0
Pragma: no-cache
Date: Wed, 29 Sep 2010 20:01:37 GMT
Content-Length: 0
Cache-Control: no-cache no-store max-age=0
Changing bucket authentication¶
Changing a bucket from port based authentication to SASL authentication can be achieved by changing the active bucket configuration. You must specify the existing configuration parameters and the changed authentication parameters in the request:
curl -X POST -u admin:password -d ramQuotaMB=130 -d authType=sasl \
-d saslPassword=letmein \
http://localhost:8091/pools/default/buckets/acache
Replace the admin, password, localhost, 130, letmein, and acache values in the above example with your actual values.
Deleting buckets¶
| Method | DELETE /pools/default/buckets/bucket_name
|
|---|---|
| Request Data | None |
| Response Data | None |
| Authentication Required | yes |
| Return Codes | |
| 200 | OK Bucket Deleted on all nodes |
| 401 | Unauthorized |
| 404 | Object Not Found |
| 500 | Bucket could not be deleted on all nodes |
| 503 | Buckets cannot be deleted during a rebalance |
Warning
This operation is data destructive.The service makes no attempt to double check with the user. It simply moves forward. Clients applications using this are advised to double check with the end user before sending such a request.
To delete a bucket, you supply the URL of the Couchbase bucket using the
DELETE operation. For example:
DELETE /pools/default/buckets/default
Host: localhost:8091
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Bucket deletion is a synchronous operation but because the cluster may include a
number of nodes, they may not all be able to delete the bucket. If all the nodes
delete the bucket within the standard timeout of 30 seconds, 200 will be
returned. If the bucket cannot be deleted on all nodes within the 30 second
timeout, a 500 is returned.
Further requests to delete the bucket will return a 404 error. Creating a new
bucket with the same name may return an error that the bucket is still being
deleted.
Flushing buckets¶
Warning
This operation is data destructive. The service makes no attempt to confirm or
double check the request. Client applications using this are advised to double
check with the end user before sending such a request. You can control and limit
the ability to flush individual buckets by setting the flushEnabled parameter
on a bucket in Couchbase Web Console or via cbepctl flush_param.
For information about changing this setting in the Web Console, see Viewing Data Buckets.
The doFlush operation empties the contents of the specified bucket, deleting
all stored data. The operation will only succeed if flush is enabled on
configured bucket. The format of the request is the URL of the REST endpoint
using the POST HTTP operation:
http://localhost:8091/pools/default/buckets/default/controller/doFlush
For example, using curl :
curl -X POST 'http://admin:password@localhost:8091/pools/default/buckets/default/controller/doFlush'
Replace the admin, password, and localhost values in the above example with your actual values.
The equivalent HTTP protocol request:
POST /pools/default/buckets/default/controller/doFlush
Host: localhost:8091
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Parameters and payload data are ignored, but the request must including the authorization header if the system has been secured.
If flushing is disable for the specified bucket, a 400 response will be returned with the bucket status:
{"_":"Flush is disabled for the bucket"}
If the flush is successful, the HTTP response code is 200 :
HTTP/1.1 200 OK
Warning
The flush request may lead to significant disk activity as the data in the bucket is deleted from the database. The high disk utilization may affect the performance of your server until the data has been successfully deleted.
Note
The flush request is not transmitted over XDCR replication configurations; the remote bucket will not be flushed.
Couchbase Server returns a HTTP 404 response if the URI is invalid or if it does not correspond to an active bucket in the system.
404 Not Found
You can configure whether flush is enabled for a bucket by configuring the individual bucket properties, either the REST API (see Modifying Bucket Parameters ), or through the Admin Console (see Creating and Editing Data Buckets ).
Views REST API¶
You can index and query JSON documents using views. Views are functions written in JavaScript that can serve several purposes in your application. You can use them to: find all the documents in your database, create a copy of data in a document and present it in a specific order, create an index to efficiently find documents by a particular value or by a particular structure in the document, represent relationships between documents, and perform calculations on data contained in documents.
You store view functions in a design document as JSON and can use the REST API to manage your design documents.
Querying views with REST¶
Querying can be performed through the REST API endpoint. The REST API supports and operates using the core HTTP protocol, and this is the same system used by the client libraries to obtain the view data.
Use the REST API to query a view by accessing any node within the Couchbase Server cluster on port 8092. For example:
GET http://localhost:8092/bucketname/_design/designdocname/_view/viewname
Where:
bucketnameis the name of the bucket.-
designdocnameis the name of the design document that contains the view.For views defined within the development context (see Development and Production Views ), the
designdocnameis prefixed withdev_. For example, the design documentbeeris accessible as a development view usingdev_beer.Production views are accessible using their name only.
viewnameis the name of the corresponding view within the design document.
When accessing a view stored within an SASL password-protected bucket, you must include the bucket name and bucket password within the URL of the request:
GET http://bucketname:password@localhost:8092/bucketname/_design/designdocname/_view/viewname
Additional arguments to the URL request can be used to select information from the view, and provide limit, sorting and other options. For example, to output only ten items:
GET http://localhost:8092/bucketname/_design/designdocname/_view/viewname?limit=10
The formatting of the URL follows the HTTP specification. The first argument
should be separated from the base URL using a question mark ( ? ). Additional
arguments should be separated using an ampersand ( & ). Special characters
should be quoted or escaped according to the HTTP standard rules.
The additional supported arguments are detailed in the table below.
| Get View Name | Description |
|---|---|
| Method | GET /bucket/_design/design-doc/_view/view-name
|
| Request Data | None |
| Response Data | JSON of the rows returned by the view |
| Authentication Required | no |
| Query Arguments | |
descending |
Return the documents in descending by key order |
| Parameters : boolean; optional | |
endkey |
Stop returning records when the specified key is reached. Key must be specified as a JSON value. |
| Parameters : string; optional | |
endkey_docid |
Stop returning records when the specified document ID is reached |
| Parameters : string; optional | |
full_set |
Use the full cluster data set (development views only). |
| Parameters : boolean; optional | |
group |
Group the results using the reduce function to a group or single row |
| Parameters : boolean; optional | |
group_level |
Specify the group level to be used |
| Parameters : numeric; optional | |
inclusive_end |
Specifies whether the specified end key should be included in the result |
| Parameters : boolean; optional | |
key |
Return only documents that match the specified key. Key must be specified as a JSON value. |
| Parameters : string; optional | |
keys |
Return only documents that match each of keys specified within the given array. Key must be specified as a JSON value. Sorting is not applied when using this option. |
| Parameters : array; optional | |
limit |
Limit the number of the returned documents to the specified number |
| Parameters : numeric; optional | |
on_error |
Sets the response in the event of an error |
| Parameters : string; optional | |
| Supported Values | |
continue : Continue to generate view information in the event of an error, including the error information in the view response stream. |
|
stop : Stop immediately when an error condition occurs. No further view information will be returned. |
|
reduce |
Use the reduction function |
| Parameters : boolean; optional | |
skip |
Skip this number of records before starting to return the results |
| Parameters : numeric; optional | |
stale |
Allow the results from a stale view to be used |
| Parameters : string; optional | |
| Supported Values : | |
false : Force a view update before returning data |
|
ok : Allow stale views |
|
update_after : Allow stale view, update view after it has been accessed |
|
startkey |
Return records with a value equal to or greater than the specified key. Key must be specified as a JSON value. |
| Parameters : string; optional | |
startkey_docid |
Return records starting with the specified document ID |
| Parameters : string; optional |
The output from a view will be a JSON structure containing information about the number of rows in the view, and the individual view information.
An example of the View result is shown below:
{
"total_rows": 576,
"rows" : [
{"value" : 13000, "id" : "James", "key" : ["James", "Paris"] },
{"value" : 20000, "id" : "James", "key" : ["James", "Tokyo"] },
{"value" : 5000, "id" : "James", "key" : ["James", "Paris"] },
…
]
}
The JSON returned consists of two fields:
-
total_rowsA count of the number of rows of information within the stored View. This shows the number of rows in the full View index, not the number of rows in the returned data set.
-
rowsAn array, with each element of the array containing the returned view data, consisting of the value, document ID that generated the row, and the key.
In the event of an error, the HTTP response will be an error type (not 200), and
a JSON structure will be returned containing two fields, the basic error and a
more detailed reason field. For example:
{
"error":"bad_request",
"reason":"invalid UTF-8 JSON: {{error,{1,\"lexical error: invalid char in json text.\\n\"}},\n \"Paris\"}"
}
Note
If you supply incorrect parameters to the query, an error message is returned by the server. Within the Client Libraries the precise behavior may differ between individual language implementations, but in all cases, an invalid query should trigger an appropriate error or exception.
Limiting simultaneous node requests¶
You can use the /internalSettings endpoint to limit the
number of simultaneous requests each node can accept. In earlier releases, too
many simultaneous views requests resulted in a node being overwhelmed. For
general information about this endpoint, see Managing Internal Cluster
Settings.
When Couchbase Server rejects an incoming connection because one of these limits is exceeded, it responds with an HTTP status code of 503. The HTTP Retry-After header will be set appropriately. If the request is made to a REST port, the response body will provide the reason why the request was rejected. If the request is made on a CAPI port, such as a views request, the server will respond with a JSON object with a “error” and “reason” fields.
For example, to change this limit for the port used for views:
curl -X POST -u admin:password http://localhost:8091/internalSettings -d 'capiRequestLimit=50'
Replace the admin, password, localhost, and 50 values in the above example with your actual values.
Will limit the number of simultaneous views requests and internal XDCR requests which can be made on a port. The following are all the port-related request parameters you can set:
restRequestLimit : Maximum number of simultaneous connections each node should accept on a REST port. Diagnostic-related requests and
/internalSettingsrequests are not counted in this limit.capiRequestLimit : Maximum number of simultaneous connections each node should accept on CAPI port. This port is used for XDCR and views connections.
dropRequestMemoryThresholdMiB : In MB. The amount of memory used by Erlang VM that should not be exceeded. If the amount is exceeded the server will start dropping incoming connections.
By default these settings do not have any limit set. We recommend you leave this settings at the default setting unless you experience issues with too many requests impacting a node. If you set these thresholds too low, too many requests will be rejected by the server, including requests from Couchbase Web Console.
Design documents REST API¶
Design documents are used to store one or more view definitions. Views can be defined within a design document and uploaded to the server through the REST API.
Storing design documents¶
To create a new design document with one or more views, you can upload the corresponding design document using the REST API with the definition in place. The format of this command is as shown in the table below:
| Put Design Document | Description |
|---|---|
| Method | PUT /bucket/_design/design-doc
|
| Request Data | Design document definition (JSON) |
| Response Data | Success and stored design document ID |
| Authentication Required | optional |
| Return Codes | |
| 201 | Document created successfully. |
| 401 | The item requested was not available using the supplied authorization, or authorization was not supplied. |
Note
When creating a design document through the REST API, we recommend that you
create a development ( dev ) view. We recommend that you create a dev design
document and views first, and then check the output of the configured views in
your design document. To create a dev view you must explicitly use the dev_
prefix for the design document name.
For example, using curl, you can create a design document, byfield, by
creating a text file (with the name byfield.ddoc ) with the design document
content using the following command:
curl -X PUT -H 'Content-Type: application/json' \
http://user:password@localhost:8092/sales/_design/dev_byfield \
-d @byfield.ddoc
In the above example:
-
-X PUT
Indicates that an HTTP PUT operation is requested.
-
-H ‘Content-Type: application/json’
Specifies the HTTP header information. Couchbase Server requires the information to be sent and identified as the
application/jsondatatype. Information not supplied with the content-type set in this manner will be rejected. -
http://user:password@localhost:8092/sales/_design/dev_byfield
The URL, including authentication information, of the bucket where you want the design document uploaded. The
userandpasswordshould either be the Administration privileges, or for SASL protected buckets, the bucket name and bucket password. If the bucket does not have a password, then the authentication information is not required.
Note
The view being accessed in this case is a development view. To create a
development view, you must use the dev_ prefix to the view name.
As a PUT command, the URL is also significant, in that the location designates
the name of the design document. In the example, the URL includes the name of
the bucket ( sales ) and the name of the design document that will be created
dev_byfield.
-
-d @byfield.ddocSpecifies that the data payload should be loaded from the file
byfield.ddoc.
If successful, the HTTP response code will be 201 (created). The returned JSON
will contain the field ok and the ID of the design document created:
{
"ok":true,
"id":"_design/dev_byfield"
}
The design document will be validated before it is created or updated in the system. The validation checks for valid JavaScript and for the use of valid built-in reduce functions. Any validation failure is reported as an error.
In the event of an error, the returned JSON will include the field error with
a short description, and the field reason with a longer description of the
problem.
The format of the design document should include all the views defined in the design document, incorporating both the map and reduce functions for each named view. For example:
{"views":{"byloc":{"map":"function (doc, meta) {\n if (meta.type == \"json\") {\n emit(doc.city, doc.sales);\n } else {\n emit([\"blob\"]);\n }\n}"}}}
Formatted, the design document looks like this:
{
"views" : {
"byloc" : {
"map" : "function (doc, meta) {\n if (meta.type == \"json\") {\n emit(doc.city, doc.sales);\n } else {\n emit([\"blob\"]);\n }\n}"
}
}
}
The top-level views field lists one or more view definitions (the byloc view
in this example), and for each view, a corresponding map() function.
Retrieving design documents¶
To obtain an existing design document from a given bucket, you need to access
the design document from the corresponding bucket using a GET request, as
detailed in the table below.
| Get Design Document | Description |
|---|---|
| Method | GET /bucket/_design/design-doc
|
| Request Data | Design document definition (JSON) |
| Response Data | Success and stored design document ID |
| Authentication Required | optional |
| Return Codes | |
| 200 | Request completed successfully. |
| 401 | The item requested was not available using the supplied authorization, or authorization was not supplied. |
| 404 | The requested content could not be found. The returned content will include further information, as a JSON object, if available. |
To get back all the design documents with views defined on a bucket, the use following URI path with the GET request. In addition to get specific design documents back, the name of the design document can be specified to retrieve it.
"ddocs": {
"uri": "/pools/default/buckets/default/ddocs" // To obtain design docs for this bucket
}
For example, to get the existing design document from the bucket sales for the
design document byfield :
curl -X GET \
-H 'Content-Type: application/json' \
http://user:password@192.168.0.77:8092/sales/_design/dev_byfield
Through curl this will download the design document to the file dev_byfield
filename.
If the bucket does not have a password, you can omit the authentication information. If the view does not exist you will get an error:
{
"error":"not_found",
"reason":"missing"
}
The HTTP response header will include a JSON document containing the metadata
about the design document being accessed. The information is returned within the
X-Couchbase-Meta header of the returned data. You can obtain this information
by using the -v option to the curl.
For example:
curl -v -X GET \
-H 'Content-Type: application/json' \
http://user:password@192.168.0.77:8092/sales/_design/
* About to connect() to 192.168.0.77 port 8092 (#0)
* Trying 192.168.0.77...
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0* connected
* Connected to 192.168.0.77 (192.168.0.77) port 8092 (#0)
* Server auth using Basic with user 'Administrator'
> GET /sales/_design/something HTTP/1.1
> Authorization: Basic QWRtaW5pc3RyYXRvcjpUYW1zaW4=
> User-Agent: curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0 OpenSSL/0.9.8r zlib/1.2.5
> Host: 192.168.0.77:8092
> Accept: */*
> Content-Type: application/json
>
< HTTP/1.1 200 OK
< X-Couchbase-Meta: {"id":"_design/dev_sample","rev":"5-2785ea87","type":"json"}
< Server: MochiWeb/1.0 (Any of you quaids got a smint?)
< Date: Mon, 13 Aug 2012 10:45:46 GMT
< Content-Type: application/json
< Content-Length: 159
< Cache-Control: must-revalidate
<
{ [data not shown]
100 159 100 159 0 0 41930 0 --:--:-- --:--:-- --:--:-- 53000
* Connection #0 to host 192.168.0.77 left intact
* Closing connection #0
The metadata matches the corresponding metadata for a data document.
Deleting design documents¶
To delete a design document, you use the DELETE HTTP request with the URL of
the corresponding design document. The summary information for this request is
shown in the table below:
| Delete Design Document | Description |
|---|---|
| Method | DELETE /bucket/_design/design-doc
|
| Request Data | Design document definition (JSON) |
| Response Data | Success and confirmed design document ID |
| Authentication Required | optional |
| Return Codes | |
| 200 | Request completed successfully. |
| 401 | The item requested was not available using the supplied authorization, or authorization was not supplied. |
| 404 | The requested content could not be found. The returned content will include further information, as a JSON object, if available. |
Deleting a design document immediately invalidates the design document and all views and indexes associated with it. The indexes and stored data on disk are removed in the background.
For example, to delete the previously created design document using curl :
curl -v -X DELETE -H 'Content-Type: application/json' \
http://Administrator:Password@192.168.0.77:8092/default/_design/dev_byfield
When the design document has been successfully removed, the JSON returned indicates successful completion, and confirmation of the design document removed:
{"ok":true,"id":"_design/dev_byfield"}
Error conditions will be returned if the authorization is incorrect, or the specified design document cannot be found.
XDCR REST API¶
Cross Datacenter Replication (XDCR) enables you to automatically replicate data between clusters and between data buckets. There are several endpoints for the Couchbase REST API that you can use specifically for XDCR. For more information about using and configuring XDCR, see Cross Datacenter Replication (XDCR).
When you use XDCR, you specify source and destination clusters. A source cluster is the cluster from which you want to copy data; a destination cluster is the cluster where you want the replica data to be stored. When you configure replication, you specify your selections for an individual cluster using Couchbase Admin Console. XDCR will replicate data between specific buckets and specific clusters and you can configure replication be either uni-directional or bi-directional. Uni-directional replication means that XDCR replicates from a source to a destination; in contrast, bi-directional replication means that XDCR replicates from a source to a destination and also replicates from the destination to the source. For more information about using Couchbase Web Console to configure XDCR, see Cross Datacenter Replication (XDCR).
Getting a destination cluster reference¶
When you use XDCR, you establish source and destination cluster. A source cluster is the cluster from which you want to copy data; a destination cluster is the cluster where you want the replica data to be stored. To get information about a destination cluster:
curl -u admin:password
http://localhost:8091/pools/default/remoteClusters
Replace the admin, password, and localhost values in the above example with your actual values.
You provide credentials for the cluster and also the hostname and port for the remote cluster. This will generate a request similar to the following sample:
GET /pools/default/remoteClusters HTTP/1.1
Authorization: Basic QWRtaW5pc3RyYXRvcjpwYXNzd29yZA==
User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8r zlib/1.2.5
Host: 10.4.2.4:8091
Accept: */*
If successful, Couchbase Server responds with a JSON response similar to the following:
[{
"name":"remote1",
"uri":"/pools/default/remoteClusters/remote1",
"validateURI":"/pools/default/remoteClusters/remote1?just_validate=1",
"hostname":"10.4.2.6:8091",
"username":"Administrator",
"uuid":"9eee38236f3bf28406920213d93981a3",
"deleted":false
}]
The following describes the response elements:
(String) name: Name of the destination cluster referenced for XDCR.
(String) uri: URI for destination cluster information.
(String) validateURI: URI to validate details of cluster reference.
(String) hostname: Hostname/IP (and :port) of the remote cluster.
(String) uuid: UUID of the remote cluster reference.
(String) username: Username for the destination cluster administrator.
(Boolean) deleted: Indicates whether the reference to the destination cluster has been deleted or not.
For more information about XDCR and using XDCR via the Couchbase Web Console, see Cross Datacenter Replication (XDCR).
Creating a destination cluster reference¶
When you use XDCR, you establish source and destination cluster. A source cluster is the cluster from which you want to copy data; a destination cluster is the cluster where you want the replica data to be stored. To create a reference to a destination cluster:
curl -v -u admin:password1 http://10.4.2.4:8091/pools/default/remoteClusters \
-d uuid=9eee38236f3bf28406920213d93981a3 \
-d name=remote1
-d hostname=10.4.2.6:8091
-d username=admin -d password=password2
Replace the admin, password1, password2, 10.4.2.4, 10.4.2.6, 9eee38236f3bf28406920213d93981a3, and remote1 values in the above example with your actual values.
You provide credentials for the source cluster and information, including credentials and UUID for destination cluster. This will generate a request similar to the following sample:
POST /pools/default/remoteClusters HTTP/1.1
Authorization: Basic QWRtaW5pc3RyYXRvcjpwYXNzd29yZA==
User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8r zlib/1.2.5
Host: 10.4.2.4:8091
Accept: */*
Content-Length: 114
Content-Type: application/x-www-form-urlencoded
If successful, Couchbase Server will respond with a JSON response similar to the following:
{"name":"remote1","uri":"/pools/default/remoteClusters/remote1",
"validateURI":"/pools/default/remoteClusters/remote1?just_validate=1",
"hostname":"10.4.2.6:8091",
"username":"Administrator",
"uuid":"9eee38236f3bf28406920213d93981a3",
"deleted":false}
The following describes the response elements:
(String) name: Name of the destination cluster referenced for XDCR.
(String) validateURI: URI to validate details of cluster reference.
(String) hostname: Hostname/IP (and :port) of the remote cluster.
(String) username: Username for the destination cluster administrator.
(String) uuid: UUID of the remote cluster reference.
(Boolean) deleted: Indicates whether the reference to the destination cluster has been deleted or not.
For more information about XDCR and creating references to destination clusters via the Couchbase Web Console, see Configuring Replication.
Deleting a destination cluster reference¶
You can remove a reference to destination cluster using the REST API. A destination cluster is a cluster to which you replicate data. After you remove it, it will no longer be available for replication via XDCR:
curl -v -X DELETE -u admin:password1 10.4.2.4:8091/pools/default/remoteClusters/remote1
Replace the admin, password1, 10.4.2.4, and remote1 values in the above example with your actual values.
This will send a request similar to the following example:
DELETE /pools/default/remoteClusters/remote1 HTTP/1.1
Authorization: Basic QWRtaW5pc3RyYXRvcjpwYXNzd29yZDE=
User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8r zlib/1.2.5
Host: 10.4.2.4:8091
Accept: */*
If successful, Couchbase Server will respond with a 200 response as well as the string, ‘OK’:
HTTP/1.1 200 OK
Server: Couchbase Server 2.0.0-1941-rel-community
Pragma: no-cache
....
"ok"
For more information about XDCR and references to destination clusters via the Couchbase Web Console, see Configuring Replication.
Creating XDCR replications¶
To replicate data to an established destination cluster from a source cluster, you can use the REST API or Couchbase Web Console. Once you create a replication it will automatically begin between the clusters. As a REST call:
curl -v -X POST -u admin:password1 http://10.4.2.4:8091/controller/createReplication
-d fromBucket=beer-sample
-d toCluster=remote1
-d toBucket=remote_beer
-d replicationType=continuous
-d type=capi
Replace the admin, password1, 10.4.2.4, beer-sample, remote1, remote_beer, and capi values in the above example with your actual values. The replicationType must be continuous. The type values are capi or xmem where capi and xmem are represented by version1 and version 2 in the web console. Default: xmem.
This will send a request similar to the following example:
POST / HTTP/1.1
Authorization: Basic QWRtaW5pc3RyYXRvcjpwYXNzd29yZDE=
User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8r zlib/1.2.5
Host: 10.4.2.4:8091
Accept: */*
Content-Length: 126
Content-Type: application/x-www-form-urlencoded
If Couchbase Server successfully creates the replication, it will immediately begin replicating data from the source to destination cluster. You will get a response similar to the following JSON:
{
"id": "9eee38236f3bf28406920213d93981a3/beer-sample/remote_beer",
"database": "http://10.4.2.4:8092/_replicator"
}
The unique document ID returned in the JSON is a reference you can use if you want to delete the replication.
For more information about XDCR and creating a new replication see Configuring Replication.
Deleting XDCR replications¶
When you delete a replication, it stops replication from the source to the destination. If you re-create the replication between the same source and destination clusters and buckets, it XDCR will resume replication. To delete replication via REST API:
curl -u admin:password1 \
http://10.4.2.4:8091/controller/cancelXDCR/9eee38236f3bf28406920213d93981a3%2Fbeer-sample%2Fremote_beer \
-X DELETE
Replace the admin, password1, 10.4.2.4, 9eee38236f3bf28406920213d93981a3, beer-sample, and remote_beer values in the above example with your actual values.
You use a URL-encoded endpoint which contains the unique document ID that references the replication. You can also delete a replication using the Couchbase Web Console. For more information, see Configuring Replication.
Viewing internal XDCR settings¶
There are internal settings for XDCR which are only exposed via the REST API. These settings will change the replication behavior, performance, and timing. To view an XDCR internal settings, for instance:
curl -u admin:password1 \
http://10.4.2.4:8091/internalSettings
Replace the admin, password1, and 10.4.2.4 values in the above example with your actual values.
You will receive a response similar to the following. For the sake of brevity, we are showing only the XDCR-related items:
{
....
"xdcrMaxConcurrentReps":33,
"xdcrCheckpointInterval":222,
"xdcrWorkerBatchSize":555,
"xdcrDocBatchSizeKb":999,
"xdcrFailureRestartInterval":44
....
}
For more information about these settings and their usage, see Cross Datacenter Replication (XDCR), Providing Advanced Settings.
Changing internal XDCR settings¶
There are internal settings for XDCR which will change the replication behavior, performance, and timing. With the Couchbase Server, endpoints are available to change global settings for replications for a cluster and to change settings for a specific replication ID:
-
/settings/replications/— global settings applied to all replications for a cluster -
/settings/replications/<replication_id>— settings for specific replication for a bucket -
/internalSettings- settings applied to all replications for a cluster. Endpoint exists in Couchbase 2.0 and onward.
As of Couchbase Server 2.2+ you can change settings for a specific replication ID in Web Console | XDCR | Ongoing Replications | Settings. In the REST API you can change these settings globally for all replications for a cluster or for a specific replication ID. For detailed information about these settings including the impact of changes to a setting, see XDCR, Providing Advanced Settings:
| Parameter | Value | Description |
|---|---|---|
xdcrMaxConcurrentReps |
Integer | Equivalent to Web Console setting XDCR Max Replications per Bucket. |
xdcrCheckpointInterval |
Integer | Same as Web Console settingXDCR Checkpoint Interval. |
xdcrWorkerBatchSize |
Integer | Known as Web Console setting XDCR Batch Count. |
xdcrDocBatchSizeKb |
Integer | Same as Web Console setting XDCR Batch Size (KB). |
xdcrFailureRestartInterval |
Integer | equal to Web Console settingXDCR Failure Retry Interval. |
xdcrOptimisticReplicationThreshold |
Integer | Same as to Web Console setting XDCR Optimistic Replication Threshold. |
There are additional internal settings for XDCR which are not yet exposed by Web Console, but are available via the REST API. These parameters are as follows:
| Parameter | Value | Description |
|---|---|---|
workerProcesses |
Integer from 1 to 32. Default 32. | The number of worker processes for each vbucket replicator in XDCR. Setting is available for replications using either memcached or REST for replication. |
httpConnections |
Integer from 1 to 100. Default 2. | Number of maximum simultaneous HTTP connections used for REST protocol. |
The following example updates an XDCR setting for parallel replication streams per node:
curl -X POST -u admin:password1 \
http://10.4.2.4:8091/settings/replications/ \
-d xdcrMaxConcurrentReps=64
Replace the admin, password1, 10.4.2.4, and 64 values in the above example with your actual values.
If Couchbase Server successfully updates this setting, it will send a response as follows:
HTTP/1.1 200 OK
Server: Couchbase Server 2.0.0-1941-rel-community
Pragma: no-cache
Date: Wed, 28 Nov 2012 18:20:22 GMT
Content-Type: application/json
Content-Length: 188
Cache-Control: no-cache
Getting XDCR stats via REST¶
You can get XDCR statistics from either Couchbase Web Console, or the REST API. You perform all of these requests on a source cluster to get information about a destination cluster. All of these requests use the UUID, a unique identifier for destination cluster. You can get this ID by using the REST API if you do not already have it. For instructions, see Getting a Destination Cluster Reference. The endpoints are as follows:
http://hostname:port/pools/default/buckets/[bucket_name]/stats/[destination_endpoint]
# where a possible [destination endpoint] includes:
# number of documents written to destination cluster via XDCR
replications/[UUID]/[source_bucket]/[destination_bucket]/docs_written
# size of data replicated in bytes
replications/[UUID]/[source_bucket]/[destination_bucket]/data_replicated
# number of updates still pending replication
replications/[UUID]/[source_bucket]/[destination_bucket]/changes_left
# number of documents checked for changes
replications/[UUID]/[source_bucket]/[destination_bucket]/docs_checked
# number of checkpoints issued in replication queue
replications/[UUID]/[source_bucket]/[destination_bucket]/num_checkpoints
# number of checkpoints failed during replication
replications/[UUID]/[source_bucket]/[destination_bucket]/num_failedckpts
# size of replication queue in bytes
replications/[UUID]/[source_bucket]/[destination_bucket]/size_rep_queue
# active vBucket replicators
replications/[UUID]/[source_bucket]/[destination_bucket]/active_vbreps
# waiting vBucket replicators
replications/[UUID]/[source_bucket]/[destination_bucket]/waiting_vbreps
# seconds elapsed during replication
replications/[UUID]/[source_bucket]/[destination_bucket]/time_committing
# time working in seconds including wait time
replications/[UUID]/[source_bucket]/[destination_bucket]/time_working
# bandwidth used during replication
replications/[UUID]/[source_bucket]/[destination_bucket]/bandwidth_usage
# aggregate time waiting to send changes to destination cluster in milliseconds
# weighted average latency for sending replicated changes to destination cluster
replications/[UUID]/[source_bucket]/[destination_bucket]/docs_latency_aggr
replications/[UUID]/[source_bucket]/[destination_bucket]/docs_latency_wt
# Number of documents in replication queue
replications/[UUID]/[source_bucket]/[destination_bucket]/docs_rep_queue
# aggregate time to request and receive metadata about documents
# weighted average time for requesting document metadata
# XDCR uses this for conflict resolution prior to sending document into replication queue
replications/[UUID]/[source_bucket]/[destination_bucket]/meta_latency_aggr
replications/[UUID]/[source_bucket]/[destination_bucket]/meta_latency_wt
# bytes replicated per second
replications/[UUID]/[source_bucket]/[destination_bucket]/rate_replication
# number of docs sent optimistically
replications/[UUID]/[source_bucket]/[destination_bucket]/docs_opt_repd
You need to provide properly URL-encoded
/[UUID]/[source_bucket]/[destination_bucket]/[stat_name]. To get the number of
documents written:
curl -u admin:password http://localhost:8091/pools/default/buckets/default/stats/replications%2F8ba6870d88cd72b3f1db113fc8aee675%2Fsource_bucket%2Fdestination_bucket%2Fdocs_written
Replace the admin, password, localhost, 8ba6870d88cd72b3f1db113fc8aee675, source_bucket, and destination_bucket values in the above example with your actual values.
The above command produces the following output:
{"samplesCount":60,"isPersistent":true,"lastTStamp":1371685106753,"interval":1000,
"timestamp":[1371685048753,1371685049754,1371685050753,1371685051753,1371685052753,1371685053753,1371685054753,
1371685055753,1371685056753,1371685057753,1371685058752,1371685059753,1371685060753,1371685061753,1371685062753,
1371685063753,1371685064753,1371685065753,1371685066753,1371685067753,1371685068753,1371685069753,1371685070753,
1371685071753,1371685072753,1371685073753,1371685074753,1371685075753,1371685076753,1371685077753,1371685078753,
1371685079753,1371685080753,1371685081753,1371685082753,1371685083753,1371685084753,1371685085753,1371685086753,
1371685087753,1371685088753,1371685089753,1371685090753,1371685091754,1371685092753,1371685093753,1371685094753,
1371685095753,1371685096753,1371685097753,1371685098753,1371685099753,1371685100753,1371685101753,1371685102753,
1371685103753,1371685104753,1371685105753,1371685106753],
"nodeStats":{"127.0.0.1:8091":[1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,
1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,
1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,
1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,
1000000,1000000,1000000,1000000,1000000,1000000,1000000]}}
This shows that XDCR transferred 1 million documents at each of the timestamps provided. To get the rate of replication, make this REST request:
curl -u admin:password http://localhost:8091/pools/default/buckets/default/stats/replications%2F8ba6870d88cd72b3f1db113fc8aee675%2Fsource_bucket%2Fdestination_bucket%2Frate_replication
Replace the admin, password, localhost, 8ba6870d88cd72b3f1db113fc8aee675, source_bucket, and destination_bucket values in the above example with your actual values.
This will produce the following output:
{"samplesCount":60,"isPersistent":true,"lastTStamp":1371685006753,"interval":1000,
"timestamp":[1371684948753,1371684949753,1371684950753,1371684951753,1371684952753,1371684953753,1371684954753,
1371684955754,1371684956753,1371684957753,1371684958753,1371684959753,1371684960753,1371684961753,1371684962753,
1371684963753,1371684964753,1371684965753,1371684966753,1371684967753,1371684968752,1371684969753,1371684970753,
1371684971753,1371684972753,1371684973753,1371684974753,1371684975753,1371684976753,1371684977753,1371684978753,
1371684979753,1371684980753,1371684981753,1371684982753,1371684983753,1371684984753,1371684985754,1371684986753,
1371684987754,1371684988753,1371684989753,1371684990753,1371684991753,1371684992753,1371684993753,1371684994753,
1371684995753,1371684996753,1371684997753,1371684998776,1371684999753,1371685000753,1371685001753,1371685002753,
1371685003753,1371685004753,1371685005753,1371685006753],
"nodeStats":{"127.0.0.1:8091":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]}}
To get docs_opt_repd you first get the replication id for a source and destination bucket. First get a list active tasks for a cluster:
curl -s -u admin:password \
http://localhost:8091/pools/default/tasks
Replace the admin, password, and localhost values in the above example with your actual values.
This will result in output as follows:
....
"id": "def03dbf5e968a47309194ebe052ed21\/bucket_source\/bucket_destination",
"source": "bucket_source",
"target":"\/remoteClusters\/def03dbf5e968a47309194ebe052ed21\/buckets\/bucket_name",
"continuous": true,
"type": "xdcr",
....
With this replication id you can get a sampling of stats for docs_opt_repd:
http://10.3.121.119:8091/pools/default/buckets/default/stats/ \
replications%2fdef03dbf5e968a47309194ebe052ed21%2fbucket_source%2fbucket_destination%2fdocs_opt_repd
This results in output similar to the following:
{
"samplesCount":60,
"isPersistent":true,
"lastTStamp":1378398438975,
"interval":1000,
"timestamp":[
1378398380976,
1378398381976,
....
You can also see the incoming write operations that occur on a destination cluster due to replication via XDCR. For this REST request, you need to make the request on your destination cluster at the following endpoint:
http://[Destination_IP]:8091/pools/default/buckets/[bucket_name]/stats
This returns results for all stats as follows. Within the JSON you find an
array xdc_ops and the value for this attribute will be the last sampling of
write operations on the destination due to XDCR:
{
.................
"xdc_ops":[0.0,0.0,0.0,0.0,633.3666333666333,1687.6876876876877, \
2610.3896103896104,3254.254254254254,3861.138861138861,4420.420420420421, \
................
}
Many of these statistics are exposed in the Couchbase Web Console. For more information, see Monitoring Outgoing XDCR.
Managing XDCR data encryption¶
The process for configuring XDCR with data encryption (Enterprise Edition only) involves configuring the XDCR cluster reference with data encryption enabled, providing the SSL certificate, and configuring replication.
The following summarizes the HTTP methods used for defining XDCR data encryption:
| HTTP method | URI path | Description |
|---|---|---|
| GET | /pools/default/remoteClusters |
Gets the destination cluster reference |
| POST | /pools/default/remoteClusters |
Creates a reference to the destination cluster |
| PUT | /pools/default/remoteClusters/UUID |
Modifies the destination cluster reference |
| DELETE | /pools/default/remoteClusters/UUID |
Deletes the reference to the destination cluster. |
Retrieving certificates¶
To retrieve the SSL certificate from the destination cluster to the source cluster:
Destination endpoint
/pools/default/certificate
Example
curl http://remoteHost:port/pools/default/certificate > ./remoteCert.pem
Regenerating certificates¶
To regenerate a certificate on a destination cluster:
Destination endpoint
/controller/regenerateCertificate
Example
curl -X POST http://Administrator:asdasd@remoteHost:8091/controller/regenerateCertificate
Configuring XDCR with data encryption¶
A POST to /pools/default/remoteClusters creates the XDCR cluster reference from the source cluster to the destination cluster. Setting the demandEncryption to one (1) and providing the certificate name and location enables data encryption.
Destination endpoint
POST /pools/default/remoteClusters creates the destination cluster reference.
PUT /pools/default/remoteClusters modifies the destination cluster reference.
Syntax
curl –X POST -u Admin:myPassword
http://localHost:port/pools/default/remoteClusters
-d name=<clusterName> // Remote cluster name
-d hostname=<host>:<port> // FQDN of the remote host.
-d username=<adminName> // Remote cluster Admin name
-d password=<adminPassword> // Remote cluster Admin password
-d demandEncryption=[0|1] --data-urlencode "certificate=$(cat remoteCert.pem)"
Example
curl –X POST
-d name=remoteName
-d hostname=10.3.4.187:8091
-d username=remoteAdmin –d password=remotePassword
-d demandEncryption=1 --data-urlencode "certificate=$(cat remoteCert.pem)"
http://Administrator:asdasd@192.168.0.1:8091/pools/default/remoteClusters/
Disabling data encryption¶
To modify the XDCR configuration so that SSL data encryption is disabled, execute a PUT from the source cluster to the destination cluster with demandEncryption=0.
Destination endpoint
/pools/default/remoteClusters
Example
curl –X PUT -u Admin:myPassword
http://192.168.0.1:8091/pools/default/remoteClusters/
-d name=remoteName
-d hostname=10.3.4.187:8091
-d username=remoteAdmin –d password=remotePassword
-d demandEncryption=0
Compaction REST API¶
Set data and index compaction¶
Couchbase Server will write all data that you append, update and delete as files on disk. This process can eventually lead to gaps in the data file, particularly when you delete data. Be aware the server also writes index files in a sequential format based on appending new results in the index. You can reclaim the empty gaps in all data files by performing a process called compaction. In both the case of data files and index files, you will want to perform frequent compaction of the files on disk to help reclaim disk space and reduce disk fragmentation. For more general information on this administrative task, see Database and View Compaction.
Compacting bucket data and indexes¶
To compact data files for a given bucket as well as any indexes associated with that bucket, you make this request:
curl -i -v -X POST -u admin:password http://localhost:8091/pools/default/buckets/bucket_name/controller/compactBucket
Replace the admin, password, localhost, and bucket_name values in the above example with your actual values.
Where you provide the ip and port for a node that accesses the bucket as well as the bucket name. You need to provide administrative credentials for that node in the cluster. To stop bucket compaction, issue this request:
curl -i -v -X POST -u admin:password http://localhost:8091/pools/default/buckets/bucket_name/controller/cancelBucketCompaction
Replace the admin, password, localhost, and bucket_name values in the above example with your actual values.
Compacting spatial views
If you have spatial views in your dataset, these are not automatically compacted with data and indexes. Instead, you must manually compact each spatial view through the REST API.
To do this, you must call the spatial compaction endpoint:
http://127.0.0.1:9500/BUCKETNAME/_design/DDOCNAME/_spatial/_compact
This URL contains the following special information:
-
127.0.0.1:9500The port number, 9500, is unique to the spatial indexing system.
-
BUCKETNAMEThe
BUCKETNAMEis the name of the bucket in which the design document is configured. -
DDOCNAMEThe name of the design document that contains the spatial index or indexes that you want to compact.
For example, you can send a request using curl :
curl -u admin:password -X POST \
'http://localhost:8091/default/_design/dev_test_spatial_compaction/_spatial/_compact'
-H 'Content-type: application/json'
Replace the admin, password, and localhost values in the above example with your actual values.
Setting auto-compaction¶
In Couchbase Server you can also provide auto-compaction settings which will trigger data and view compaction based on certain settings. These settings can be made for an entire cluster or for a bucket in a cluster. For background information, see Admin Tasks, Compaction Process. To details about each setting, see Admin Tasks, Auto-Compaction Configuration
Auto-compaction API
| REST API | Description |
|---|---|
| POST /controller/setAutoCompaction | Set cluster-wide auto-compaction intervals and thresholds |
| GET /settings/autoCompaction | Read cluster-wide settings for auto-compaction |
| GET /pools/default/buckets/bucket_name | Read auto-compaction settings for named bucket |
| POST/pools/default/buckets/bucket_name | Set auto-compaction interval or thresholds for named bucket |
Auto-compaction parameters
You can use the following parameters for global auto-compaction settings which apply to all buckets in a cluster at /controller/setAutoCompaction. You also use these at /pools/default/buckets/<bucket_name>
for bucket-level auto-compaction. You will need to provide administrative credentials to change these settings.
As of Couchbase Server 2.2+ you can provide a purge interval to remove the key and metadata for items that have been deleted or are expired. This is known as ‘tombstone purging’. For background information, see Introduction, Tombstone Purging.
| Parameter | Value | Notes |
|---|---|---|
| databaseFragmentationThreshold[percentage] | Integer between 2 and 100 | Percentage disk fragmentation for data |
| databaseFragmentationThreshold[size] | Integer greater than 1 | Bytes of disk fragmentation for data |
| viewFragmentationThreshold[percentage] | Integer between 2 and 100 | Percentage disk fragmentation for index |
| viewFragmentationThreshold[size] | Integer greater than 1 | Bytes of disk fragmentation for index |
| parallelDBAndViewCompaction | True or false | Run index and data compaction in parallel |
| allowedTimePeriod[fromHour] | Integer between 0 and 23 | Compaction can occur from this hour onward |
| allowedTimePeriod[toHour] | Integer between 0 and 23 | Compaction can occur up to this hour |
| allowedTimePeriod[fromMinute] | Integer between 0 and 59 | Compaction can occur from this minute onward |
| allowedTimePeriod[toMinute] | Integer between 0 and 59 | Compaction can occur up to this minute |
| allowedTimePeriod[abortOutside] | True or false | Terminate compaction if process takes longer than allowed time |
| purgeInterval | Integer between 1 and 60 | Number of days a item is deleted or expired. The key and metadata for that item will be purged by auto-compaction |
To read current auto-compaction settings for a cluster:
curl -u admin:password http://localhost:8091/settings/autoCompaction
Replace the admin, password, and localhost values in the above example with your actual values.
This will result in JSON response as follows:
{
"purgeInterval": 3,
"autoCompactionSettings": {
"viewFragmentationThreshold": {
"size": "undefined",
"percentage": "undefined"
},
"databaseFragmentationThreshold": {
"size": "undefined",
"percentage": "undefined"
},
"parallelDBAndViewCompaction": false
}
}
This tells us we have a purgeInterval of three days and no current thresholds set for data or index compaction. The field parallelDBAndViewCompaction set to ‘false’ indicates the
cluster will not perform data and index compaction in parallel. To see auto-compaction settings for a single bucket,
use this request:
curl -u admin:password http://localhost:8091/pools/default/buckets/bucket_name
Replace the admin, password, localhost, and bucket_name values in the above example with your actual values.
Couchbase Server sends a JSON response with auto-compaction settings for the bucket_name:
{
"purgeInterval": 2,
"autoCompactionSettings": {
"viewFragmentationThreshold": {
"size": "undefined",
"percentage": 30
},
"databaseFragmentationThreshold": {
"size": "undefined",
"percentage": 30
},
"parallelDBAndViewCompaction": true
}
}
This indicates a tombstone purgeInterval of two days with a threshold of 30% disk fragmentation for data and views. This means items can be expired for two days or deleted two ago and their tombstones will be purged during the next auto-compaction run.cluster-wide
Logs REST API¶
This section provides the REST API endpoints for retrieving log and diagnostic information as well as how an SDK can add entries into a log.
| HTTP method | URI path | Description |
|---|---|---|
| GET | /diag |
Retrieves log and additional server diagnostic information. |
| GET | /sasl_logs |
Retrieves log information. |
Retrieving log information¶
Couchbase Server logs various messages, which are available via the REST API. These log messages are optionally categorized by the module. A generic list of log entries or log entries for a particular category can be retrieved.
Note
If the system is secured, administrator credentials are required to access logs.To retrieve log and server diagnostic information, perform a GET with the /diag endpoint.
curl -v -X GET -u Administrator:password
http://127.0.0.1:8091/diag
To retrieve a generic list of logs, perform a GET with the /sasl_logs endpoint.
curl -v -X GET -u Administrator:password
http://127.0.0.1:8091/sasl_logs
To retrieve a specific log file, perform a GET on the sasl_logs endpoint and provide a specific log category.
curl -v -X GET -u Administrator:password
http://127.0.0.1:8091/sasl_logs/<logName>
Where the logName is one of the following log types:
- babysitter
- couchdb
- debug
- error
- info
- mapreduce_errors
- ssl_proxy
- stats
- view
- xdcr
- xdcr_errors
Example
curl -v -X GET -u Administrator:password
http://127.0.0.1:8091/sasl_logs/ssl_proxy
Results
* About to connect() to 10.5.2.118 port 8091 (#0)
* Trying 10.5.2.118... connected
* Connected to 10.5.2.118 (10.5.2.118) port 8091 (#0)
* Server auth using Basic with user 'Administrator'
> GET /sasl_logs/ssl_proxy HTTP/1.1
> Authorization: Basic QWRtaW5pc3RyYXRvcjpwYXNzd29yZA==
> User-Agent: curl/7.21.4 (x86_64-unknown-linux-gnu) libcurl/7.21.4 OpenSSL/0.9.8b zlib/1.2.3
> Host: 10.5.2.118:8091
> Accept: */*
>
< HTTP/1.1 200 OK
< Transfer-Encoding: chunked
< Server: Couchbase Server
< Pragma: no-cache
< Date: Thu, 06 Feb 2014 22:50:12 GMT
< Content-Type: text/plain; charset=utf-8
< Cache-Control: no-cache
<
logs_node (ssl_proxy):
-------------------------------
[ns_server:info,2014-01-24T11:25:18.066,nonode@nohost:<0.30.0>:ns_ssl_proxy:init_logging:84]Brought up ns_ssl_proxy logging
[error_logger:info,2014-01-24T11:25:18.082,nonode@nohost:error_logger<0.5.0>:ale_error_logger_handler:log_report:72]
=========================PROGRESS REPORT=========================
supervisor: {local,ns_ssl_proxy_sup}
started: [{pid,<0.64.0>},
{name,ns_ssl_proxy_server_sup},
{mfargs,{ns_ssl_proxy_server_sup,start_link,[]}},
{restart_type,permanent},
{shutdown,infinity},
{child_type,supervisor}]
Creating a client logging interface¶
Entries can be added to the central log from a custom Couchbase SDK. These entries are typically responses to exceptions such as difficulty handling a server response. For instance, the Web Console uses this functionality to log client error conditions.
To add entries, provide a REST request similar to the following:
POST /logClientError
Host: localhost:8091
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: application/json
X-memcachekv-Store-Client-Specification-Version: 0.1
200 - OK
Users REST API¶
As of Couchbase Server 2.2+ you can create one read-only user with the REST API. For more information about this type of user, see Read-Only Users.
To create a read-only user, you need administrative access:
curl -X POST -u admin:password http://localhost:8091/settings/readOnlyUser -d username=a_name -d password=a_password
Replace the admin, password, localhost, a_name, and a_password values in the above example with your actual values.
Upon success, you will get this response:
success: 200 | []
The endpoint has one additional, optional parameter just_validate=1. If you provide this in
your request the server will validate the username and password for a read-only user but will not
actually create the user.
The following are the endpoints, parameters, expected return values and possible errors:
| Request | Description | Parameters | Returns | Errors |
|---|---|---|---|---|
| POST /settings/readOnlyUser | Create read-only user | username, password, just_validate | success: 200 [] | error: 400 | {“errors”:{field_name:error_message}} |
| PUT /settings/readOnlyUser | Change read-only user password | password | success: 200 [] | error: 400 | {“errors”:{field_name:error_message}} |
| DELETE /settings/readOnlyUser | Delete user | none | success: 200 [] | error: 400 | {“errors”:{field_name:error_message}} |
| GET /settings/readOnlyAdminName | Get the read-only username | none | success: 200 “username” | not found: 404 |
A username is a UTF-8 string that does not contain spaces, control characters or any of these characters: ()<>@,;:\\“/[]?={} characters. Any password must be UTF-8 with no control characters and must be at least six characters long.
To change the password for a read-only user:
curl -X POST -u admin:password http://localhost:8091/settings/readOnlyUser -d username=a_name -d password=new_password
To delete this user:
curl -X DELETE -u admin:password http://localhost:8091/settings/readOnlyUser
To get the read-only username, you can have administrative or read-only permissions:
curl -u username:password http://localhost:8091/settings/readOnlyAdminName
Replace the admin, password, localhost, username, a_name, and new_password values in the above examples with your actual values.
This will return a response with the read-only username as payload, success: 200 | "username". If there is no
read-only user you will get this error not found: 404.