C++ elasticlient
C++ elasticlient library is simple library for simplified work with Elasticsearch in C++. The library is based on C++ Requests: Curl for People.
Features
- Elasticsearch client which work with unlimited nodes in one Elasticsearch cluster. If any node is dead it tries another one.
- Elasticsearch client supports search, index, get, remove methods by default.
- Posibility to perform not implemented method i.e multi GET or indices creation.
- Support for Bulk API requests.
- Support for Scroll API.
Dependencies
- C++ Requests: Curl for People
- JsonCpp
- Google Test
- Only for tests: C++ HTTP mock server library
Requirements
- C++11 compatible compiler such as GCC (tested with version 4.9.2)
- CMake (tested with version 3.5.2)
Building and testing on Unix like system
Step 1
Clone or download this repository to some directory and go to this directory.
git clone https://github.com/seznam/elasticlient
cd elasticlient
Step 2
Now if you want to use all above mentioned dependencies from system, you can skip this step.
git submodule update --init --recursive
Step 3
Build the library:
mkdir build
cd build
cmake ..
make
make test # Optional, will run elasticlient tests
Following CMake configuration variables may be passed right before ..
in cmake ..
command.
-DUSE_ALL_SYSTEM_LIBS=YES
- use all dependencies from system (default=NO)-DUSE_SYSTEM_CPR=YES
- use C++ Requests library from system (default=NO)-DUSE_SYSTEM_JSONCPP=YES
- use JsonCpp library from system (default=NO)-DUSE_SYSTEM_GTEST=YES
- use Google Test library from system (default=NO)-DUSE_SYSTEM_HTTPMOCKSERVER=YES
- use C++ HTTP mock server library from system (default=NO)-DBUILD_ELASTICLIENT_TESTS=YES
- build elasticlient library tests (default=YES)-DBUILD_ELASTICLIENT_EXAMPLE=YES
- build elasticlient library example hello-world program (default=YES)-DBUILD_SHARED_LIBS=YES
- build as a shared library (default=YES)
How to use
Basic Hello world example
If you build the library with -DBUILD_ELASTICLIENT_EXAMPLE=YES
you can find compiled binary
(hello-world) of this example in build/bin
directory.
This example will at first index the document into elasticsearch cluster. After that it will retrieve the same document and on the end it will remove the document.
#include <string>
#include <vector>
#include <iostream>
#include <cpr/response.h>
#include <elasticlient/client.h>
int main() {
// Prepare Client for nodes of one Elasticsearch cluster
elasticlient::Client client({"http://elastic1.host:9200/"}); // last / is mandatory
std::string document {"{\"message\": \"Hello world!\"}"};
// Index the document, index "testindex" must be created before
cpr::Response indexResponse = client.index("testindex", "docType", "docId", document);
// 200
std::cout << indexResponse.status_code << std::endl;
// application/json; charset=UTF-8
std::cout << indexResponse.header["content-type"] << std::endl;
// Elasticsearch response (JSON text string)
std::cout << indexResponse.text << std::endl;
// Retrieve the document
cpr::Response retrievedDocument = client.get("testindex", "docType", "docId");
// 200
std::cout << retrievedDocument.status_code << std::endl;
// application/json; charset=UTF-8
std::cout << retrievedDocument.header["content-type"] << std::endl;
// Elasticsearch response (JSON text string) where key "_source" contain:
// {"message": "Hello world!"}
std::cout << retrievedDocument.text << std::endl;
// Remove the document
cpr::Response removedDocument = client.remove("testindex", "docType", "docId");
// 200
std::cout << removedDocument.status_code << std::endl;
// application/json; charset=UTF-8
std::cout << removedDocument.header["content-type"] << std::endl;
// Elasticsearch response (JSON text string)
std::cout << removedDocument.text << std::endl;
return 0;
}
Usage of Bulk indexer
#include <memory>
#include <string>
#include <vector>
#include <iostream>
#include <elasticlient/client.h>
#include <elasticlient/bulk.h>
int main() {
// Prepare Client for nodes of one Elasticsearch cluster
std::shared_ptr<elasticlient::Client> client = std::make_shared<elasticlient::Client>(
std::vector<std::string>({"http://elastic1.host:9200/"})); // last / is mandatory
elasticlient::Bulk bulkIndexer(client);
elasticlient::SameIndexBulkData bulk("testindex", 100);
bulk.indexDocument("docType", "docId0", "{\"data\": \"data0\"}");
bulk.indexDocument("docType", "docId1", "{\"data\": \"data1\"}");
bulk.indexDocument("docType", "docId2", "{\"data\": \"data2\"}");
// another unlimited amount of indexDocument() calls...
size_t errors = bulkIndexer.perform(bulk);
std::cout << "When indexing " << bulk.size() << " documents, "
<< errors << " errors occured" << std::endl;
bulk.clear();
return 0;
}
Usage of Scroll API
#include <memory>
#include <string>
#include <vector>
#include <iostream>
#include <json/json.h>
#include <elasticlient/client.h>
#include <elasticlient/scroll.h>
int main() {
// Prepare Client for nodes of one Elasticsearch cluster
std::shared_ptr<elasticlient::Client> client = std::make_shared<elasticlient::Client>(
std::vector<std::string>({"http://elastic1.host:9200/"})); // last / is mandatory
elasticlient::Scroll scrollInstance(client);
std::string searchQuery{"{\"sort\": [\"_doc\"],"
" \"query\": {"
" \"prefix\": {"
" \"data\": \"data\"}}}"};
// Scroll all documents of type: docType from testindex which corresponding searchQuery
scrollInstance.init("testindex", "docType", searchQuery);
Json::StyledWriter writer;
Json::Value res;
bool isSuccessful = true;
// Will scroll for all suitable documents
while ((isSuccessful = scrollInstance.next(res))) {
if (res["hits"].empty()) {
// last scroll, no more results
break;
}
std::cout << writer.write(res["hits"]) << std::endl;
}
scrollInstance.clear();
}
How to use logging feature (debugging)
#include <iostream>
#include <elasticlient/client.h>
#include <elasticlient/logging.h>
/// Very simple log callback (only print message to stdout)
void logCallback(elasticlient::LogLevel logLevel, const std::string &msg) {
if (logLevel != elasticlient::LogLevel::DEBUG) {
std::cout << "LOG " << (unsigned) logLevel << ": " << msg << std::endl;
}
}
int main() {
// Set logging function for elasticlient library
elasticlient::setLogFunction(logCallback);
// Elasticlient will now print all debug messages on stdout.
// It is necessary to set logging function for elasticlient for each thread where you want
// use this logging feature!
}
Elasticlient connection settings
To setup various settings for the connection, option arguments can be passed into constructor.
// Prepare Client for nodes of one Elasticsearch cluster.
// Various options could be passed into it - vector of the cluster nodes must be first
// but the rest of the arguments is order independent, and each is optional.
elasticlient::Client client(
{"http://elastic1.host:9200/"},
elasticlient::Client::TimeoutOption{30000},
elasticlient::Client::ConnectTimeoutOption{1000},
elasticlient::Client::ProxiesOption(
{{"http", "http://proxy.host:8080"},
{"https", "https://proxy.host:8080"}})
);
// each of these options can be set later as well
elasticlient::Client::SSLOption sslOptions {
elasticlient::Client::SSLOption::VerifyHost{true},
elasticlient::Client::SSLOption::VerifyPeer{true},
elasticlient::Client::SSLOption::CaInfo{"myca.pem"},
elasticlient::Client::SSLOption::CertFile{"mycert.pem"},
elasticlient::Client::SSLOption::KeyFile{"mycert-key.pem"}};
client.setClientOption(std::move(sslOptions));
client.setClientOption(elasticlient::Client::TimeoutOption{300000});
Currently supported options:
Client::TimeoutOption
- HTTP request timeout in ms.Client::ConnectTimeoutOption
- Connect timeout in ms.Client::ProxiesOption
- Proxy server settings.Client::SSLOption
Client::SSLOption::CertFile
- path to the SSL certificate file.Client::SSLOption::KeyFile
- path to the SSL certificate key file.Client::SSLOption::CaInfo
- path to the CA bundle if custom CA is used.Client::SSLOption::VerifyHost
- verify the certificate's name against host.Client::SSLOption::VerifyPeer
- verify the peer's SSL certificate.
License
Elasticlient is licensed under the MIT License (MIT). Only the cmake/Modules/FindJsonCpp.cmake is originally licensed under Boost Software License, for more information see header of the file.