wu-sheng commented on a change in pull request #3: URL: https://github.com/apache/skywalking-banyandb-java-client/pull/3#discussion_r739986618
########## 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: We should be clear, this process should be reused and thread safe, right? -- 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]
