Getting Started

In this tutorial you will learn how to install and use the Kuzzle C++ SDK.

You will learn :

  • how to connect to your Kuzzle Server instance
  • how to create an index and a collection
  • how to store documents
  • how to to subcribe to real-time notifications

Before proceeding, please make sure your system meets the following requirements :

  • A C++ compiler that supports C++ 11 sush as: gcc version 4.5 or higher
  • A running instance of Kuzzle Server (Kuzzle installation guide)

Having trouble? Get in touch with us on Gitter!

Installation

Go to https://dl.kuzzle.io/sdk/cpp/1-dev and download the archive corresponding to your target artchitecture.

For amd64 linux :

Copied to clipboard!
$ curl https://dl.kuzzle.io/sdk/cpp/1-dev/kuzzlesdk-cpp-experimental-amd64.tar.gz

Extract the archive :

Copied to clipboard!
$ tar xf kuzzlesdk-cpp-experimental-amd64.tar.gz

To make building the sample application in the following step easier, we'll export the path to the Kuzzle C++ SDK to KUZZLE_SDK_PATH environnement variable :

Copied to clipboard!
$ export KUZZLE_SDK_PATH=$PWD/kuzzle-cpp-sdk

First connection

Create a my-first-kuzzle-app.cpp file and with the following source code :

Copied to clipboard!
#include <iostream>

#include "websocket.hpp"
#include "kuzzle.hpp"

int main(int argc, char * argv[]) {
  // Instantiate a Kuzzle client with a WebSocket connection.
  // Replace "kuzzle" with your actual Kuzzle hostname (e.g. "localhost")
  kuzzleio::WebSocket * ws = new kuzzleio::WebSocket("kuzzle");
  kuzzleio::Kuzzle *kuzzle = new kuzzleio::Kuzzle(ws);

  try {
    // Connect to the server.
    kuzzle->connect();
    std::cout << "Connected!" << std::endl;
  }
  catch(kuzzleio::KuzzleException &e) {
    std::cerr << e.what() << std::endl;
    exit(1);
  }

  try {
    // Get the server current date as a UNIX timestamp.
    std::cout << "Server current timestamp: "
    << kuzzle->server->now()
    << std::endl;
  }
  catch(kuzzleio::KuzzleException &e) {
    std::cerr << e.what() << std::endl;
    kuzzle->disconnect();
    exit(1);
  }

  // Disconnect and free resources
  kuzzle->disconnect();
  delete kuzzle;
  delete ws;

  return 0;
}

Build and run :

Copied to clipboard!
$ g++ -o my-first-kuzzle-app my-first-kuzzle-app.cpp -I${KUZZLE_SDK_PATH}/include -L${KUZZLE_SDK_PATH}/lib -lkuzzlesdk -lpthread -Wl,-rpath=${KUZZLE_SDK_PATH}/lib
$ ./my-first-kuzzle-app
Connected!
Server current timestamp: 1549298495451

Create data structure

Now we'll learn how to nitializes the Kuzzle Server storage by creating an index, and a collection inside it using Kuzzle C++ SDK

Update my-first-kuzzle-app.cpp with the following content :

Copied to clipboard!
#include <iostream>
#include "kuzzle.hpp"
#include "websocket.hpp"

int main(int argc, char * argv[]) {
  // Instantiate a Kuzzle client with a WebSocket connection.
  // Replace "kuzzle" with your actual Kuzzle hostname (e.g. "localhost")
  kuzzleio::WebSocket *ws = new kuzzleio::WebSocket("kuzzle");
  kuzzleio::Kuzzle *kuzzle = new kuzzleio::Kuzzle(ws);

  try {
    // Connect to the server.
    kuzzle->connect();
    std::cout << "Connected!" << std::endl;

  // Freshly installed Kuzzle servers are empty: we first need to create
  // a index. The one used in this example is named "nyc-open-data"
  kuzzle->index->create("nyc-open-data");
  std::cout << "Index nyc-open-data created!" << std::endl;

    // Create a collection named "yellow-taxi" in our newly created index
    kuzzle->collection->create("nyc-open-data", "yellow-taxi");
    std::cout << "Collection yellow-taxi created!" << std::endl;
  }
  catch(kuzzleio::KuzzleException e) {
    std::cerr << e.what() << std::endl;
    exit(1);
  }

  // Disconnect and free allocated resources
  kuzzle->disconnect();

  delete kuzzle;
  delete ws;

  return 0;
}

Build and execute the program with the following commands :

Copied to clipboard!
$ g++ -o my-first-kuzzle-app my-first-kuzzle-app.cpp -I${KUZZLE_SDK_PATH}/include -L${KUZZLE_SDK_PATH}/lib -lkuzzlesdk -lpthread
$ LD_LIBRARY_PATH=${KUZZLE_SDK_PATH}/lib/ ./my-first-kuzzle-app
Connected to Kuzzle Server
Index nyc-open-data created!
Collection yellow-taxi created!

Create your first document

Now that you successfully connected to your Kuzzle server with the Go SDK, and created an index and a collection, it's time to manipulate data.

Here is how Kuzzle storage is structured :

  • indexes contain collections
  • collections contain documents

We will create a document in nyc-open-data/yellow-taxi

Create a create-document.cpp file with the following source code :

Copied to clipboard!
#include <iostream>
#include "kuzzle.hpp"
#include "websocket.hpp"

