Skip to content

Latest commit

 

History

History
189 lines (153 loc) · 7.02 KB

README_CN.md

File metadata and controls

189 lines (153 loc) · 7.02 KB
Raw

opengemini-client-cpp

License language version

⚠️ 当前仓库仍处于早期开发阶段，功能特性尚未完成。目前提供的API接口不是稳定版本，可能随开发进程有所调整。

English | 简体中文

opengemini-client-cpp是一个用 C++ 语言编写的 OpenGemini 客户端

设计文档

OpenGemini Client 设计文档

关于 OpenGemini

OpenGemini 是一款云原生分布式时序数据库。获取更多信息，请点击这里

前置条件

  • 构建环境
    • 兼容的操作系统：Linux，macOS，Windows
    • 支持C++17（或更新版本）的编译套件: GCC，Clang，MSVC
    • CMake 3.12或更高版本
    • Doxygen (非必选，用于生成文档)
  • 依赖库

与项目集成

CMake FetchContent

我们推荐使用CMake FetchContent 来将OpenGeminiCxx集成到您的项目中。

库自身和所有必要的依赖（除了OpenSSL）都会自动下载，不需要手动处理依赖。

可以将下列代码添加至项目的CMakeLists.txt中：

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

这将导出目标OpenGeminiCxx::Client，您可以将其链接到自己的目标中：

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

CMake FindPackage

也可以使用CMake find_package() 函数来集成到项目中。

这意味着您必须先在系统上构建并安装OpenGeminiCxx。

接着就可以将下列代码添加至CMakeLists.txt中：

find_package(OpenGeminiCxx REQUIRED)

这将导出目标OpenGeminiCxx::Client，您可以将其链接到自己的目标中：

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

Header-Only

注意： 尽管OpenGeminiCxx可以当作纯头文件引用，但我们仍建议使用预编译好的版本以减少构建时间。

下载OpenGeminiCxx，然后将/path/to/opengemini-client-cpp/include添加至工程的包含路径中。

然后就可以直接在源码中包含（可能需要手动将必要的依赖库链接到工程中）：

#include <opengemini/Client.hpp>

快速上手

下列示例代码简单演示了这个库的一些主要特性，您可以通过examples目录查看更多的示例代码。

从服务端查询数据

#include <iostream>

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

int main(int argc, char** argv)
{
    // 构造OpenGemini客户端对象。
    opengemini::Client client{ opengemini::ClientConfigBuilder()
                                    // 需要至少指定一个服务端的端点
                                   .AppendAddress({ "127.0.0.1", 8086 })
                                   .Finalize() };

    // 执行查询请求并直接将结果直接打印。
    // 该操作将会一直阻塞，直到成功完成或抛出异常。
    auto result = client.Query({
        "ExampleDatabase",
        "select * from ExampleMeasurement",
    });
    std::cout << result << std::endl;

    return 0;
}

向服务端写入点位

#include <iostream>

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

int main(int argc, char** argv)
{
    // 构造OpenGemini客户端对象。
    opengemini::Client client{ opengemini::ClientConfigBuilder()
                                    // 需要至少指定一个服务端的端点
                                   .AppendAddress({ "127.0.0.1", 8086 })
                                   .Finalize() };

    // 向服务端写入单个点位。
    // 该操作将会一直阻塞，直到成功完成或抛出异常。
    client.Write("ExampleDatabase",
                 {
                     "ExampleMeasurement",
                     {
                         { "Weather", "sunny" },
                         { "Humidity", 521 },
                         { "Temperature", 38.1 },
                     },
                     std::chrono::system_clock::now(),
                 });
    return 0;
}

从源码构建

确保所有必要的构建工具和依赖库已经安装到您的系统上了，接着就可以下载并构建OpenGeminiCxx：

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

如果想要启用TLS支持，可以使用选项OPENGEMINI_ENABLE_SSL_SUPPORT进行配置：

cmake -DOPENGEMINI_ENABLE_SSL_SUPPORT=ON ..

也可以通过选项OPENGEMINI_ENABLE_SSL_SUPPORT来生成单元测试：

cmake -DOPENGEMINI_BUILD_TESTING=ON ..

关于所有配置选项的详细信息，参见CMake选项

配置选项

CMake选项

选项 描述 默认值
OPENGEMINI_ENABLE_SSL_SUPPORT 启用TLS支持（需要OpenSSL） OFF
OPENGEMINI_BUILD_DOCUMENTATION 构建API文档（需要Doxygen） OFF
OPENGEMINI_BUILD_TESTING 构建单元测试（需要GoogleTest） OFF
OPENGEMINI_BUILD_SHARED_LIBS 构建为动态库，仅当选项OPENGEMINI_BUILD_HEADER_ONLY_LIBS的值为OFF时生效 OFF
OPENGEMINI_BUILD_EXAMPLE 构建样例代码 OFF
OPENGEMINI_BUILD_HEADER_ONLY_LIBS 构建为header-only库 OFF
OPENGEMINI_GENERATE_INSTALL_TARGET 生成安装目标，该选项和OPENGEMINI_USE_FETCHCONTENT选项的值不能同时为ON ON
（当是根项目时）
OPENGEMINI_USE_FETCHCONTENT 若无法找到依赖，则自动使用FetchContent OFF
（当是根项目时）

贡献

欢迎加入我们。