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 :

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

Extract the archive :

$ 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 :

$ export KUZZLE_SDK_PATH=$PWD/kuzzle-cpp-sdk

First connection #

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

#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 :

$ 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 :

#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 :

$ 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 :

#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 :

$ 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

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

#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:

$ 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:

discover what this SDK has to offer by browsing other sections of this documentation
learn how to use Koncorde to create incredibly fine-grained and blazing-fast subscriptions
follow our guide to learn how to perform basic authentication
follow our guide to learn how to manage users and how to set up fine-grained access control

Edit this page on Github