diff --git a/docs/user-guide/ingest-data/for-iot/grpc-sdks/go.md b/docs/user-guide/ingest-data/for-iot/grpc-sdks/go.md index 8c80600f5..2f92b2ef8 100644 --- a/docs/user-guide/ingest-data/for-iot/grpc-sdks/go.md +++ b/docs/user-guide/ingest-data/for-iot/grpc-sdks/go.md @@ -10,20 +10,18 @@ import DocTemplate from './template.md'
- +## Introduction The Go ingester SDK provided by GreptimeDB is a lightweight, concurrent-safe library that is easy to use with the metric struct. -
- +## Quick start demos To quickly get started, you can explore the [quick start demos](https://github.com/GreptimeTeam/greptimedb-ingester-go/tree/main/examples) to understand how to use the GreptimeDB Go ingester SDK. -
- +## Installation Use the following command to install the GreptimeDB client library for Go: ```shell @@ -40,11 +38,10 @@ import ( "github.com/GreptimeTeam/greptimedb-ingester-go/table/types" ) ``` -
- +## Connect to database ```go cfg := greptime.NewConfig("127.0.0.1"). // change the database name to your database name @@ -62,7 +59,7 @@ cli, _ := greptime.NewClient(cfg)
- +## Set table options You can set table options using the `ingesterContext` context. For example, to set the `ttl` option, use the following code: @@ -83,11 +80,11 @@ if err != nil { return err } ``` -
- +## Low-level API +### Create row objects ```go // Construct the table schema for CPU metrics cpuMetric, err := table.New("cpu_metric") @@ -112,11 +109,10 @@ if err != nil { } ``` -
- +### Create multiple rows ```go cpuMetric, err := table.New("cpu_metric") if err != nil { @@ -143,11 +139,10 @@ if err != nil { // Handle error appropriately } ``` -
- +### Insert data ```go resp, err := cli.Write(ctx, cpuMetric, memMetric) if err != nil { @@ -155,30 +150,27 @@ if err != nil { } log.Printf("affected rows: %d\n", resp.GetAffectedRows().GetValue()) ``` -
- +### Streaming insert ```go err := cli.StreamWrite(ctx, cpuMetric, memMetric) if err != nil { // Handle error appropriately } ``` - Close the stream writing after all data has been written. In general, you do not need to close the stream writing when continuously writing data. ```go affected, err := cli.CloseStream(ctx) ``` -
-
- +## High-level API +### Create row objects ```go type CpuMetric struct { Host string `greptime:"tag;column:host;type:string"` @@ -225,31 +217,28 @@ memMetrics := []MemMetric{
- +### Insert data ```go resp, err := cli.WriteObject(ctx, cpuMetrics) log.Printf("affected rows: %d\n", resp.GetAffectedRows().GetValue()) ``` -
- +### Streaming insert ```go err := cli.StreamWriteObject(ctx, cpuMetrics) ``` - Close the stream writing after all data has been written. In general, you do not need to close the stream writing when continuously writing data. ```go affected, err := cli.CloseStream(ctx) ``` -
- +## Insert data in JSON type In the [low-level API](#low-level-api), you can specify the column type as `types.JSON` using the `AddFieldColumn` method to add a JSON column. Then, use a `struct` or `map` to insert JSON data. @@ -300,13 +289,19 @@ sensor := SensorReadings{ ``` For the executable code for inserting JSON data, please refer to the [example](https://github.com/GreptimeTeam/greptimedb-ingester-go/tree/main/examples/jsondata) in the SDK repository. +
+
+## Debug logs
- +## Ingester library reference - [API Documentation](https://pkg.go.dev/github.com/GreptimeTeam/greptimedb-ingester-go) +
+
+## FAQ
diff --git a/docs/user-guide/ingest-data/for-iot/grpc-sdks/java.md b/docs/user-guide/ingest-data/for-iot/grpc-sdks/java.md index 75aba04dc..329d4d55e 100644 --- a/docs/user-guide/ingest-data/for-iot/grpc-sdks/java.md +++ b/docs/user-guide/ingest-data/for-iot/grpc-sdks/java.md @@ -10,7 +10,7 @@ import DocTemplate from './template.md'
- +## Introduction The Java ingester SDK provided by GreptimeDB is a lightweight library with the following features: - SPI-based extensible network transport layer, which provides the default implementation using the gRPC framework. @@ -21,13 +21,12 @@ The Java ingester SDK provided by GreptimeDB is a lightweight library with the f
- +## Quick start demos To quickly get started, you can explore the [quick start demos](https://github.com/GreptimeTeam/greptimedb-ingester-java/tree/main/ingester-example/src/main/java/io/greptime) to understand how to use the GreptimeDB Java ingester SDK. -
- +## Installation 1. Install the Java Development Kit(JDK) Make sure that your system has JDK 8 or later installed. For more information on how to @@ -53,7 +52,7 @@ After configuring your dependencies, make sure they are available to your projec
- +## Connect to database The following code demonstrates how to connect to GreptimeDB with the simplest configuration. For customizing the connection options, please refer to [API Documentation](#ingester-library-reference). Please pay attention to the accompanying comments for each option, as they provide detailed explanations of their respective roles. @@ -84,7 +83,7 @@ For customizing the connection options, please refer to [API Documentation](#ing
- +## Set table options You can set table options using the `Context`. For example, to set the `ttl` option, use the following code: @@ -102,7 +101,8 @@ CompletableFuture> future = greptimeDB.write(Arrays.asList(
- +## Low-level API +### Create row objects ```java // Construct the table schema for `cpu_metric`. // The schema is immutable and can be safely reused across multiple operations. @@ -140,9 +140,8 @@ cpuMetric.complete();
-
- +### Create multiple rows ```java // Define the schema for tables. // The schema is immutable and can be safely reused across multiple operations. @@ -195,9 +194,8 @@ memMetric.complete();
-
- +### Insert data ```java // Saves data @@ -220,10 +218,8 @@ if (result.isOk()) {
-
- - +### Streaming insert ```java // Set the compression algorithm to Zstd. Context ctx = Context.newDefault().withCompression(Compression.Zstd); @@ -256,7 +252,8 @@ LOG.info("Write result: {}", result);
- +## High-level API +### Create row objects GreptimeDB Java Ingester SDK allows us to use basic POJO objects for writing. This approach requires the use of Greptime's own annotations, but they are easy to use. ```java @@ -314,10 +311,8 @@ for (int i = 0; i < 10; i++) {
-
- - +### Insert data Write data with POJO objects: ```java @@ -336,9 +331,8 @@ if (result.isOk()) {
-
- +### Streaming insert ```java StreamWriter, WriteOk> writer = greptimeDB.objectsStreamWriter(); @@ -363,7 +357,7 @@ LOG.info("Write result: {}", result);
- +## Insert data in JSON type In the [low-level API](#low-level-api), you can specify the column type as `DataType.Json` using the `addField` method to add a JSON column. Then use map to insert JSON data. @@ -414,24 +408,21 @@ sensor.setAttributes(attr);
- ## Debug logs - The ingester SDK provides metrics and logs for debugging. Please refer to [Metrics & Display](https://github.com/GreptimeTeam/greptimedb-ingester-java/blob/main/docs/metrics-display.md) and [Magic Tools](https://github.com/GreptimeTeam/greptimedb-ingester-java/blob/main/docs/magic-tools.md) to learn how to enable or disable the logs.
- +## Ingester library reference - [API Documentation](https://javadoc.io/doc/io.greptime/ingester-protocol/latest/index.html)
- +## FAQ ### Why am I getting some connection exceptions? - When using the GreptimeDB Java ingester SDK, you may encounter some connection exceptions. For example, exceptions that are "`Caused by: java.nio.channels.UnsupportedAddressTypeException`", "`Caused by: java.net.ConnectException: connect(..) failed: Address family not supported by protocol`", or @@ -486,4 +477,4 @@ packaged into the final JAR, during the assembling process. So the fix can be:
-
\ No newline at end of file + diff --git a/docs/user-guide/ingest-data/for-iot/grpc-sdks/template.md b/docs/user-guide/ingest-data/for-iot/grpc-sdks/template.md index 87200cf45..b7d012be3 100644 --- a/docs/user-guide/ingest-data/for-iot/grpc-sdks/template.md +++ b/docs/user-guide/ingest-data/for-iot/grpc-sdks/template.md @@ -1,4 +1,3 @@ - GreptimeDB offers ingester libraries for high-throughput data writing. It utilizes the gRPC protocol, which supports schemaless writing and eliminates the need to create tables before writing data. @@ -6,29 +5,19 @@ For more information, refer to [Automatic Schema Generation](/user-guide/ingest- -## Quick start demos - -## Installation - -## Connect to database - If you have set the [`--user-provider` configuration](/user-guide/deployments-administration/authentication/overview.md) when starting GreptimeDB, you will need to provide a username and password to connect to GreptimeDB. The following example shows how to set the username and password when using the library to connect to GreptimeDB. -## Data model - Each row item in a table consists of three types of columns: `Tag`, `Timestamp`, and `Field`. For more information, see [Data Model](/user-guide/concepts/data-model.md). The types of column values could be `String`, `Float`, `Int`, `Timestamp`, `JSON` etc. For more information, see [Data Types](/reference/sql/data-types.md). -## Set table options - Although the time series table is created automatically when writing data to GreptimeDB via the SDK, you can still configure table options. The SDK supports the following table options: @@ -40,13 +29,9 @@ The SDK supports the following table options: For how to write data to GreptimeDB, see the following sections. -## Low-level API - The GreptimeDB low-level API provides a straightforward method to write data to GreptimeDB by adding rows to the table object with a predefined schema. -### Create row objects - This following code snippet begins by constructing a table named `cpu_metric`, which includes columns `host`, `cpu_user`, `cpu_sys`, and `ts`. Subsequently, it inserts a single row into the table. @@ -63,46 +48,32 @@ To improve the efficiency of writing data, you can create multiple rows at once -### Insert data - The following example shows how to insert rows to tables in GreptimeDB. -### Streaming insert - Streaming insert is useful when you want to insert a large amount of data such as importing historical data. -## High-level API - The high-level API uses an ORM style object to write data to GreptimeDB. It allows you to create, insert, and update data in a more object-oriented way, providing developers with a friendlier experience. However, it is not as efficient as the low-level API. This is because the ORM style object may consume more resources and time when converting the objects. -### Create row objects - -### Insert data - -### Streaming insert - Streaming insert is useful when you want to insert a large amount of data such as importing historical data. -## Insert data in JSON type - GreptimeDB supports storing complex data structures using [JSON type data](/reference/sql/data-types.md#json-type). With this ingester library, you can insert JSON data using string values. For instance, if you have a table named `sensor_readings` and wish to add a JSON column named `attributes`, @@ -112,10 +83,6 @@ refer to the following code snippet. -## Ingester library reference - -## FAQ -