Java

Insert

Data Ingestion Process

Use the following code to insert an object to GreptimeDB:

java

  1. TableSchema tableSchema = TableSchema.newBuilder(TableName.with("public" /* db name */, "monitor"))
  2. .semanticTypes(SemanticType.Tag, SemanticType.Timestamp, SemanticType.Field, SemanticType.Field)
  3. .dataTypes(ColumnDataType.String, ColumnDataType.Int64, ColumnDataType.Float64, ColumnDataType.Float64)
  4. .columnNames("host", "ts", "cpu", "memory")
  5. .build();
  6. WriteRows rows = WriteRows.newBuilder(tableSchema).build();
  7. long now = System.currentTimeMillis();
  8. rows.insert("127.0.0.1", now, 0.1, null)
  9. .insert("127.0.0.2", now, 0.3, 0.5)
  10. .finish();
  11. CompletableFuture<Result<WriteOk, Err>> writeFuture = greptimeDB.write(rows);
  12. Result<WriteOk, Err> result = future.get();
  13. if (result.isOk()) {
  14. LOG.info("Write result: {}", result.getOk());
  15. } else {
  16. LOG.error("Failed to write: {}", result.getErr());
  17. }

You can also use the StreamWriter API to write data:

java

  1. TableName tableName = TableName.with("public" /* db name */, "monitor");
  2. TableSchema
  3. .newBuilder(tableName)
  4. .semanticTypes(SemanticType.Tag, SemanticType.Timestamp, SemanticType.Field, SemanticType.Field)
  5. .dataTypes(ColumnDataType.String, ColumnDataType.TimestampMillisecond, ColumnDataType.Float64, ColumnDataType.Float64)
  6. .columnNames("host", "ts", "cpu", "memory")
  7. .buildAndCache(); // cache for reuse
  8. StreamWriter<WriteRows, WriteOk> streamWriter = greptimeDB.streamWriter();
  9. for (int i = 0; i < 100; i++) {
  10. WriteRows rows = WriteRows.newBuilder(TableSchema.findSchema(tableName)).build();
  11. rows.insert("127.0.0.1", now + i, i, null).finish();
  12. streamWriter.write(rows);
  13. }
  14. CompletableFuture<WriteOk> future = streamWriter.completed();
  15. WriteOk result = future.get();
  16. LOG.info("Write result: {}", result);

To begin, we must create a TableSchema and then use it to construct a WriteRows object. Since the TableSchema can be reused, caching it can prevent unnecessary construction.

Once the WriteRows object is created, data can be added to it. However, this data is only stored in memory and has not yet been sent to the server. To insert multiple rows efficiently, we use batch insertion. Once all desired data has been added to the WriteRows, remember to call its finish method before sending it to the server.

After calling the write method on our completed WriteRows, a future will be returned which allows us to obtain write results through its callback function. You can also obtain the result synchronously by using future.get().

If you need to insert a large amount of data, consider using StreamWriter to enhance write performance. StreamWriter persistently writes data to the database using a stream. Once the writing is complete, you should invoke the completed method to close the stream and await the database’s confirmation of write success.

TIP

Even though each WriteRows can only contain data from a single table, a StreamWrite instance can write multiple WriteRows simultaneously. This means that StreamWrite supports multi-table data import.

Write API

java

  1. /**
  2. * Write a single table multi rows data to database.
  3. *
  4. * @param rows rows with one table
  5. * @param ctx invoke context
  6. * @return write result
  7. */
  8. CompletableFuture<Result<WriteOk, Err>> write(WriteRows rows, Context ctx);
  9. /**
  10. * Create a streaming for write.
  11. *
  12. * @param maxPointsPerSecond The max number of points that can be written per second,
  13. * exceeding which may cause blockage.
  14. * @param ctx invoke context
  15. * @return a stream writer instance
  16. */
  17. StreamWriter<WriteRows, WriteOk> streamWriter(int maxPointsPerSecond, Context ctx);
NameDescription
rowsSeveral rows of data to write to the database (all data must belong to the same table).
ctxThe KV in ctx will be written to the gRPC headers metadata then sent to GreptimeDB server.
Result<WriteOk, Err>Inspired by Result in Rust, where WriteOk and Err only one is meaningful and the other is empty.If the call succeeds, you can extract the appropriate information from WriteOk, otherwise you need to extract useful information from Err.
maxPointsPerSecondThe max number of points that can be written per second, exceeding which may cause blockage.