Couchbase Node.js SDK

Class: Bucket

Bucket

The Bucket class represents a connection to a Couchbase bucket. Never instantiate this class directly. Instead use the Cluster#openBucket method instead.

<private> new Bucket()

Since:
  • 2.0.0 (stability: committed)

Classes

N1qlQueryResponse
TranscoderDoc
ViewQueryResponse

Members

clientVersion :string

Returns the version of the Node.js library as a string.

Type:
  • string
Since:
  • 2.0.0 (stability: committed)
Example
"2.0.0-beta.fa123bd"

configThrottle :number

Gets or sets the config throttling in milliseconds. The config throttling is the time that Bucket will wait before forcing a configuration refresh. If no refresh occurs before this period while a configuration is marked invalid, an update will be triggered.

Type:
  • number
Since:
  • 2.0.0 (stability: committed)

connectionTimeout :number

Sets or gets the connection timeout in milliseconds. This is the timeout value used when connecting to the configuration port during the initial connection (in this case, use this as a key in the 'options' parameter in the constructor) and/or when Bucket attempts to reconnect in-situ (if the current connection has failed).

Type:
  • number
Since:
  • 2.0.0 (stability: committed)
Default Value:
  • 5000

durabilityInterval :number

Gets or sets the durability interval in milliseconds. The durability interval is the time that Bucket will wait between requesting new durability information during a durability poll.

Type:
  • number
Since:
  • 2.0.0 (stability: committed)

durabilityTimeout :number

Gets or sets the durability timeout in milliseconds. The durability timeout is the time that Bucket will wait for a response from the server in regards to a durability request. If there are no responses received within this time frame, the request fails with an error.

Type:
  • number
Since:
  • 2.0.0 (stability: committed)

lcbVersion :string

Returns the libcouchbase version as a string. This information will usually be in the format of 2.4.0-fffffff representing the major, minor, patch and git-commit that the built libcouchbase is based upon.

Type:
  • string
Since:
  • 2.0.0 (stability: committed)
Example
"2.4.0-beta.adbf222"

managementTimeout :number

Gets or sets the management timeout in milliseconds. The management timeout is the time that Bucket will wait for a response from the server for a management request. If the response is not received within this time frame, the request is failed out with an error.

Type:
  • number
Since:
  • 2.0.0 (stability: committed)

nodeConnectionTimeout :number

Sets or gets the node connection timeout in msecs. This value is similar to Bucket#connectionTimeout, but defines the time to wait for a particular node to respond before trying the next one.

Type:
  • number
Since:
  • 2.0.0 (stability: committed)

operationTimeout :number

Gets or sets the operation timeout in milliseconds. The operation timeout is the time that Bucket will wait for a response from the server for a CRUD operation. If the response is not received within this time frame, the operation is failed with an error.

Type:
  • number
Since:
  • 2.0.0 (stability: committed)
Default Value:
  • 2500

viewTimeout :number

Gets or sets the view timeout in milliseconds. The view timeout is the time that Bucket will wait for a response from the server for a view request. If the response is not received within this time frame, the request fails with an error.

Type:
  • number
Since:
  • 2.0.0 (stability: committed)

Methods

append(key, fragment, options, callback)

Similar to Bucket#upsert, but instead of setting a new key, it appends data to the existing key. Note that this function only makes sense when the stored data is a string; 'appending' to a JSON document may result in parse errors when the document is later retrieved.

Parameters:
Name Type Argument Description
key string | Buffer

The target document key.
fragment *

The document's contents to append.
options Object <optional>
Properties
Name Type Argument Default Description
cas Bucket.CAS <optional>

The CAS value to check. If the item on the server contains a different CAS value, the operation will fail. Note that if this option is undefined, no comparison will be performed.
persist_to number <optional>
 0

Ensures this operation is persisted to this many nodes
replicate_to number <optional>
 0

Ensures this operation is replicated to this many nodes
callback Bucket.OpCallback
Since:
  • 2.0.0 (stability: committed)
See:

counter(key, delta, options, callback)

Increments or decrements a key's numeric value.

