{"id":14988031,"url":"https://github.com/apache/horaedb-client-java","last_synced_at":"2025-10-19T12:30:32.622Z","repository":{"id":36956223,"uuid":"501159254","full_name":"apache/horaedb-client-java","owner":"apache","description":"Apache HoraeDB (Incubating) Java Client.","archived":false,"fork":false,"pushed_at":"2024-08-14T07:50:34.000Z","size":845,"stargazers_count":21,"open_issues_count":3,"forks_count":12,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-01-30T10:23:48.290Z","etag":null,"topics":["cloud-native","database","distributed-database","horaedb","iot-database","java","sql","timeseries-analysis","timeseries-database","tsdb"],"latest_commit_sha":null,"homepage":"https://horaedb.apache.org/","language":"Java","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/apache.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":"2022-06-08T08:15:35.000Z","updated_at":"2024-08-14T07:50:39.000Z","dependencies_parsed_at":"2023-12-22T13:03:35.643Z","dependency_job_id":"3ae38466-ee78-466b-9624-687ec8da2789","html_url":"https://github.com/apache/horaedb-client-java","commit_stats":null,"previous_names":["ceresdb/horaedb-client-java","apache/incubator-horaedb-client-java","ceresdb/ceresdb-client-java","apache/horaedb-client-java"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fhoraedb-client-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fhoraedb-client-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fhoraedb-client-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fhoraedb-client-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/apache","download_url":"https://codeload.github.com/apache/horaedb-client-java/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237125524,"owners_count":19259299,"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":["cloud-native","database","distributed-database","horaedb","iot-database","java","sql","timeseries-analysis","timeseries-database","tsdb"],"created_at":"2024-09-24T14:15:58.909Z","updated_at":"2025-10-19T12:30:27.224Z","avatar_url":"https://github.com/apache.png","language":"Java","readme":"# Apache HoraeDB (Incubating) Java Client\n\n![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)\n\n[中文](README_CN.md)\n\n## Introduction\n\nJava client for [Apache HoraeDB (Incubating)](https://github.com/apache/incubator-horaedb).\n\n\u003e [!IMPORTANT]\n\u003e Apache HoraeDB (incubating) is an effort undergoing incubation at the Apache\n\u003e Software Foundation (ASF), sponsored by the Apache Incubator PMC.\n\u003e\n\u003e Please read the [DISCLAIMER](DISCLAIMER) and a full explanation of [\"incubating\"](https://incubator.apache.org/policy/incubation.html).\n\n## Features\n\n- With the well-designed SPI, the network transport layer is extensible. And we provide the default implementation which uses the gRPC framework.\n- The client provides high-performance async streaming write API.\n- The client also collects lots of performance metrics by default. These metrics can be configured to write to local file.\n- We can take memory snapshots that contains the status of critical objects. The snapshots can also be configured to write to local file, which helps a lot when we diagnose complex problems.\n\n## Data ingestion process\n\n```\n                   ┌─────────────────────┐  \n                   │   HoraeDBClient     │  \n                   └─────────────────────┘  \n                              │  \n                              ▼  \n                   ┌─────────────────────┐  \n                   │     WriteClient     │───┐  \n                   └─────────────────────┘   │  \n                              │     Async to retry and merge responses  \n                              │              │  \n                 ┌────Split requests         │  \n                 │                           │  \n                 │  ┌─────────────────────┐  │   ┌─────────────────────┐       ┌─────────────────────┐\n                 └─▶│    RouterClient     │◀─┴──▶│     RouterCache     │◀─────▶│      RouterFor      │\n                    └─────────────────────┘      └─────────────────────┘       └─────────────────────┘\n                               ▲                                                          │  \n                               │                                                          │  \n                               ▼                                                          │  \n                    ┌─────────────────────┐                                               │  \n                    │      RpcClient      │◀──────────────────────────────────────────────┘  \n                    └─────────────────────┘  \n                               ▲  \n                               │  \n                               ▼  \n                    ┌─────────────────────┐  \n                    │  Default gRPC impl  │  \n                    └─────────────────────┘  \n                               ▲  \n                               │  \n           ┌───────────────────┴ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐  \n           │                            │  \n           ▼                            ▼                            ▼  \n┌─────────────────────┐      ┌─────────────────────┐      ┌─────────────────────┐  \n│   HoraeDB Node1     │      │   HoraeDB Node2     │      │         ...         │  \n└─────────────────────┘      └─────────────────────┘      └─────────────────────┘  \n```\n\n## Data query process\n```\n                   ┌─────────────────────┐  \n                   │   HoraeDBClient     │  \n                   └─────────────────────┘  \n                              │  \n                              ▼  \n                   ┌─────────────────────┐  \n                   │     QueryClient     │───┐  \n                   └─────────────────────┘   │  \n                              │              │Async to retry  \n                              │              │  \n                 ┌────────────┘              │  \n                 │                           │  \n                 │  ┌─────────────────────┐  │   ┌─────────────────────┐       ┌─────────────────────┐\n                 └─▶│    RouterClient     │◀─┴──▶│     RouterCache     │◀─────▶│      RouterFor      │\n                    └─────────────────────┘      └─────────────────────┘       └─────────────────────┘\n                               ▲                                                          │  \n                               │                                                          │  \n                               ▼                                                          │  \n                    ┌─────────────────────┐                                               │  \n                    │      RpcClient      │◀──────────────────────────────────────────────┘  \n                    └─────────────────────┘  \n                               ▲  \n                               │  \n                               ▼  \n                    ┌─────────────────────┐  \n                    │  Default gRPC impl  │  \n                    └─────────────────────┘  \n                               ▲  \n                               │  \n           ┌───────────────────┴ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐  \n           │                            │  \n           ▼                            ▼                            ▼  \n┌─────────────────────┐      ┌─────────────────────┐      ┌─────────────────────┐  \n│   HoraeDB Node1     │      │   HoraeDB Node2     │      │         ...         │  \n└─────────────────────┘      └─────────────────────┘      └─────────────────────┘  \n```\n\n## Requirements\n- Java 8 or later is required for compilation \n\n## Import\n```java\n\u003cdependency\u003e\n  \u003cgroupId\u003eio.ceresdb\u003c/groupId\u003e\n  \u003cartifactId\u003ehoraedb-all\u003c/artifactId\u003e\n  \u003cversion\u003e1.0.0-alpha\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n## Init HoraeDB client\n```java\nfinal HoraeDBOptions opts = HoraeBOptions.newBuilder(\"127.0.0.1\", 8831, DIRECT) // HoraeDB default grpc port 8831，use DIRECT RouteMode\n        .database(\"public\") // use database for client, can be overridden by the RequestContext in request\n        // maximum retry times when write fails\n        // (only some error codes will be retried, such as the routing table failure)\n        .writeMaxRetries(1)\n        // maximum retry times when read fails\n        // (only some error codes will be retried, such as the routing table failure)\n        .readMaxRetries(1).build();\n\nfinal HoraeDBClient client = new HoraeDBClient();\nif (!client.init(opts)) {\n        throw new IllegalStateException(\"Fail to start HoraeDBClient\");\n}\n```\nFor more configuration options, see [configuration](docs/configuration.md)\n\n## Create table example\nHoraeDB is a Schema-less time-series database, so creating table schema ahead of data ingestion is not required (HoraeDB will create a default schema according to the very first data you write into it). Of course, you can also manually create a schema for fine grained management purposes (eg. managing index).\n\nThe following table creation statement（using the SQL API included in SDK ）shows all field types supported by HoraeDB：\n\n```java\n// Create table manually, creating table schema ahead of data ingestion is not required\nString createTableSql = \"CREATE TABLE IF NOT EXISTS machine_table(\" +                                                                                              \"ts TIMESTAMP NOT NULL,\" + //\n        \"ts TIMESTAMP NOT NULL,\" +\n        \"city STRING TAG NOT NULL,\" +\n        \"ip STRING TAG NOT NULL,\" +\n        \"cpu DOUBLE NULL,\" +\n        \"mem DOUBLE NULL,\" +\n        \"TIMESTAMP KEY(ts)\" + // timestamp column must be specified\n        \") ENGINE=Analytic\";\n\nResult\u003cSqlQueryOk, Err\u003e createResult = client.sqlQuery(new SqlQueryRequest(createTableSql)).get();\nif (!createResult.isOk()) {\n        throw new IllegalStateException(\"Fail to create table\");\n}\n```\n\n## How to build write data\n```java\nfinal Point point = Point.newPointBuilder(\"machine_table\")\n        .setTimestamp(t0)\n        .addTag(\"city\", \"Singapore\")\n        .addTag(\"ip\", \"10.0.0.1\")\n        .addField(\"cpu\", Value.withDouble(0.23))\n        .addField(\"mem\", Value.withDouble(0.55))\n        .build();\n```\n\n## Write data example\n```java\nfinal CompletableFuture\u003cResult\u003cWriteOk, Err\u003e\u003e wf = client.write(new WriteRequest(pointList));\n// here the `future.get` is just for demonstration, a better async programming practice would be using the CompletableFuture API\nfinal Result\u003cWriteOk, Err\u003e writeResult = wf.get();\nAssert.assertTrue(writeResult.isOk());\n// `Result` class referenced the Rust language practice, provides rich functions (such as mapXXX, andThen) transforming the result value to improve programming efficiency. You can refer to the API docs for detail usage.\nAssert.assertEquals(3, writeResult.getOk().getSuccess());\nAssert.assertEquals(3, writeResult.mapOr(0, WriteOk::getSuccess).intValue());\nAssert.assertEquals(0, writeResult.mapOr(-1, WriteOk::getFailed).intValue());\n```\nSee [write](docs/write.md)\n\n## Query data example\n```java\nfinal SqlQueryRequest queryRequest = SqlQueryRequest.newBuilder()\n        .forTables(\"machine_table\") // table name is optional. If not provided, SQL parser will parse the `sql` to get the table name and do the routing automaticly\n        .sql(\"select * from machine_table where ts = %d\", t0) //\n        .build();\nfinal CompletableFuture\u003cResult\u003cSqlQueryOk, Err\u003e\u003e qf = client.sqlQuery(queryRequest);\n// here the `future.get` is just for demonstration, a better async programming practice would be using the CompletableFuture API\nfinal Result\u003cSqlQueryOk, Err\u003e queryResult = qf.get();\n\nAssert.assertTrue(queryResult.isOk());\n\nfinal SqlQueryOk queryOk = queryResult.getOk();\nAssert.assertEquals(1, queryOk.getRowCount());\n\n// get rows as list\nfinal List\u003cRow\u003e rows = queryOk.getRowList();\n\n// get rows as stream\nfinal Stream\u003cRow\u003e rowStream = queryOk.stream();\nrowStream.forEach(row -\u003e System.out.println(row.toString()));\n```\nSee [read](docs/read.md)\n\n## stream write/read Example\nHoraeDB support streaming writing and reading，suitable for large-scale data reading and writing。\n```java\nfinal StreamWriteBuf\u003cPoint, WriteOk\u003e writeBuf = client.streamWrite(\"machine_table\");\nfor (int i = 0; i \u003c 1000; i++) {\n    final Point point = Point.newPointBuilder(\"machine_table\")\n        .setTimestamp(timestamp)\n        .addTag(\"city\", \"Beijing\")\n        .addTag(\"ip\", \"10.0.0.3\")\n        .addField(\"cpu\", Value.withDouble(0.42))\n        .addField(\"mem\", Value.withDouble(0.67))\n        .build();\n        writeBuf.writeAndFlush(Arrays.asList(point));\n        timestamp = timestamp+1;\n}\n\nfinal CompletableFuture\u003cWriteOk\u003e writeOk = writeBuf.completed();\n```\nSee [streaming](docs/streaming.md)\n\n## Licensing\nUnder [Apache License 2.0](./LICENSE).\n\n## Community and support\n- Join the user group on DingTalk: 44602802\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapache%2Fhoraedb-client-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapache%2Fhoraedb-client-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapache%2Fhoraedb-client-java/lists"}