Update README and examples

couchbaselabs · Jul 24, 2024 · e76eced · e76eced
1 parent 296bea6
commit e76eced
Show file tree

Hide file tree

Showing 5 changed files with 261 additions and 31 deletions.
diff --git a/README.md b/README.md
@@ -5,4 +5,135 @@ Node.js client for [Couchbase](https://couchbase.com) Columnar
 
 # Installing the SDK<a id="installing-the-sdk"></a>
 
-See the [BUILDING page](https://github.com/couchbaselabs/columnar-nodejs-client/blob/main/BUILDING.md) for details on how to build the client's binary.
+Eventually the SDK will be published to npm, but in the interim a select set of packages with prebuilt binaries are available on the [Releases page](https://github.com/couchbaselabs/columnar-nodejs-client/releases).  If a packages is not available for your specific platform, see the [BUILDING page](https://github.com/couchbaselabs/columnar-nodejs-client/blob/main/BUILDING.md) for details on how to build the SDK's binary.
+
+To install the SDK from a wheel on the [Releases page](https://github.com/couchbaselabs/columnar-nodejs-client/releases):
+1. Download the appropriate package
+2. Unzip the downloaded file
+3. Install via npm: `npm install <path to unzipped wheel>`
+
+If a compatible package is not available, the SDK's binary will need to be built from source:
+1. Follow the steps on the [BUILDING page](https://github.com/couchbaselabs/columnar-nodejs-client/blob/main/BUILDING.md)
+2. After the build succeeds, the SDK can be used by running Node scripts from within the cloned repository or the SDK can be installed via pip: `npm install <path to cloned repository>`
+
+# Using the SDK<a id="using-the-sdk"></a>
+
+## CommonJS
+**Connecting and executing a query**
+```javascript
+const columnar = require('couchbase-columnar')
+
+async function main() {
+  // Update this to your cluster
+  const clusterConnStr = 'couchbases://--your-instance--'
+  const username = 'username'
+  const password = 'P@ssw0rd_12345!'
+  // User Input ends here.
+
+  const credential = new columnar.Credential(username, password)
+  const cluster = columnar.createInstance(clusterConnStr, credential, {
+    securityOptions: {
+      trustOnlyCertificates: columnar.Certificates.getNonprodCertificates(),
+    },
+  })
+
+  // Execute a streaming query with positional arguments.
+  let qs = 'SELECT * FROM `travel-sample`.inventory.airline LIMIT 10;'
+  let res = await cluster.executeQuery(qs)
+  for await (let row of res.rows()) {
+    console.log('Found row: ', row)
+  }
+  console.log('Metadata: ', res.metadata())
+
+  // Execute a streaming query with positional arguments.
+  qs =
+    'SELECT * FROM `travel-sample`.inventory.airline WHERE country=$1 LIMIT $2;'
+  res = await cluster.executeQuery(qs, { parameters: ['United States', 10] })
+  for await (let row of res.rows()) {
+    console.log('Found row: ', row)
+  }
+  console.log('Metadata: ', res.metadata())
+
+  // Execute a streaming query with named parameters.
+  qs =
+    'SELECT * FROM `travel-sample`.inventory.airline WHERE country=$country LIMIT $limit;'
+  res = await cluster.executeQuery(qs, {
+    parameters: { country: 'United States', limit: 10 },
+  })
+  for await (let row of res.rows()) {
+    console.log('Found row: ', row)
+  }
+  console.log('Metadata: ', res.metadata())
+}
+
+main()
+  .then(() => {
+    console.log('Finished.  Exiting app...')
+  })
+  .catch((err) => {
+    console.log('ERR: ', err)
+    console.log('Exiting app...')
+    process.exit(1)
+  })
+
+```
+
+## ES Modules
+**Connecting and executing a query**
+```javascript
+import { Certificates, Credential, createInstance } from "couchbase-columnar"
+
+async function main() {
+  // Update this to your cluster
+  const clusterConnStr = 'couchbases://--your-instance--'
+  const username = 'username'
+  const password = 'P@ssw0rd_12345!'
+  // User Input ends here.
+
+  const credential = new Credential(username, password)
+  const cluster = createInstance(clusterConnStr, credential, {
+    securityOptions: {
+      trustOnlyCertificates: Certificates.getNonprodCertificates(),
+    },
+  })
+
+  // Execute a streaming query with positional arguments.
+  let qs = "SELECT * FROM `travel-sample`.inventory.airline LIMIT 10;"
+  let res = await cluster.executeQuery(qs)
+  for await (let row of res.rows()) {
+    console.log("Found row: ", row)
+  }
+  console.log("Metadata: ", res.metadata())
+
+  // Execute a streaming query with positional arguments.
+  qs =
+    "SELECT * FROM `travel-sample`.inventory.airline WHERE country=$1 LIMIT $2;"
+  res = await cluster.executeQuery(qs, { parameters: ["United States", 10] })
+  for await (let row of res.rows()) {
+    console.log("Found row: ", row)
+  }
+  console.log("Metadata: ", res.metadata())
+
+  // Execute a streaming query with named parameters.
+  qs =
+    "SELECT * FROM `travel-sample`.inventory.airline WHERE country=$country LIMIT $limit;"
+  res = await cluster.executeQuery(qs, {
+    parameters: { country: "United States", limit: 10 },
+  })
+  for await (let row of res.rows()) {
+    console.log("Found row: ", row)
+  }
+  console.log("Metadata: ", res.metadata())
+}
+
+main()
+  .then(() => {
+    console.log("Finished.  Exiting app...")
+  })
+  .catch((err) => {
+    console.log("ERR: ", err)
+    console.log("Exiting app...")
+    process.exit(1)
+  })
+
+```
diff --git a/examples/query.cjs b/examples/query.cjs
@@ -9,11 +9,6 @@ async function main() {
 
   const credential = new columnar.Credential(username, password)
   const cluster = columnar.createInstance(clusterConnStr, credential, {
-    timeoutOptions: {
-      queryTimeout: 10000,
-      connectTimeout: 2000,
-      dispatchTimeout: 5000,
-    },
     securityOptions: {
       trustOnlyCertificates: columnar.Certificates.getNonprodCertificates(),
     },

diff --git a/examples/query.mjs b/examples/query.mjs
@@ -1,4 +1,4 @@
-import { Certificates, Credential, createInstance } from "couchbase-columnar";
+import { Certificates, Credential, createInstance } from "couchbase-columnar"
 
 async function main() {
   // Update this to your cluster
@@ -7,53 +7,48 @@ async function main() {
   const password = 'P@ssw0rd_12345!'
   // User Input ends here.
 
-  const credential = new Credential(username, password);
+  const credential = new Credential(username, password)
   const cluster = createInstance(clusterConnStr, credential, {
-    timeoutOptions: {
-      queryTimeout: 10000,
-      connectTimeout: 2000,
-      dispatchTimeout: 5000,
-    },
     securityOptions: {
       trustOnlyCertificates: Certificates.getNonprodCertificates(),
     },
-  });
+  })
 
   // Execute a streaming query with positional arguments.
-  let qs = "SELECT * FROM `travel-sample`.inventory.airline LIMIT 10;";
-  let res = await cluster.executeQuery(qs);
+  let qs = "SELECT * FROM `travel-sample`.inventory.airline LIMIT 10;"
+  let res = await cluster.executeQuery(qs)
   for await (let row of res.rows()) {
-    console.log("Found row: ", row);
+    console.log("Found row: ", row)
   }
-  console.log("Metadata: ", res.metadata());
+  console.log("Metadata: ", res.metadata())
 
   // Execute a streaming query with positional arguments.
   qs =
-    "SELECT * FROM `travel-sample`.inventory.airline WHERE country=$1 LIMIT $2;";
-  res = await cluster.executeQuery(qs, { parameters: ["United States", 10] });
+    "SELECT * FROM `travel-sample`.inventory.airline WHERE country=$1 LIMIT $2;"
+  res = await cluster.executeQuery(qs, { parameters: ["United States", 10] })
   for await (let row of res.rows()) {
-    console.log("Found row: ", row);
+    console.log("Found row: ", row)
   }
-  console.log("Metadata: ", res.metadata());
+  console.log("Metadata: ", res.metadata())
 
   // Execute a streaming query with named parameters.
   qs =
-    "SELECT * FROM `travel-sample`.inventory.airline WHERE country=$country LIMIT $limit;";
+    "SELECT * FROM `travel-sample`.inventory.airline WHERE country=$country LIMIT $limit;"
   res = await cluster.executeQuery(qs, {
     parameters: { country: "United States", limit: 10 },
-  });
+  })
   for await (let row of res.rows()) {
-    console.log("Found row: ", row);
+    console.log("Found row: ", row)
   }
-  console.log("Metadata: ", res.metadata());
+  console.log("Metadata: ", res.metadata())
 }
 
 main()
   .then(() => {
-    console.log("Finished.  Exiting app...");
+    console.log("Finished.  Exiting app...")
   })
   .catch((err) => {
-    console.log("ERR: ", err);
-    console.log("Exiting app...");
-    process.exit(1);
-  });
+    console.log("ERR: ", err)
+    console.log("Exiting app...")
+    process.exit(1)
+  })
diff --git a/examples/scopeQuery.cjs b/examples/scopeQuery.cjs
@@ -0,0 +1,55 @@
+const columnar = require("couchbase-columnar")
+
+async function main() {
+  // Update this to your cluster
+  const clusterConnStr = 'couchbases://--your-instance--'
+  const username = 'username'
+  const password = 'P@ssw0rd_12345!'
+  // User Input ends here.
+
+  const credential = new columnar.Credential(username, password)
+  const scope = columnar
+    .createInstance(clusterConnStr, credential, {
+      securityOptions: {
+        trustOnlyCertificates: columnar.Certificates.getNonprodCertificates(),
+      },
+    })
+    .database("travel-sample")
+    .scope("inventory")
+
+  // Execute a streaming query with positional arguments.
+  let qs = "SELECT * FROM airline LIMIT 10;"
+  let res = await scope.executeQuery(qs)
+  for await (let row of res.rows()) {
+    console.log("Found row: ", row)
+  }
+  console.log("Metadata: ", res.metadata())
+
+  // Execute a streaming query with positional arguments.
+  qs = "SELECT * FROM airline WHERE country=$1 LIMIT $2;"
+  res = await scope.executeQuery(qs, { parameters: ["United States", 10] })
+  for await (let row of res.rows()) {
+    console.log("Found row: ", row)
+  }
+  console.log("Metadata: ", res.metadata())
+
+  // Execute a streaming query with named parameters.
+  qs = "SELECT * FROM airline WHERE country=$country LIMIT $limit;"
+  res = await scope.executeQuery(qs, {
+    parameters: { country: "United States", limit: 10 },
+  })
+  for await (let row of res.rows()) {
+    console.log("Found row: ", row)
+  }
+  console.log("Metadata: ", res.metadata())
+}
+
+main()
+  .then(() => {
+    console.log("Finished.  Exiting app...")
+  })
+  .catch((err) => {
+    console.log("ERR: ", err)
+    console.log("Exiting app...")
+    process.exit(1)
+  })
diff --git a/examples/scopeQuery.mjs b/examples/scopeQuery.mjs
@@ -0,0 +1,54 @@
+import { Certificates, Credential, createInstance } from "couchbase-columnar"
+
+async function main() {
+  // Update this to your cluster
+  const clusterConnStr = 'couchbases://--your-instance--'
+  const username = 'username'
+  const password = 'P@ssw0rd_12345!'
+  // User Input ends here.
+
+  const credential = new Credential(username, password)
+  const scope = createInstance(clusterConnStr, credential, {
+    securityOptions: {
+      trustOnlyCertificates: Certificates.getNonprodCertificates(),
+    },
+  })
+    .database("travel-sample")
+    .scope("inventory")
+
+  // Execute a streaming query with positional arguments.
+  let qs = "SELECT * FROM airline LIMIT 10;"
+  let res = await scope.executeQuery(qs)
+  for await (let row of res.rows()) {
+    console.log("Found row: ", row)
+  }
+  console.log("Metadata: ", res.metadata())
+
+  // Execute a streaming query with positional arguments.
+  qs = "SELECT * FROM airline WHERE country=$1 LIMIT $2;"
+  res = await scope.executeQuery(qs, { parameters: ["United States", 10] })
+  for await (let row of res.rows()) {
+    console.log("Found row: ", row)
+  }
+  console.log("Metadata: ", res.metadata())
+
+  // Execute a streaming query with named parameters.
+  qs = "SELECT * FROM airline WHERE country=$country LIMIT $limit;"
+  res = await scope.executeQuery(qs, {
+    parameters: { country: "United States", limit: 10 },
+  })
+  for await (let row of res.rows()) {
+    console.log("Found row: ", row)
+  }
+  console.log("Metadata: ", res.metadata())
+}
+
+main()
+  .then(() => {
+    console.log("Finished.  Exiting app...")
+  })
+  .catch((err) => {
+    console.log("ERR: ", err)
+    console.log("Exiting app...")
+    process.exit(1)
+  })