Note that JavaScript does not support 64-bit integers (while libcouchbase and the server do). You might receive an inaccurate value if the number is greater than 53-bits (JavaScript's maximum integer precision).

Parameters:
Name Type Argument Description
key string | Buffer

The target document key.
delta number

The amount to add or subtract from the counter value. This value may be any non-zero integer.
options Object <optional>
Properties
Name Type Argument Default Description
initial number <optional>

Sets the initial value for the document if it does not exist. Specifying a value of undefined will cause the operation to fail if the document does not exist, otherwise this value must be equal to or greater than 0.
expiry number <optional>
 0

Set the initial expiration time for the document. A value of 0 represents never expiring.
persist_to number <optional>
 0

Ensures this operation is persisted to this many nodes
replicate_to number <optional>
 0

Ensures this operation is replicated to this many nodes
callback Bucket.OpCallback
Since:
  • 2.0.0 (stability: committed)

disconnect()

Shuts down this connection.

Since:
  • 2.0.0 (stability: committed)

enableN1ql(hosts)

Enables N1QL support on the client. A cbq-server URI must be passed. This method will be deprecated in the future in favor of automatic configuration through the connected cluster.

Parameters:
Name Type Description
hosts string | Array.<string>

An array of host/port combinations which are N1QL servers attached to this cluster.
Since:
  • 2.0.0 (stability: volatile)
Example
bucket.enableN1ql(['http://1.1.1.1:8093/','http://1.1.1.2:8093']);

get(key, options, callback)

Retrieves a document.

Parameters:
Name Type Argument Description
key string | Buffer

The target document key.
options Object <optional>
callback Bucket.OpCallback
Since:
  • 2.0.0 (stability: committed)

getAndLock(key, options, callback)

Lock the document on the server and retrieve it. When an document is locked, its CAS changes and subsequent operations on the document (without providing the current CAS) will fail until the lock is no longer held.

This function behaves identically to Bucket#get in that it will return the value. It differs in that the document is also locked. This ensures that attempts by other client instances to access this document while the lock is held will fail.

Once locked, a document can be unlocked either by explicitly calling Bucket#unlock or by performing a storage operation (e.g. Bucket#upsert, Bucket#replace, Bucket::append) with the current CAS value. Note that any other lock operations on this key will fail while a document is locked.

Parameters:
Name Type Argument Description
key string | Buffer

The target document key.
options Object <optional>
Properties
Name Type Argument Default Description
lockTime number <optional>
 15

The duration of time the lock should be held for. Note that the maximum duration for a lock is 30 seconds, and if a higher value is specified, it will be rounded to this number.
callback Bucket.OpCallback
Since:
  • 2.0.0 (stability: committed)
See:

getAndTouch(key, expiry, options, callback)

Retrieves a document and updates the expiry of the item at the same time.

Parameters:
Name Type Argument Description
key string | Buffer

The target document key.
expiry number

The expiration time to use. If a value of 0 is provided, then the current expiration time is cleared and the key is set to never expire. Otherwise, the key is updated to expire in the time provided (in seconds).
options Object <optional>
callback Bucket.OpCallback
Since:
  • 2.0.0 (stability: committed)
See:

getMulti(keys, callback)

Retrieves a list of keys

Parameters:
Name Type Description
keys Array.<(Buffer|string)>

The target document keys.
callback Bucket.MultiGetCallback
Since:
  • 2.0.0 (stability: committed)
See:

getReplica(key, options, callback)

Get a document from a replica server in your cluster.

Parameters:
Name Type Argument Description
key string | Buffer

The target document key.
options Object <optional>
Properties
Name Type Argument Description
index number <optional>

The index for which replica you wish to retrieve this value from, or if undefined, use the value from the first server that replies.
callback Bucket.OpCallback
Since:
  • 2.0.0 (stability: committed)
See:

insert(key, value, options, callback)

Identical to Bucket#upsert but will fail if the document already exists.

Parameters:
Name Type Argument Description
key string | Buffer

The target document key.
value *

The document's contents.
options Object <optional>
Properties
Name Type Argument Default Description
expiry number <optional>
 0

Set the initial expiration time for the document. A value of 0 represents never expiring.
persist_to number <optional>
 0

Ensures this operation is persisted to this many nodes
replicate_to number <optional>
 0

Ensures this operation is replicated to this many nodes
callback Bucket.OpCallback
Since:
  • 2.0.0 (stability: committed)

lookupIn(key, options) → {LookupInBuilder}

Creates a sub-document lookup operation builder.

Parameters:
Name Type Description
key string
options Object
Since:
  • 2.1.4 (stability: volatile)
Returns:
Type
LookupInBuilder

manager() → {BucketManager}

Returns an instance of a BuckerManager for performing management operations against a bucket.

Since:
  • 2.0.0 (stability: committed)
Returns:
Type
BucketManager

mutateIn(key, options) → {MutateInBuilder}

Creates a sub-document mutation operation builder.

Parameters:
Name Type Description
key string
options Object
Since:
  • 2.1.4 (stability: volatile)
Returns:
Type
MutateInBuilder

prepend(key, fragment, options, callback)

Like Bucket#append, but prepends data to the existing value.

Parameters:
Name Type Argument Description
key string | Buffer

The target document key.
fragment *

The document's contents to prepend.
options Object <optional>
Properties
Name Type Argument Default Description
cas Bucket.CAS <optional>

The CAS value to check. If the item on the server contains a different CAS value, the operation will fail. Note that if this option is undefined, no comparison will be performed.
persist_to number <optional>
 0

Ensures this operation is persisted to this many nodes
replicate_to number <optional>
 0

Ensures this operation is replicated to this many nodes
callback Bucket.OpCallback
Since:
  • 2.0.0 (stability: committed)
See:

query(query, params, callback) → {Bucket.ViewQueryResponse|Bucket.N1qlQueryResponse}

Executes a previously prepared query object. This could be a ViewQuery or a N1qlQuery.

Note: N1qlQuery queries are currently an uncommitted interface and may be subject to change in 2.0.0's final release.

Parameters:
Name Type Argument Description
query ViewQuery | N1qlQuery

The query to execute.
params Object | Array <optional>

A list or map to do replacements on a N1QL query.
callback Bucket.QueryCallback
Since:
  • 2.0.0 (stability: committed)
Returns:
Type
Bucket.ViewQueryResponse | Bucket.N1qlQueryResponse

remove(key, options, callback)

Deletes a document on the server.

Parameters:
Name Type Argument Description
key string | Buffer

The target document key.
options Object <optional>
Properties
Name Type Argument Default Description
cas Bucket.CAS <optional>

The CAS value to check. If the item on the server contains a different CAS value, the operation will fail. Note that if this option is undefined, no comparison will be performed.
persist_to number <optional>
 0

Ensures this operation is persisted to this many nodes
replicate_to number <optional>
 0

Ensures this operation is replicated to this many nodes
callback Bucket.OpCallback
Since:
  • 2.0.0 (stability: committed)

replace(key, value, options, callback)

Identical to Bucket#upsert, but will only succeed if the document exists already (i.e. the inverse of Bucket#insert).

Parameters:
Name Type Argument Description
key string | Buffer

The target document key.
value *

The document's contents.
options Object <optional>
Properties
Name Type Argument Default Description
cas Bucket.CAS <optional>

The CAS value to check. If the item on the server contains a different CAS value, the operation will fail. Note that if this option is undefined, no comparison will be performed.
expiry number <optional>
 0

Set the initial expiration time for the document. A value of 0 represents never expiring.
persist_to number <optional>
 0

Ensures this operation is persisted to this many nodes
replicate_to number <optional>
 0

Ensures this operation is replicated to this many nodes
callback Bucket.OpCallback
Since:
  • 2.0.0 (stability: committed)

setTranscoder(encoder, decoder)

Configures a custom set of transcoder functions for encoding and decoding values that are being stored or retreived from the server.

Parameters:
Name Type Description
encoder EncoderFunction

The function for encoding.
decoder DecoderFunction

The function for decoding.
Since:
  • 2.0.0 (stability: committed)

touch(key, expiry, options)

Update the document expiration time.

Parameters:
Name Type Argument Description
key string | Buffer

The target document key.
expiry number

The expiration time to use. If a value of 0 is provided, then the current expiration time is cleared and the key is set to never expire. Otherwise, the key is updated to expire in the time provided (in seconds). Values larger than 302460*60 seconds (30 days) are interpreted as absolute times (from the epoch).
options Object <optional>
Properties
Name Type Argument Default Description
persist_to number <optional>
 0

Ensures this operation is persisted to this many nodes
replicate_to number <optional>
 0

Ensures this operation is replicated to this many nodes
callback. Bucket.OpCallback
Since:
  • 2.0.0 (stability: committed)

unlock(key, cas, options, callback)

Unlock a previously locked document on the server. See the Bucket#lock method for more details on locking.

Parameters:
Name Type Argument Description
key string | Buffer

The target document key.
cas Bucket.CAS

The CAS value returned when the key was locked. This operation will fail if the CAS value provided does not match that which was the result of the original lock operation.
options Object <optional>
callback Bucket.OpCallback
Since:
  • 2.0.0 (stability: committed)
See:

upsert(key, value, options, callback)

Stores a document to the bucket.

Parameters:
Name Type Argument Description
key string | Buffer

The target document key.
value *

The document's contents.
options Object <optional>
Properties
Name Type Argument Default Description
cas Bucket.CAS <optional>

The CAS value to check. If the item on the server contains a different CAS value, the operation will fail. Note that if this option is undefined, no comparison will be performed.
expiry number <optional>
 0

Set the initial expiration time for the document. A value of 0 represents never expiring.
persist_to number <optional>
 0

Ensures this operation is persisted to this many nodes
replicate_to number <optional>
 0

Ensures this operation is replicated to this many nodes
callback Bucket.OpCallback
Since:
  • 2.0.0 (stability: committed)

Type Definitions

CAS

The CAS value is a special object that indicates the current state of the item on the server. Each time an object is mutated on the server, the value is changed. CAS objects can be used in conjunction with mutation operations to ensure that the value on the server matches the local value retrieved by the client. This is useful when doing document updates on the server as you can ensure no changes were applied by other clients while you were in the process of mutating the document locally.

In the Node.js SDK, the CAS is represented as an opaque value. As such,y ou cannot generate CAS objects, but should rather use the values returned from a Bucket.OpCallback.

Type:
  • Object

DecoderFunction(doc) → {*}

Transcoder Decoding Function.

This function will receive an object containing a Buffer value and an integer value representing any flags metadata whenever a retrieval operation is executed. It is expected that this function will return a value representing the original value stored and encoded with its matching EncoderFunction.

Parameters:
Name Type Description
doc Bucket.TranscoderDoc

The data from Couchbase to decode.
Returns:

The resulting value.

Type
*

EncoderFunction(value) → {Bucket.TranscoderDoc}

Transcoder Encoding Function.

This function will receive a value when a storage operation is invoked that needs to encode user-provided data for storage into Couchbase. It expects to be returned a Buffer object to store along with an integer representing any flag metadata relating to how to decode the key later using the matching DecoderFunction.

Parameters:
Name Type Description
value *

The value needing encoding.
Returns:

The data to store to Couchbase.

Type
Bucket.TranscoderDoc

MultiGetCallback(error, results)

Multi-Get Callback.

This callback is used to return results from a getMulti operation.

Parameters:
Name Type Description
error undefined | number

The number of keys that failed to be retrieved. The precise errors are available by checking the error property of the individual documents.
results Array.<Object>

This is a map of keys to results. The result for each key will optionally contain an error if one occured, or if no error occured will contain the CAS and value of the document.

OpCallback(error, result)

Single-Key callbacks.

This callback is passed to all of the single key functions.

It returns a result objcet containing a combination of a CAS and a value, depending on which operation was invoked.

Parameters:
Name Type Description
error undefined | Error

The error for the operation. This can either be an Error object or a value which evaluates to false (null, undefined, 0 or false).
result Object

The result of the operation that was executed. This usually contains at least a cas property, and on some operations will contain a value property as well.

QueryCallback(error, rows, meta)

This is used as a callback from executed queries. It is a shortcut method that automatically subscribes to the rows and error events of the Bucket.ViewQueryResponse.

Parameters:
Name Type Description
error undefined | Error

The error for the operation. This can either be an Error object or a falsy value.
rows Array.<Object>

The rows returned from the query
meta Bucket.ViewQueryResponse.Meta

The metadata returned by the query.

Events

connect

Connected Event. Invoked once the connection has been established successfully.

Since:
  • 2.0.0 (stability: committed)

error

Error Event. Invoked if the connection encounters any errors without having an operation context available to handle the error.

Parameters:
Name Type Description
err Error

The error that occured while attempting to connect to the cluster.
Since:
  • 2.0.0 (stability: committed)