int main(int argc, char * argv[]) {
  // Instantiate a Kuzzle client with a WebSocket connection.
  // Replace "kuzzle" with your actual Kuzzle hostname (e.g. "localhost")
  kuzzleio::WebSocket *ws = new kuzzleio::WebSocket("kuzzle");
  kuzzleio::Kuzzle *kuzzle = new kuzzleio::Kuzzle(ws);

  try {
    // Connect to the server.
    kuzzle->connect();
    std::cout << "Connected!" << std::endl;
  }
  catch(kuzzleio::KuzzleException &e) {
    std::cerr << e.what() << std::endl;
    exit(1);
  }

  // New document content
  std::string document = R"(
    {
      "name": "Sirkis",
      "birthday": "1959-06-22",
      "license": "B"
    }
  )";

  try {
    // Store the document in the "yellow-taxi" collection, itself in the
    // "nyc-open-data" index
    std::string response = kuzzle->document->create(
      "nyc-open-data",
      "yellow-taxi",
      "document-id",
      document);
    std::cout << "Document created successfully: " << response << std::endl;
  }
  catch(kuzzleio::KuzzleException &e) {
    std::cerr << e.what() << std::endl;
    exit(1);
  }

  // Disconnect and free allocated resources
  kuzzle->disconnect();

  delete kuzzle;
  delete ws;

  return 0;
}

Build and run :

Copied to clipboard!
$ g++ -o create-document create-document.cpp -I${KUZZLE_SDK_PATH}/include -L${KUZZLE_SDK_PATH}/lib -lkuzzlesdk -lpthread
$ LD_LIBRARY_PATH=${KUZZLE_SDK_PATH}/lib/ ./create-document
Connected to Kuzzle Server
Document created successfuly
{"_index":"nyc-open-data","_type":"yellow-taxi","_id":"AWesW0cJYEmXIw2Bonx4","_version":1,"result":"created","_shards":{"total":2,"successful":1,"failed":0},"created":true,"_source":{"birthday":"1959-06-22","license":"B","name":"Sirkis","_kuzzle_info":{"author":"-1","createdAt":1544784922373,"updatedAt":null,"updater":null,"active":true,"deletedAt":null}},"_meta":{"author":"-1","createdAt":1544784922373,"updatedAt":null,"updater":null,"active":true,"deletedAt":null}}

You can perform other actions such as delete, replace or search documents. There are also other ways to interact with Kuzzle like our Admin Console, the Kuzzle HTTP API or by using your own protocol.

Now you know how to:

  • Store documents in a Kuzzle server, and access those

Subscribe to realtime document notifications (pub/sub)

Time to use realtime with Kuzzle. Create a new file realtime.cpp with the following code:

Copied to clipboard!
#include <unistd.h>
#include <iostream>
#include <memory>
#include "websocket.hpp"
#include "kuzzle.hpp"

int main(int argc, char * argv[]) {
  // Instantiate a Kuzzle client with a WebSocket connection.
  // Replace "kuzzle" with your actual Kuzzle hostname (e.g. "localhost")
  kuzzleio::WebSocket *ws = new kuzzleio::WebSocket("kuzzle");
  kuzzleio::Kuzzle *kuzzle = new kuzzleio::Kuzzle(ws);

  try {
    // Connect to the server.
    kuzzle->connect();
    std::cout << "Connected!" << std::endl;
  }
  catch(kuzzleio::KuzzleException &e) {
    std::cerr << e.what() << std::endl;
    exit(1);
  }

  // For the sake of this example only: a simple toggle that is set
  // to true once a notification is received. This allows us to wait
  // before exiting the program
  bool notified = false;

  // Create a lambda that will be invoked for each real-time notification
  // received
  kuzzleio::NotificationListener listener =
    [&](const std::shared_ptr<kuzzleio::notification_result> &notification) {
      std::string id = notification->result->id;
      std::cout << "New created document notification: " << id << std::endl;
      notified = true;
    };

  try {
    // Subscribe to notifications for drivers having a "B" driver license.
    std::string filters = R"(
      {
        "equals": {
          "license": "B"
        }
      }
    )";

  kuzzle->realtime->subscribe(
    "nyc-open-data",
    "yellow-taxi",
    filters,
    &listener);
  std::cout << "Successfully subscribed!" << std::endl;

  // Write a new document. This triggers a notification
  // sent to our subscription.
  std::string document = R"(
    {
      "name": "John",
      "birthday": "1995-11-27",
      "license": "B"
    }
  )";

  kuzzle->document->create(
    "nyc-open-data",
    "yellow-taxi",
    "some-id",
    document);
  } catch (kuzzleio::KuzzleException &e) {
    std::cerr << e.what() << std::endl;
    kuzzle->disconnect();
    exit(1);
  }

  // Waiting for a notification before exiting
  for (unsigned i = 0; i < 10 && !notified; ++i) {
    sleep(2);
  }

  // Disconnect and free allocated resources, allowing the
  // program to exit at the first notification received
  kuzzle->disconnect();

  delete kuzzle;
  delete ws;

  return 0;
}

This program subscribes to changes made to documents with a license field set to B, within the yellow-taxi collection. Whenever a document matching the provided filters changes, a new notification is received from Kuzzle. Run your program:

Copied to clipboard!
$ g++ -o realtime realtime.cpp -I${KUZZLE_SDK_PATH}/include -L${KUZZLE_SDK_PATH}/lib -lkuzzlesdk -lpthread
$ LD_LIBRARY_PATH=${KUZZLE_SDK_PATH}/lib/ ./realtime
Connected!
Successfully subscribing!
New document added to yellow-taxi collection!
Driver John born on 1995-11-27 got a B license.

Now, you know how to:

  • Create realtime filters
  • Subscribe to notifications

Where do we go from here?

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