@ibm-cloud/cloudant
Advanced tools
IBM Cloudant Node.js SDK is a client library that interacts with the IBM Cloudant APIs.
Disclaimer: This library is still a 0.x release. We do consider this library production-ready and capable, but there are still some limitations we’re working to resolve, and refinements we want to deliver. We are working really hard to minimise the disruption from now until the 1.0 release, but there may still be some changes that impact applications using this SDK. For now, be sure to pin versions to avoid surprises.
The IBM Cloudant Node.js SDK allows developers to programmatically
interact with IBM Cloudant
with the help of the @ibm-cloud/cloudant package.
The purpose of this Node.js SDK is to wrap most of the HTTP request APIs provided by Cloudant and supply other functions to ease the usage of Cloudant. This SDK should make life easier for programmers to do what’s really important to them: developing software.
Reasons why you should consider using Cloudant Node.js SDK in your project:
Promise based design with asynchronous HTTP requests.npm install @ibm-cloud/cloudant
This library requires some of your Cloudant service credentials to authenticate with your account.
IAM, COUCHDB_SESSION, BASIC or NOAUTH authentication type.
apikey instead of a
user-given password. You can create one
here.COUCHDB_SESSION) authentication
is recommended for Apache CouchDB or for
Cloudant when IAM is unavailable. It exchanges username
and password credentials for an AuthSession cookie from the /_session
endpoint.username and password credentials.url.There are several ways to set these properties:
For Cloudant IAM authentication, set the following environmental variables by
replacing the <url> and <apikey> with your proper
service credentials. There is no need to set
CLOUDANT_AUTH_TYPE to IAM because it is the default.
CLOUDANT_URL=<url>
CLOUDANT_APIKEY=<apikey>
For COUCHDB_SESSION authentication, set the following environmental variables
by replacing the <url>, <username> and <password> with your proper
service credentials.
CLOUDANT_AUTH_TYPE=COUCHDB_SESSION
CLOUDANT_URL=<url>
CLOUDANT_USERNAME=<username>
CLOUDANT_PASSWORD=<password>
For Basic authentication, set the following environmental variables by
replacing the <url>, <username> and <password> with your proper
service credentials.
CLOUDANT_AUTH_TYPE=BASIC
CLOUDANT_URL=<url>
CLOUDANT_USERNAME=<username>
CLOUDANT_PASSWORD=<password>
Note: We recommend that you use IAM for Cloudant and Session for CouchDB authentication.
To use an external configuration file, the Cloudant API docs, or the general SDK usage information will guide you.
To learn more about how to use programmatic authentication, see the related documentation in the Cloudant API docs or in the Node.js SDK Core document about authentication.
For fundamental SDK usage information and config options, please see the common IBM Cloud SDK documentation.
No request timeout is defined, but a 2.5m connect and 2.5m read timeout is set by default. Be sure to set a request timeout appropriate to your application usage and environment. The request timeout section contains details on how to change the value.
Note: System settings may take precedence over configured timeout values.
The following code examples authenticate with the environment variables.
Note: This example code assumes that animaldb database does not exist in your account.
This example code gathers information about an existing database hosted on
the https://examples.cloudant.com/ service url. To connect, you must
extend your environment variables with the service url and authentication
type to use NOAUTH authentication while you connect to the animaldb database.
This step is necessary for the SDK to distinguish the EXAMPLES custom service
name from the default service name which is CLOUDANT.
Cloudant environment variable naming starts with a service name prefix that identifies your service.
By default this is CLOUDANT, see the settings in the
authentication with environment variables section.
If you would like to rename your Cloudant service from CLOUDANT,
you must use your defined service name as the prefix for all Cloudant related environment variables.
The code block below provides an example of instantiating a user-defined EXAMPLES service name.
EXAMPLES_URL=https://examples.cloudant.com
EXAMPLES_AUTH_TYPE=NOAUTH
Once the environment variables are set, you can try out the code examples.
import {CloudantV1} from "@ibm-cloud/cloudant";
// 1. Create a Cloudant client with "EXAMPLES" service name =====================
const client = CloudantV1.newInstance({ serviceName: 'EXAMPLES' });
// 2. Get server information ====================================================
// call service without parameters:
client.getServerInformation().then((serverInformation) => {
const { version } = serverInformation.result;
console.log(`Server version ${version}`);
});
// 3. Get database information for "animaldb" ===================================
const dbName = 'animaldb';
// call service with embedded parameters:
client.getDatabaseInformation({ db: dbName }).then((dbInfo) => {
const documentCount = dbInfo.result.doc_count;
const dbNameResult = dbInfo.result.db_name;
// 4. Show document count in database =========================================
console.log(
`Document count in "${dbNameResult}" database is ${documentCount}.`
);
});
// 5. Get zebra document out of the database by document id =====================
const getDocParams: CloudantV1.GetDocumentParams = {
db: dbName,
docId: 'zebra',
};
// call service with predefined parameters:
client.getDocument(getDocParams).then((documentAboutZebra) => {
// result object is defined as a Document here:
const { result } = documentAboutZebra;
console.log(
`Document retrieved from database:\n${JSON.stringify(result, null, 2)}`
);
});
const { CloudantV1 } = require('@ibm-cloud/cloudant');
const getInfoFromExistingDatabase = async () => {
// 1. Create a Cloudant client with "EXAMPLES" service name ===================
const client = CloudantV1.newInstance({ serviceName: 'EXAMPLES' });
// 2. Get server information ==================================================
// call service without parameters:
const { version } = (await client.getServerInformation()).result;
console.log(`Server version ${version}`);
// 3. Get database information for "animaldb" =================================
const dbName = 'animaldb';
// call service with embedded parameters:
const dbInfo = await client.getDatabaseInformation({ db: dbName });
const documentCount = dbInfo.result.doc_count;
const dbNameResult = dbInfo.result.db_name;
// 4. Show document count in database =========================================
console.log(
`Document count in "${dbNameResult}" database is ${documentCount}.`
);
// 5. Get zebra document out of the database by document id ===================
const getDocParams = { db: dbName, docId: 'zebra' };
// call service with predefined parameters:
const documentAboutZebra = await client.getDocument(getDocParams);
// result object is defined as a Document here:
const { result } = documentAboutZebra;
console.log(
`Document retrieved from database:\n${JSON.stringify(result, null, 2)}`
);
};
if (require.main === module) {
getInfoFromExistingDatabase();
}
When you run the code, you see a result similar to the following output.
Server version 2.1.1
Document count in "animaldb" database is 11.
Document retrieved from database:
{
"_id": "zebra",
"_rev": "3-750dac460a6cc41e6999f8943b8e603e",
"wiki_page": "http://en.wikipedia.org/wiki/Plains_zebra",
"min_length": 2,
"max_length": 2.5,
"min_weight": 175,
"max_weight": 387,
"class": "mammal",
"diet": "herbivore"
}
Note: This example code assumes that orders database does not exist in your account.
Now comes the exciting part, you create your own orders database and add a document about Bob Smith with your own IAM or
Basic service credentials.
import {CloudantV1} from "@ibm-cloud/cloudant";
interface OrderDocument extends CloudantV1.Document {
name?: string;
joined?: string;
_id: string;
_rev?: string;
}
// 1. Create a client with `CLOUDANT` default service name ======================
const client = CloudantV1.newInstance({});
// 2. Create a database =========================================================
const exampleDbName = 'orders';
// Try to create database if it doesn't exist
const createDb = client
.putDatabase({ db: exampleDbName })
.then((putDatabaseResult) => {
if (putDatabaseResult.result.ok) {
console.log(`"${exampleDbName}" database created."`);
}
})
.catch((err) => {
if (err.code === 412) {
console.log(
`Cannot create "${exampleDbName}" database, it already exists.`
);
}
});
// 3. Create a document =========================================================
// Create a document object with "example" id
const exampleDocId = 'example';
// Setting `_id` for the document is optional when postDocument function is used for CREATE.
// When `_id` is not provided the server will generate one for your document.
const exampleDocument: OrderDocument = { _id: exampleDocId };
// Add "name" and "joined" fields to the document
exampleDocument.name = 'Bob Smith';
exampleDocument.joined = '2019-01-24T10:42:59.000Z';
// Save the document in the database with "postDocument" function
createDb.then(() => {
client
.postDocument({
db: exampleDbName,
document: exampleDocument,
})
// ==========================================================================
// Note: saving the document can also be done with the "putDocument"
// function. In this case `docId` is required for a CREATE operation:
/*
.putDocument({
db: exampleDbName,
docId: exampleDocId,
document: exampleDocument,
})
*/
// ==========================================================================
.then((createDocumentResponse) => {
// Keeping track of the revision number of the document object
// is necessary for further UPDATE/DELETE operations:
exampleDocument._rev = createDocumentResponse.result.rev;
console.log(
'You have created the document:\n' +
JSON.stringify(exampleDocument, null, 2)
);
});
});
const { CloudantV1 } = require('@ibm-cloud/cloudant');
const createDbAndDoc = async () => {
// 1. Create a client with `CLOUDANT` default service name ====================
const client = CloudantV1.newInstance({});
// 2. Create a database =======================================================
const exampleDbName = 'orders';
// Try to create database if it doesn't exist
try {
const putDatabaseResult = (
await client.putDatabase({
db: exampleDbName,
})
).result;
if (putDatabaseResult.ok) {
console.log(`"${exampleDbName}" database created.`);
}
} catch (err) {
if (err.code === 412) {
console.log(
`Cannot create "${exampleDbName}" database, it already exists.`
);
}
}
// 3. Create a document =======================================================
// Create a document object with "example" id
const exampleDocId = 'example';
// Setting `_id` for the document is optional when "postDocument" function is used for CREATE.
// When `_id` is not provided the server will generate one for your document.
const exampleDocument = { _id: exampleDocId };
// Add "name" and "joined" fields to the document
exampleDocument['name'] = 'Bob Smith';
exampleDocument.joined = '2019-01-24T10:42:59.000Z';
// Save the document in the database with "postDocument" function
const createDocumentResponse = await client.postDocument({
db: exampleDbName,
document: exampleDocument,
});
// ==========================================================================
// Note: saving the document can also be done with the "putDocument"
// function. In this case `docId` is required for a CREATE operation:
/* const createDocumentResponse = await client.putDocument({
db: exampleDbName,
docId: exampleDocId,
document: exampleDocument,
}); */
// ==========================================================================
// Keeping track of the revision number of the document object
// is necessary for further UPDATE/DELETE operations:
exampleDocument._rev = createDocumentResponse.result.rev;
console.log(
'You have created the document:\n' +
JSON.stringify(exampleDocument, null, 2)
);
};
if (require.main === module) {
createDbAndDoc();
}
"orders" database created.
You have created the document:
{
"_id": "example",
"name": "Bob Smith",
"joined": "2019-01-24T10:42:59.000Z",
"_rev": "1-1b403633540686aa32d013fda9041a5d"
}
Note: This example code assumes that you have created both the orders
database and the example document by
running the previous example code
successfully. Otherwise, the following error message occurs, "Cannot update document because either 'orders'
database or 'example' document was not found."
import {CloudantV1} from "@ibm-cloud/cloudant";
interface OrderDocument extends CloudantV1.Document {
address?: string;
joined?: string;
_id?: string;
_rev?: string;
}
// 1. Create a client with `CLOUDANT` default service name ======================
const client = CloudantV1.newInstance({});
// 2. Update the document =======================================================
// Set the options to get the document out of the database if it exists
const exampleDbName = 'orders';
// Try to get the document if it previously existed in the database
const getDocParams: CloudantV1.GetDocumentParams = {
docId: 'example',
db: exampleDbName,
};
// ==============================================================================
// Note : for response byte stream use:
/*
const getdocAsStreamParam: CloudantV1.GetDocumentAsStreamParams = {
docId: 'example',
db: exampleDbName,
};
client
.getDocumentAsStream(getdocAsStreamParam)
.then((documentAsByteStream) => {...});
*/
// ==============================================================================
client
.getDocument(getDocParams)
.then((docResult) => {
// using OrderDocument on getDocument result:
const document: OrderDocument = docResult.result;
// Add Bob Smith's address to the document
document.address = '19 Front Street, Darlington, DL5 1TY';
// Remove the joined property from document object
delete document.joined;
// Update the document in the database
client
.postDocument({ db: exampleDbName, document })
// ========================================================================
// Note 1: for request byte stream use:
// .postDocument(
// {db: exampleDbName, document: documentAsByteStream}
// )
// ========================================================================
// ========================================================================
// Note 2: updating the document can also be done with the "putDocument" function.
// `docId` and `rev` are required for an UPDATE operation,
// but `rev` can be provided in the document object as `_rev` too:
/*
.putDocument({
db: exampleDbName,
docId: document._id, // docId is a required parameter
rev: document._rev,
document, // _rev in the document object CAN replace above `rev` parameter
})
*/
// ========================================================================
.then((res) => {
// Keeping track of the latest revision number of the document object
// is necessary for further UPDATE/DELETE operations:
document._rev = res.result.rev;
console.log(
`You have updated the document:\n${JSON.stringify(document, null, 2)}`
);
});
})
.catch((err) => {
if (err.code === 404) {
console.log(
`Cannot update document because either "${exampleDbName}" database or the "example" ` +
`document was not found.`
);
}
});
const { CloudantV1 } = require('@ibm-cloud/cloudant');
const updateDoc = async () => {
// 1. Create a client with `CLOUDANT` default service name ====================
const client = CloudantV1.newInstance({});
// 2. Update the document =====================================================
// Set the options to get the document out of the database if it exists
const exampleDbName = 'orders';
// Try to get the document if it previously existed in the database
try {
const document = (
await client.getDocument({
docId: 'example',
db: exampleDbName,
})
).result;
// ==========================================================================
// Note: for response byte stream use:
/*
const documentAsByteStream = (
await client.getDocumentAsStream({
docId: 'example',
db: exampleDbName,
})
).result;
*/
// ==========================================================================
// Add Bob Smith's address to the document
document.address = '19 Front Street, Darlington, DL5 1TY';
// Remove the joined property from document object
delete document['joined'];
// Keeping track of the latest revision number of the document object
// is necessary for further UPDATE/DELETE operations:
document._rev = (
await client.postDocument({
db: exampleDbName,
document, // _id and _rev MUST be inside the document object
})
).result.rev;
// ==========================================================================
// Note 1: for request byte stream use:
/*
document._rev = (
await client.postDocument({
db: exampleDbName,
document: documentAsByteStream,
})
).result.rev;
*/
// ==========================================================================
// ==========================================================================
// Note 2: updating the document can also be done with the "putDocument" function.
// `docId` and `rev` are required for an UPDATE operation,
// but `rev` can be provided in the document object as `_rev` too:
/*
document._rev = (
await client.putDocument({
db: exampleDbName,
docId: document._id, // docId is a required parameter
rev: document._rev,
document // _rev in the document object CAN replace above `rev` parameter
})
).result.rev;
*/
// ==========================================================================
console.log(
`You have updated the document:\n${JSON.stringify(document, null, 2)}`
);
} catch (err) {
if (err.code === 404) {
console.log(
`Cannot update document because either "${exampleDbName}" database or the "example" ` +
`document was not found.`
);
}
}
};
if (require.main === module) {
updateDoc();
}
You have updated the document:
{
"_id": "example",
"_rev": "2-4e2178e85cffb32d38ba4e451f6ca376",
"name": "Bob Smith",
"address": "19 Front Street, Darlington, DL5 1TY"
}
Note: This example code assumes that you have created both the orders
database and the example document by
running the previous example code
successfully. Otherwise, the following error message occurs, "Cannot delete document because either 'orders'
database or 'example' document was not found."
import {CloudantV1} from "@ibm-cloud/cloudant";
interface OrderDocument extends CloudantV1.Document {
name?: string;
address?: string;
joined?: string;
_id?: string;
_rev?: string;
}
// 1. Create a client with `CLOUDANT` default service name ======================
const client = CloudantV1.newInstance({});
// 2. Delete the document =======================================================
// Set the options to get the document out of the database if it exists
const exampleDbName = 'orders';
const exampleDocId = 'example';
// Try to get the document if it previously existed in the database
const getDocParams: CloudantV1.GetDocumentParams = {
docId: exampleDocId,
db: exampleDbName,
};
client
.getDocument(getDocParams)
.then((docResult) => {
const document: OrderDocument = docResult.result;
client
.deleteDocument({
db: exampleDbName,
docId: document._id, // `docId` is required for DELETE
rev: document._rev, // `rev` is required for DELETE
})
.then(() => {
console.log('You have deleted the document.');
});
})
.catch((err) => {
if (err.code === 404) {
console.log(
`Cannot delete document because either "${exampleDbName}" database or the "example" ` +
`document was not found.`
);
}
});
const { CloudantV1 } = require('@ibm-cloud/cloudant');
const deleteDoc = async () => {
// 1. Create a client with `CLOUDANT` default service name ====================
const client = CloudantV1.newInstance({});
// 2. Delete the document =====================================================
// Set the options to get the document out of the database if it exists
const exampleDbName = 'orders';
const exampleDocId = 'example';
// Try to get the document if it previously existed in the database
try {
const document = (
await client.getDocument({
docId: exampleDocId,
db: exampleDbName,
})
).result;
await client.deleteDocument({
db: exampleDbName,
docId: document._id, // `docId` is required for DELETE
rev: document._rev, // `rev` is required for DELETE
});
console.log('You have deleted the document.');
} catch (err) {
if (err.code === 404) {
console.log(
`Cannot delete document because either "${exampleDbName}" database or the "example" ` +
`document was not found.`
);
}
}
};
if (require.main === module) {
deleteDoc();
}
You have deleted the document.
For sample code on handling errors, see Cloudant API docs.
For endpoints that read or write document content it is possible to bypass usage of the built-in interface with byte streams.
Depending on the specific SDK operation it may be possible to:
Request byte stream can be supplied for NodeJS.ReadableStream or Buffer type parameters
.
For these cases you can pass this byte stream directly to the HTTP request body.
Response byte stream is supported in functions with the suffix of AsStream.
The returned byte stream allows the response body to be consumed
without triggering JSON unmarshalling that is typically performed by the SDK.
The update document section contains examples for both request and response byte stream cases.
The API reference contains further examples of using byte streams. They are titled "Example request as stream" and are initially collapsed. Expand them to see examples of:
Byte requests:
Byte responses:
If you are having difficulties using this SDK or have a question about the IBM Cloud services, ask a question on Stack Overflow.
If you encounter an issue with the project, you are welcome to submit a bug report. Before you submit a bug report, search for similar issues and review the KNOWN_ISSUES file to verify that your issue hasn't been reported yet.
Find more open source projects on the IBM Github page.
For more information, see CONTRIBUTING.
This SDK is released under the Apache 2.0 license. To read the full text of the license, see LICENSE.
FAQs
IBM Cloudant Node.js SDK
The npm package @ibm-cloud/cloudant receives a total of 15,480 weekly downloads. As such, @ibm-cloud/cloudant popularity was classified as popular.
We found that @ibm-cloud/cloudant demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Michigan TypeScript founder Dmitri Mitropoulos implements WebAssembly runtime in TypeScript types, enabling Doom to run after processing 177 terabytes of type definitions.
Security News
vlt's new "reproduce" tool verifies npm packages against their source code, outperforming traditional provenance adoption in the JavaScript ecosystem.
Research
Security News
Socket researchers uncovered a malicious PyPI package exploiting Deezer’s API to enable coordinated music piracy through API abuse and C2 server control.