SXAPI Resource : couchbase
This resource allow you to interact with a Couchbase Enterprise Server Cluster. Programmers can access resource methods and embed this module methods into there own method and endpoints. API developpers can use resource endpoints into there configuration profile to expose couchbase data.
This resource is based on couchbase npm module and is part of the sxapi-core engine from .
Resource configuration
To configure this resource, you must add a config key under the resources
section of your configuration profile.
This key must be a unique string and will be considered as the resource id. The value
must be an object who must have the appropriate configuration parameters.
For a better understanting of the sxapi configuration profile, please refer to the configuration guide
This config object will be used with couchbase.Cluster()
method of the nodejs couchbase module.
Read couchbase sdk documentation
for more information.
Resource config parameters
Param | Mandatory | Type | default | Description |
---|---|---|---|---|
_class | yes | string | module name. Must be couchbase for this resource | |
cluster | yes | string | connection tring to the cluster. format is couchbase://host[/bucket] You have to give the full URL, with protocol (http or https) and port number (must be 8091) . If you want to reach a cluster on the same machine using docker, don't forget to use the docker0 interface IP (like 172.17.x.x) using # ifconfig docker0 and not localhost or 127.0.0.1. Example : http://172.17.42.1:8091. read more on couchbase connection |
|
bucket | yes | string | the bucket name to use. If you need to connect to several bucket, you'll have to create several resources | |
user | no | string | Username to use for authentication (in conjuction with password ) |
|
password | no | string | Password for the previously defined username |
|
insertOptions | no | object | options used when inserting a document to the bucket. See Couchbase Docs for more informations | |
insertOptions.persist_to | no | int | Ensures this operation is persisted to this many nodes. Default is set to 0. | |
insertOptions.replicate_to | no | int | Ensures this operation is replicated to this many nodes. Default is set to 0. | |
insertOptions.expiry | no | int | Set the initial expiration time for the document. A value of 0 represents never expiring. Default is set to 0. | |
updateOptions | no | object | options used when updating a document to the bucket. See Couchbase Docs for more informations | |
updateOptions.persist_to | no | int | Ensures this operation is persisted to this many nodes. Default is set to 0. | |
updateOptions.replicate_to | no | int | Ensures this operation is replicated to this many nodes. Default is set to 0. | |
updateOptions.expiry | no | int | Set the initial expiration time for the document. A value of 0 represents never expiring. Default is set to 0. | |
deleteOptions | no | object | options used when deleting a document to the bucket. See Couchbase Docs for more informations | |
deleteOptions.persist_to | no | int | Ensures this operation is persisted to this many nodes. Default is set to 0. | |
deleteOptions.replicate_to | no | int | Ensures this operation is replicated to this many nodes. Default is set to 0. | |
deleteOptions.expiry | no | int | Set the initial expiration time for the document. A value of 0 represents never expiring. Default is set to 0. |
Example
This is a sample configuration of this resource. You must add this section under
the resources
section of your configuration profile
resources:
couchbase-id:
_class: couchbase
cluster: http://172.17.42.1:8091
bucket: bucket
insertOptions:
expiry: 3600
Resource methods
If you want to use this resource in our own module, you can retrieve this resource
instance by using $app.resources.get('couchbase-id')
where couchbase-id
is the
id of your resource as defined in the resource configuration.
This module come with 6 methods for manipulating couchbase dataset.
1. Read method
2. Query method
3. Queryfree method
4. Insert method
5. Update method
6. Delete method
Method read
read a couchbase value by it's given document ID.
Parameters
Param | Mandatory | Type | default | Description |
---|---|---|---|---|
docID | yes | string | null | document ID to find |
callback | no | function | default | callback function called when server answer the request. If not defined, dropped to a default function who output information to the debug console |
callback(error,response) | N/A | mixed | null | will be false or null if no error returned from the couchbase SDK. Will be an error object if an error occur. |
callback(error,response) | N/A | mixed | the document object (if no error) |
Example
var resource = $app.resources.get('couchbase-id');
resource.read('docID', function (error, response) {
console.log(error, response);
});
Method query
Send a N1QL request to the query service of the couchbase cluster defined in the given resource. Use Query and Index node as well as Data Node according to your query. Take care of having theses services optimized for the kind of query you perform.
Parameters
Param | Mandatory | Type | default | Description |
---|---|---|---|---|
n1ql | yes | string | null | A N1QL query for selecting dataset |
callback | no | function | default | callback function called when server answer the request. If not defined, dropped to a default function who output information to the debug console |
callback(error,response) | N/A | mixed | null | will be false or null if no error returned from the couchbase SDK. Will be an error object if an error occur. |
callback(error,response) | N/A | mixed | the document object (if no error) |
Example
var resource = $app.resources.get('couchbase-id');
resource.query('SELECT name FROM `beer-sample` WHERE brewery_id ="mishawaka_brewing";', function (error, response) {
console.log(error, response);
});
Method queryFree
Send a view request to the query service of the couchbase cluster defined in the given resource. Use only map-reduce function into Data node and work perfectly for targeted data manipulation.
Parameters
Param | Mandatory | Type | default | Description |
---|---|---|---|---|
query | yes | object | options used when inserting a document to the bucket. See Couchbase Docs for more informations | |
query.ddoc | yes | string | Design Document. View group in couchbase terminology. | |
query.name | yes | string | View name to query | |
callback | no | function | default | callback function called when server answer the request. If not defined, dropped to a default function who output information to the debug console |
callback(error,response) | N/A | mixed | null | will be false or null if no error returned from the couchbase SDK. Will be an error object if an error occur. |
callback(error,response) | N/A | mixed | the document object (if no error) |
Example
var resource = $app.resources.get('couchbase-id');
resource.queryFree({ddoc: "beers", name : "brewery_beers"}, function (error, response) {
console.log(error, response);
});
Method insert
insert a couchbase document associated to the given ID. Use KV capabilities of Couchbase and work extremely fast on well sized cluster.
Parameters
Param | Mandatory | Type | default | Description |
---|---|---|---|---|
docID | yes | string | null | document ID to use |
document | yes | string | null | document associated to this ID |
callback | no | function | default | callback function called when server answer the request. If not defined, dropped to a default function who output information to the debug console |
callback(error,response) | N/A | mixed | null | will be false or null if no error returned from the couchbase SDK. Will be an error object if an error occur. |
callback(error,response) | N/A | mixed | the document object (if no error) |
Example
var resource = $app.resources.get('couchbase-id');
resource.insert('docID', 'my document', function (error, response) {
console.log(error, response);
});
Method update
update a couchbase value associated to the given document ID. Use KV capabilities of Couchbase and work extremely fast on well sized cluster.
Parameters
Param | Mandatory | Type | default | Description |
---|---|---|---|---|
docID | yes | string | null | document ID to update |
document | yes | string | null | the new document associated to this ID |
callback | no | function | default | callback function called when server answer the request. If not defined, dropped to a default function who output information to the debug console |
callback(error,response) | N/A | mixed | null | will be false or null if no error returned from the couchbase SDK. Will be an error object if an error occur. |
callback(error,response) | N/A | mixed | the document object (if no error) |
Example
var resource = $app.resources.get('couchbase-id');
resource.update('docID', 'my new document', function (error, response) {
console.log(error, response);
});
Method delete
delete a couchbase document ID and it associated value. Use KV capabilities of Couchbase and work extremely fast on well sized cluster.
Parameters
Param | Mandatory | Type | default | Description |
---|---|---|---|---|
docID | yes | string | null | document ID to delete |
callback | no | function | default | callback function called when server answer the request. If not defined, dropped to a default function who output information to the debug console |
callback(error) | N/A | mixed | null | will be false or null if no error returned from the couchbase SDK. Will be an error object if an error occur. |
Example
var resource = $app.resources.get('couchbase-id');
resource.delete('docID', function (error) {
console.log(error);
});
Resource endpoints
This module come with 5 endpoints who can interact with any couchbase method.
1. List endpoint
2. Read endpoint
3. Create endpoint
4. Update endpoint
5. Delete endpoint
List endpoint
The purpose of this endpoint is to make call to a couchbase server and to return the value associated to the given document ID.
Parameters
Param | Mandatory | Type | default | Description |
---|---|---|---|---|
path | yes | string | path used as client endpoint (must start with /) | |
resource | yes | string | resource id declared in the resource of your config profile | |
endpoint | yes | string | endpoint name declared in the resource module. In this case must be "list" | |
n1ql | yes | string | the n1ql query to execute and get a result from |
Example
server:
endpoints:
- path: "/couchbase"
resource: couchbase-id
endpoint: list
n1ql: SELECT name FROM `beer-sample` WHERE brewery_id ="mishawaka_brewing";
Read endpoint
The purpose of this endpoint is to make call to a couchbase server and to return the value associated to the given document ID. Use KV capabilities of Couchbase and work extremely fast on well sized cluster.
Parameters
Param | Mandatory | Type | default | Description |
---|---|---|---|---|
path | yes | string | path used as client endpoint (must start with /) | |
resource | yes | string | resource id declared in the resource of your config profile | |
endpoint | yes | string | endpoint name declared in the resource module. In this case must be "read" | |
keyParam | no | string | id | param name containing the key received from the client |
docPrefix | no | string | a document prefix to use in conjuction with the received key |
Example
server:
endpoints:
- path: "/couchbase/:id"
resource: couchbase-id
endpoint: read
Create endpoint
The purpose of this endpoint is to insert a document ID into a couchbase server. Document Id is defined by the context, and document will be the HTTP body of the query.
Parameters
Param | Mandatory | Type | default | Description |
---|---|---|---|---|
path | yes | string | path used as client endpoint (must start with /) | |
resource | yes | string | resource id declared in the resource of your config profile | |
endpoint | yes | string | endpoint name declared in the resource module. In this case must be "create" | |
keyParam | no | string | id | param name containing the key received from the client |
docPrefix | no | string | a document prefix to use in conjuction with the received key |
Example
server:
endpoints:
- path: "/couchbase/:id"
method: POST
resource: couchbase-id
endpoint: create
Update endpoint
The purpose of this endpoint is to update a document into a couchbase server. Document Id is defined by the context, and document will be the HTTP body of the query.
Parameters
Param | Mandatory | Type | default | Description |
---|---|---|---|---|
path | yes | string | path used as client endpoint (must start with /) | |
resource | yes | string | resource id declared in the resource of your config profile | |
endpoint | yes | string | endpoint name declared in the resource module. In this case must be "update" | |
keyParam | no | string | id | param name containing the key received from the client |
docPrefix | no | string | a document prefix to use in conjuction with the received key |
Example
server:
endpoints:
- path: "/couchbase/:id"
method: PUT
resource: couchbase-id
endpoint: update
Delete endpoint
The purpose of this endpoint is to delete a document into a couchbase server. Document Id is defined by the context. by the context.
Parameters
Param | Mandatory | Type | default | Description |
---|---|---|---|---|
path | yes | string | path used as client endpoint (must start with /) | |
resource | yes | string | resource id declared in the resource of your config profile | |
endpoint | yes | string | endpoint name declared in the resource module. In this case must be "delete" | |
keyParam | no | string | id | param name containing the key received from the client |
docPrefix | no | string | a document prefix to use in conjuction with the received key |
Example
server:
endpoints:
- path: "/couchbase/:id"
method: DELETE
resource: couchbase-id
endpoint: delete