lujiajing1126 commented on a change in pull request #3: URL: https://github.com/apache/skywalking-banyandb-java-client/pull/3#discussion_r739989574
########## File path: README.md ########## @@ -10,6 +10,95 @@ The client implement for SkyWalking BanyanDB in Java. [](https://github.com/apache/skywalking-banyandb-java-client/actions?query=workflow%3ACI%2BAND%2BIT+event%3Aschedule+branch%main) +# Usage + +## Create a client + +Create a `BanyanDBClient` with host, port and a user-specified group and then establish a connection. + +```java +// use `default` group +client = new BanyanDBClient("127.0.0.1", 17912, "default"); +// establish a connection +client.connect(channel); +``` + +## Query + +Construct a `StreamQuery` instance with given time-range and other conditions. + +> Note: time-range is left-inclusive and right-exclusive. + +For example, + +```java +// [begin, end) = [ now - 15min, now ) +Instant end = Instant.now(); +Instant begin = end.minus(15, ChronoUnit.MINUTES); +// with stream schema, group=default, name=sw +StreamQuery query = new StreamQuery("sw", + new TimestampRange(begin.toEpochMilli(), end.toEpochMilli()), + // projection tags + Arrays.asList("state", "start_time", "duration", "trace_id")); +// search for all states +query.appendCondition(PairQueryCondition.LongQueryCondition.eq("searchable", "state" , 0L)); +// set order by condition +query.setOrderBy(new StreamQuery.OrderBy("duration", StreamQuery.OrderBy.Type.DESC)); +// send the query request +client.queryStreams(query); +``` + +After response is returned, `elements` can be fetched, + +```java +StreamQueryResponse resp = client.queryStreams(query); +List<RowEntity> entities = resp.getElements(); +``` + +where `RowEntity` is similar to the `java.sql.ResultSet` but not iterable. + +The `StreamQueryResponse`, `RowEntity`, `TagFamily` and `Tag` (i.e. `TagAndValue`) forms a hierarchical structure, where +the order of the tag families and containing tags, i.e. indexes of these objects in the List, follow the order specified +in the projection condition we've used in the request. + +## Write + +Since grpc bidi streaming is used for write protocol, build a `StreamBulkWriteProcessor` which would handle back-pressure for you. +Adjust `maxBulkSize`, `flushInterval` and `concurrency` of the consumer in different scenarios to meet requirements. + +```java +// build a StreamBulkWriteProcessor from client +StreamBulkWriteProcessor streamBulkWriteProcessor = client.buildStreamWriteProcessor(maxBulkSize, flushInterval, concurrency); Review comment: Sure. I've added several sentences to put emphasis on this problem ########## File path: README.md ########## @@ -10,6 +10,95 @@ The client implement for SkyWalking BanyanDB in Java. [](https://github.com/apache/skywalking-banyandb-java-client/actions?query=workflow%3ACI%2BAND%2BIT+event%3Aschedule+branch%main) +# Usage + +## Create a client + +Create a `BanyanDBClient` with host, port and a user-specified group and then establish a connection. + +```java +// use `default` group +client = new BanyanDBClient("127.0.0.1", 17912, "default"); +// establish a connection +client.connect(channel); +``` + +## Query + +Construct a `StreamQuery` instance with given time-range and other conditions. + +> Note: time-range is left-inclusive and right-exclusive. + +For example, + +```java +// [begin, end) = [ now - 15min, now ) +Instant end = Instant.now(); +Instant begin = end.minus(15, ChronoUnit.MINUTES); +// with stream schema, group=default, name=sw +StreamQuery query = new StreamQuery("sw", + new TimestampRange(begin.toEpochMilli(), end.toEpochMilli()), + // projection tags + Arrays.asList("state", "start_time", "duration", "trace_id")); +// search for all states +query.appendCondition(PairQueryCondition.LongQueryCondition.eq("searchable", "state" , 0L)); +// set order by condition +query.setOrderBy(new StreamQuery.OrderBy("duration", StreamQuery.OrderBy.Type.DESC)); +// send the query request +client.queryStreams(query); +``` + +After response is returned, `elements` can be fetched, + +```java +StreamQueryResponse resp = client.queryStreams(query); +List<RowEntity> entities = resp.getElements(); +``` + +where `RowEntity` is similar to the `java.sql.ResultSet` but not iterable. Review comment: Fixed -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
