{"id":20102439,"url":"https://github.com/clickhouse/clickhouse-cpp","last_synced_at":"2025-04-14T06:52:43.717Z","repository":{"id":35692840,"uuid":"208047461","full_name":"ClickHouse/clickhouse-cpp","owner":"ClickHouse","description":"C++ client library for ClickHouse","archived":false,"fork":false,"pushed_at":"2025-04-01T23:37:25.000Z","size":2601,"stargazers_count":318,"open_issues_count":37,"forks_count":170,"subscribers_count":28,"default_branch":"master","last_synced_at":"2025-04-07T01:07:28.648Z","etag":null,"topics":["clickhouse","cpp"],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ClickHouse.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-09-12T12:35:34.000Z","updated_at":"2025-04-03T13:39:19.000Z","dependencies_parsed_at":"2024-06-21T16:48:45.957Z","dependency_job_id":"06ee8031-9c91-441d-b131-148c222e462a","html_url":"https://github.com/ClickHouse/clickhouse-cpp","commit_stats":{"total_commits":626,"total_committers":72,"mean_commits":8.694444444444445,"dds":0.6182108626198083,"last_synced_commit":"d242cc8b0e1c83f0fe1f61c3ccf07c0bf705a100"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClickHouse%2Fclickhouse-cpp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClickHouse%2Fclickhouse-cpp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClickHouse%2Fclickhouse-cpp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClickHouse%2Fclickhouse-cpp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ClickHouse","download_url":"https://codeload.github.com/ClickHouse/clickhouse-cpp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248837274,"owners_count":21169373,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clickhouse","cpp"],"created_at":"2024-11-13T17:30:46.631Z","updated_at":"2025-04-14T06:52:43.693Z","avatar_url":"https://github.com/ClickHouse.png","language":"C","readme":"ClickHouse C++ client [![Linux](https://github.com/ClickHouse/clickhouse-cpp/actions/workflows/linux.yml/badge.svg)](https://github.com/ClickHouse/clickhouse-cpp/actions/workflows/linux.yml) [![macOS](https://github.com/ClickHouse/clickhouse-cpp/actions/workflows/macos.yml/badge.svg)](https://github.com/ClickHouse/clickhouse-cpp/actions/workflows/macos.yml) [![Windows MSVC](https://github.com/ClickHouse/clickhouse-cpp/actions/workflows/windows_msvc.yml/badge.svg)](https://github.com/ClickHouse/clickhouse-cpp/actions/workflows/windows_msvc.yml) [![Windows mingw](https://github.com/ClickHouse/clickhouse-cpp/actions/workflows/windows_mingw.yml/badge.svg)](https://github.com/ClickHouse/clickhouse-cpp/actions/workflows/windows_mingw.yml)\n=====\n\nC++ client for [ClickHouse](https://clickhouse.com/).\n\n## Supported data types\n\n* Array(T)\n* Date\n* DateTime, DateTime64\n* DateTime([timezone]), DateTime64(N, [timezone])\n* Decimal32, Decimal64, Decimal128\n* Enum8, Enum16\n* FixedString(N)\n* Float32, Float64\n* IPv4, IPv6\n* Nullable(T)\n* String\n* LowCardinality(String) or LowCardinality(FixedString(N))\n* Tuple\n* UInt8, UInt16, UInt32, UInt64, Int8, Int16, Int32, Int64\n* Int128\n* UUID\n* Map\n* Point, Ring, Polygon, MultiPolygon\n\n## Dependencies\nIn the most basic case one needs only:\n- a C++-17-complaint compiler,\n- `cmake` (3.12 or newer), and\n- `ninja`\n\nOptional dependencies:\n- openssl\n- liblz4\n- libabsl\n- libzstd\n\n## Building\n\n```sh\n$ mkdir build .\n$ cd build\n$ cmake .. [-DBUILD_TESTS=ON]\n$ make\n```\n\nPlese refer to the workflows for the reference on dependencies/build options\n- https://github.com/ClickHouse/clickhouse-cpp/blob/master/.github/workflows/linux.yml\n- https://github.com/ClickHouse/clickhouse-cpp/blob/master/.github/workflows/windows_msvc.yml\n- https://github.com/ClickHouse/clickhouse-cpp/blob/master/.github/workflows/windows_mingw.yml\n- https://github.com/ClickHouse/clickhouse-cpp/blob/master/.github/workflows/macos.yml\n\n\n## Example application build with clickhouse-cpp\n\nThere are various ways to integrate clickhouse-cpp with the build system of an application. Below example uses the simple approach based on\nsubmodules presented in https://www.youtube.com/watch?v=ED-WUk440qc .\n\n- `mkdir clickhouse-app \u0026\u0026 cd clickhouse-app \u0026\u0026 git init`\n- `git submodule add https://github.com/ClickHouse/clickhouse-cpp.git contribs/clickhouse-cpp`\n- `touch app.cpp`, then copy the following C++ code into that file\n\n```cpp\n#include \u003ciostream\u003e\n#include \u003cclickhouse/client.h\u003e\n\nusing namespace clickhouse;\n\nint main()\n{\n    /// Initialize client connection.\n    Client client(ClientOptions().SetHost(\"localhost\"));\n\n    /// Create a table.\n    client.Execute(\"CREATE TABLE IF NOT EXISTS default.numbers (id UInt64, name String) ENGINE = Memory\");\n\n    /// Insert some values.\n    {\n        Block block;\n\n        auto id = std::make_shared\u003cColumnUInt64\u003e();\n        id-\u003eAppend(1);\n        id-\u003eAppend(7);\n\n        auto name = std::make_shared\u003cColumnString\u003e();\n        name-\u003eAppend(\"one\");\n        name-\u003eAppend(\"seven\");\n\n        block.AppendColumn(\"id\"  , id);\n        block.AppendColumn(\"name\", name);\n\n        client.Insert(\"default.numbers\", block);\n    }\n\n    /// Select values inserted in the previous step.\n    client.Select(\"SELECT id, name FROM default.numbers\", [] (const Block\u0026 block)\n        {\n            for (size_t i = 0; i \u003c block.GetRowCount(); ++i) {\n                std::cout \u003c\u003c block[0]-\u003eAs\u003cColumnUInt64\u003e()-\u003eAt(i) \u003c\u003c \" \"\n                          \u003c\u003c block[1]-\u003eAs\u003cColumnString\u003e()-\u003eAt(i) \u003c\u003c \"\\n\";\n            }\n        }\n    );\n\n    /// Delete table.\n    client.Execute(\"DROP TABLE default.numbers\");\n\n    return 0;\n}\n```\n\n- `touch CMakeLists.txt`, then copy the following CMake code into that file\n\n```cmake\ncmake_minimum_required(VERSION 3.12)\nproject(application-example)\n\nset(CMAKE_CXX_STANDARD 17)\n\nadd_subdirectory(contribs/clickhouse-cpp)\n\nadd_executable(${PROJECT_NAME} \"app.cpp\")\n\ntarget_include_directories(${PROJECT_NAME} PRIVATE contribs/clickhouse-cpp/ contribs/clickhouse-cpp/contrib/absl)\n\ntarget_link_libraries(${PROJECT_NAME} PRIVATE clickhouse-cpp-lib)\n```\n\n- run `rm -rf build \u0026\u0026 cmake -B build -S . \u0026\u0026 cmake --build build -j32` to remove remainders of the previous builds, run CMake and build the\n  application. The generated binary is located in location `build/application-example`.\n\n## Thread-safety\n⚠ Please note that `Client` instance is NOT thread-safe. I.e. you must create a separate `Client` for each thread or utilize some synchronization techniques. ⚠\n\n## Retries\nIf you wish to implement some retry logic atop of `clickhouse::Client` there are few simple rules to make you life easier:\n- If previous attempt threw an exception, then make sure to call `clickhouse::Client::ResetConnection()` before the next try.\n- For `clickhouse::Client::Insert()` you can reuse a block from previous try, no need to rebuild it from scratch.\n\nSee https://github.com/ClickHouse/clickhouse-cpp/issues/184 for details.\n\n## Asynchronous inserts\nSee https://clickhouse.com/docs/en/cloud/bestpractices/asynchronous-inserts for details.\n\n⚠ The asynchronous setting is different according to the clickhouse-server version. The under example with clickhouse-server version 24.8.4.13. ⚠\n\n\u003e Our strong recommendation is to use async_insert=1,wait_for_async_insert=1 if using asynchronous inserts. Using wait_for_async_insert=0 is very risky because your INSERT client may not be aware if there are errors, and also can cause potential overload if your client continues to write quickly in a situation where the ClickHouse server needs to slow down the writes and create some backpressure in order to ensure reliability of the service.\n\n- Only use the SDK, do not need to change the clickhouse-server config. Asynchronous inserts only work if the data is sent as SQL text format. Here is the example.\n```cpp\n// You can specify the asynchronous insert settings by using the SETTINGS clause of insert queries\nclickhouse::Query query(\"INSERT INTO default.test SETTINGS async_insert=1,wait_for_async_insert=1,async_insert_busy_timeout_ms=5000,async_insert_use_adaptive_busy_timeout=0,async_insert_max_data_size=104857600 VALUES(10,10)\");\nclient.Execute(query);\n\n// Or by SetSetting\nclickhouse::Query query(\"INSERT INTO default.test VALUES(10,10)\");\nquery.SetSetting(\"async_insert\", clickhouse::QuerySettingsField{ \"1\", 1 });\nquery.SetSetting(\"wait_for_async_insert\", clickhouse::QuerySettingsField{ \"1\", 1 }); // strong recommendation\nquery.SetSetting(\"async_insert_busy_timeout_ms\", clickhouse::QuerySettingsField{ \"5000\", 1 });\nquery.SetSetting(\"async_insert_max_data_size\", clickhouse::QuerySettingsField{ \"104857600\", 1 });\nquery.SetSetting(\"async_insert_use_adaptive_busy_timeout\", clickhouse::QuerySettingsField{ \"0\", 1 });\nclient.Execute(query);\n\n// Not available case. The Insert interface actually use the native data format\nclickhouse::Block block;\nclient.Insert(\"default.test\", block);\n```\n- Change the clickhouse-server users.xml, enable asynchronous inserts (available for the native data format). Here is the example.\n```xml\n\u003cprofiles\u003e\n        \u003c!-- Default settings. --\u003e\n        \u003cdefault\u003e\n            \u003casync_insert\u003e1\u003c/async_insert\u003e\n            \u003cwait_for_async_insert\u003e1\u003c/wait_for_async_insert\u003e\n            \u003casync_insert_use_adaptive_busy_timeout\u003e0\u003c/async_insert_use_adaptive_busy_timeout\u003e\n            \u003casync_insert_busy_timeout_ms\u003e5000\u003c/async_insert_busy_timeout_ms\u003e\n            \u003casync_insert_max_data_size\u003e104857600\u003c/async_insert_max_data_size\u003e\n        \u003c/default\u003e\n\n        \u003c!-- Profile that allows only read queries. --\u003e\n        \u003creadonly\u003e\n            \u003creadonly\u003e1\u003c/readonly\u003e\n        \u003c/readonly\u003e\n    \u003c/profiles\u003e\n```\n- Enabling asynchronous inserts at the user level. Ensure your login accout has the privileges about ALTER USER. Then you can use insert_account for asynchronous inserts.\n```sql\nALTER USER insert_account SETTINGS async_insert=1,wait_for_async_insert=1,async_insert_use_adaptive_busy_timeout=0,async_insert_busy_timeout_ms=5000,async_insert_max_data_size=104857600\n```\n\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclickhouse%2Fclickhouse-cpp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclickhouse%2Fclickhouse-cpp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclickhouse%2Fclickhouse-cpp/lists"}