First Steps with Kuzzle

It's time to play with the Kuzzle JS SDK. In this section, we will learn how to store a document and subscribe to notifications in Kuzzle using the Javascript SDK in a simple NodeJS client application.

Before proceeding, please make sure your system has these programs installed:

Prepare your environment

Create your playground directory and install the Javascript SDK from the command line using npm:

mkdir "kuzzle-playground"
cd "kuzzle-playground"
npm install kuzzle-sdk
If you are performing a clean install you might see some `UNMET PEER DEPENDENCY` warnings, these are safe to ignore as they refer to optional dependencies.

Then, create an init.js file and start by loading the Kuzzle Javascript SDK. Next, instantiate a client that automatically connects to Kuzzle via WebSocket. Replace 'kuzzle' with the corresponding server name or IP address:

const {
  Kuzzle,
  WebSocket
} = require('kuzzle-sdk');

const kuzzle = new Kuzzle(new WebSocket('kuzzle'));
Finally, we will add the code that will access Kuzzle to create a new index 'playground' and a new collection 'mycollection' that we will use to store data later on.

try {
  // Create a 'playground' index
  await kuzzle.index.create('playground');
  // Create a collection named 'mycollection' in playground index
  await kuzzle.collection.create(
    'playground',
    'mycollection'
  );
  console.log('playground/mycollection ready');
} catch (error) {
  console.error(error.message);
}

Your first-step.js file should now look like this:

// Load the Kuzzle SDK module
const {
  Kuzzle,
  WebSocket
} = require('kuzzle-sdk');
const kuzzle = new Kuzzle(new WebSocket('kuzzle'));
const run = async () => {
  try {
    await kuzzle.connect();
    // Create a 'playground' index
    await kuzzle.index.create('playground');
    // Create a collection named 'mycollection' in playground index
    await kuzzle.collection.create(
      'playground',
      'mycollection'
    );
    console.log('playground/mycollection ready');
  } catch (error) {
    console.error(error.message);
  } finally {
    kuzzle.disconnect();
  }
};
run();

This code does the following:

  • loads the Kuzzle SDK from its NPM package
  • creates an instance of the SDK and connects it to Kuzzle running on localhost (and selects the playground as default index),
  • creates the playground index,
  • creates the mycollection collection (within the playground index),
  • disconnects from Kuzzle after the collection is created or if an error occurs.

Run your file in Node.js

node first-step.js

Your console should output the following message:

playground/mycollection ready
Congratulations! You are now ready to say Hello to the World!
Having trouble? Get in touch with us on Gitter! We're happy to help.

Create your first "Hello World" document

Create a create.js file with the following code:

// load the Kuzzle SDK module
const {
  Kuzzle,
  WebSocket
} = require('kuzzle-sdk');
const kuzzle = new Kuzzle(new WebSocket('kuzzle'));
const message = {message: 'Hello, World!'};
const run = async () => {
  try {
    await kuzzle.connect();
    await kuzzle.document.create(
      'playground',
      'mycollection',
      message
    );
    console.log('document created');
  } catch (error) {
    console.error(error.message);
  } finally {
    kuzzle.disconnect();
  }
};
run();

This code does the following:

  • creates a new document containing the message "Hello, World" in mycollection within the playground index,
  • logs a success message to the console if everything went fine,
  • logs an error message if any of the previous actions failed,
  • disconnects from Kuzzle after the document is created or if an error occurs.

Run your file in Node.js

node create.js

Your console should show the following message:

document created
You have now successfully stored your first document into Kuzzle. Click here to see how you can use the Kuzzle Admin Console to browse your collection and confirm that your document was saved.
Having trouble? Get in touch with us on Gitter! We're happy to help.

You can find more resources about Kuzzle SDK in the SDK Reference.

Subscribe to data changes (pub/sub)

Kuzzle provides pub/sub features that can be used to trigger real-time notifications based on the state of your data (for a deep-dive on notifications check out the Room class definition in the SDK Reference).

Let's get started. Complete your create.js file:

// Load the Kuzzle SDK module
const {
  Kuzzle,
  WebSocket
} = require('kuzzle-sdk');
const kuzzle = new Kuzzle(new WebSocket('kuzzle'));
const message = {message: 'Hello, World!'};
// Define a filter
const filter = {exists: {field: 'message'}};
// Will be called each time a document match the filter
const callback = notifications => {
  console.log(
    'message received from kuzzle',
    notifications.result._source.message
  );
};
const run = async () => {
  try {
    await kuzzle.connect();
    // Create a subscription on the collection matching given filters
    await kuzzle.realtime.subscribe(
      'playground',
      'mycollection',
      filter,
      callback
    );
    await kuzzle.document.create(
      'playground',
      'mycollection',
      message
    );
  } catch (error) {
    console.error(error.message);
  } finally {
    kuzzle.disconnect();
  }
};
run();

Run your file in Node.js

node create.js

This creates a new document in Kuzzle, triggering a notification:

subscribe ok
document created
message received from kuzzle: Hello, World!
Congratulations! You have just choreographed your first pub/sub pattern!
Having trouble? Get in touch with us on Gitter! We're happy to help.

Where do we go from here?

Now that you're more familiar with Kuzzle, dive even deeper to learn how to leverage its full capabilities: