opengemini-client-cpp

⚠️ This repository is in pre-alpha stage, so not yet feature-complete. And the API has not been frozen, it may be changed on the course of the development.

English | 简体中文

opengemini-client-cpp is a C++ client for OpenGemini

---

• Design Doc
• About OpenGemini
• Prerequisites
• Integration
  • CMake FetchContent
  • CMake FindPackage
  • Header-Only
• Quick Start
• Build From Source
• Configuration
• Contribute

Design Doc

OpenGemini Client Design Doc

About OpenGemini

OpenGemini is a cloud-native distributed time series database, find more information here

Prerequisites

• Building Environment
  • A compatible operating system: Linux, macOS, Windows
  • A C++ compiler toolset that supports at least C++17 standard: GCC, Clang, MSVC
  • CMake 3.12 or later
  • Doxygen (optional, for generating documents)
• Dependencies
  • Boost 1.81 or later
  • {fmt}
  • JSON
  • OpenSSL (optional, for using TLS protocol)
  • GoogleTest (optional, for building unit tests)

Integration

CMake FetchContent

It is recommended to integrate with OpenGeminiCxx using CMake's FetchContent.

The library, along with any necessary dependencies(excluding OpenSSL), will be downloaded automatically, so you don't need to handle it yourself.

You can including the following lines in your CMakeLists.txt:

include(FetchContent)
FetchContent_Declare(OpenGeminiCxx
    GIT_REPOSITORY https://github.com/openGemini/opengemini-client-cpp
    GIT_TAG        main
)
FetchContent_MakeAvailable(OpenGeminiCxx)

This will export the target OpenGeminiCxx::Client which you can link against to your own target like this:

add_executable(YourApp main.cpp)
target_link_libraries(YourApp PRIVATE OpenGeminiCxx::Client)

CMake FindPackage

You can also use CMake's find_package() function to integrate the library into your project.

This means you need to build and install OpenGeminiCxx on your system first.

Then you can add the following lines in your CMakeLists.txt:

find_package(OpenGeminiCxx REQUIRED)

This will export the target OpenGeminiCxx::Client which you can link against to your own target like this:

add_executable(YourApp main.cpp)
target_link_libraries(YourApp PRIVATE OpenGeminiCxx::Client)

Header-Only

Note: Although OpenGeminiCxx can be use as a header-only library, we still recommend use the compiled library for improved build times.

Download the OpenGeminiCxx, then add /path/to/opengemini-client-cpp/include to your project's including directories.

You may also need to link against any necessary dependencies to your program manually, then you can include it directly in your source code with:

#include <opengemini/Client.hpp>

Quick Start

Below are a few examples show how to use some of the main features of the library. For more example code, please check out examples directory;

Query data from the server

#include <iostream>

#include <opengemini/Client.hpp>
#include <opengemini/ClientConfigBuilder.hpp>

int main(int argc, char** argv)
{
    // Constructs an openGemini client object.
    opengemini::Client client{ opengemini::ClientConfigBuilder()
                                   // At least one server endpoint needed.
                                   .AppendAddress({ "127.0.0.1", 8086 })
                                   .Finalize() };

    // Performs a query request and print the result, the operation will
    // block until completes or an exception is thrown.
    auto result = client.Query({
        "ExampleDatabase",
        "select * from ExampleMeasurement",
    });
    std::cout << result << std::endl;

    return 0;
}

Write points to server

#include <iostream>

#include <opengemini/Client.hpp>
#include <opengemini/ClientConfigBuilder.hpp>

int main(int argc, char** argv)
{
    // Constructs an openGemini client object.
    opengemini::Client client{ opengemini::ClientConfigBuilder()
                                   // At least one server endpoint needed.
                                   .AppendAddress({ "127.0.0.1", 8086 })
                                   .Finalize() };

    // Writes single point to server, the operation will
    // block until completes or an exception is thrown.
    client.Write("ExampleDatabase",
                 {
                     "ExampleMeasurement",
                     {
                         { "Weather", "sunny" },
                         { "Humidity", 521 },
                         { "Temperature", 38.1 },
                     },
                     std::chrono::system_clock::now(),
                 });
    return 0;
}

Build From Source

Make sure all required build tools and dependencies are installed on your system, then you can download and build the OpenGeminiCxx library:

git clone https://github.com/openGemini/opengemini-client-cpp.git
cd opengemini-client-cpp && mkdir build && cd build
cmake ..
make -j
make install

If you want to enable TLS support, you can configure with OPENGEMINI_ENABLE_SSL_SUPPORT option:

cmake -DOPENGEMINI_ENABLE_SSL_SUPPORT=ON .. 

You can also control generation of unit tests with OPENGEMINI_BUILD_TESTING option:

cmake -DOPENGEMINI_BUILD_TESTING=ON .. 

For details of all the options see CMake Options.

Configuration

CMake Options

Option	Description	Default Value
OPENGEMINI_ENABLE_SSL_SUPPORT	Enable OpenSSL support for using TLS (OpenSSL required)	OFF
OPENGEMINI_BUILD_DOCUMENTATION	Build API documentation (Doxygen required)	OFF
OPENGEMINI_BUILD_TESTING	Build unit tests (GoogleTest required)	OFF
OPENGEMINI_BUILD_SHARED_LIBS	Build shared libraries instead of static ones. Only has effect if option OPENGEMINI_BUILD_HEADER_ONLY_LIBS is OFF	OFF
OPENGEMINI_BUILD_EXAMPLE	Build examples	OFF
OPENGEMINI_BUILD_HEADER_ONLY_LIBS	Build as header-only library	OFF
OPENGEMINI_GENERATE_INSTALL_TARGET	Generate the install target, should not be set to ON if OPENGEMINI_USE_FETCHCONTENT is also ON	ON (if is root project)
OPENGEMINI_USE_FETCHCONTENT	Automatically using FetchContent if dependencies not found	OFF (if is root project)

Contribution

Welcome to join us.