Skip to content

Commit

Permalink
docs: updates CHANGELOG.md a recent javadoc.
Browse files Browse the repository at this point in the history
  • Loading branch information
karel-rehor committed Jul 15, 2024
1 parent a8094e5 commit 92295f9
Show file tree
Hide file tree
Showing 2 changed files with 32 additions and 25 deletions.
26 changes: 12 additions & 14 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,28 +1,26 @@
## 7.2.0 [unreleased]

### Breaking Changes

#### InfluxQLQuery default timestamp

The default timestamp returned by `InfluxQLQueryAPI.query()` is no longer in the POSIX epoch format. It is now in the RFC3339 format. The Epoch format is still supported. It is sufficient to add the `epoch` query parameter to a query request via `InfluxQLQuery.setPrecision()` or to use a new dedicated CSV query method, `InfluxQLQueryAPI.queryCSV()`.

See header changes in features below.

### Features

- [#719](https://github.com/influxdata/influxdb-client-java/issues/719): `InfluxQLQueryService` header changes.
- Now uses `Accept` header with the value `application/json` by default.
- The `Accept` header for InfluxQLQuery calls can now be set dynamically as either `application/json` or `application/csv`.
- `Accept` header can now be defined when making `InfluxQLQuery` calls. Supoorted MIME types:
- `application/csv`
- `application/json`
- The value `application/csv` remains the default.
- :warning: Side effects of these changes:
- When using `application/json` timestamp fields are returned in the [RFC3339](https://www.rfc-editor.org/rfc/rfc3339) format.
- When using `application/csv` timestamp fields are returned in the POSIX epoch format.
- Convenience methods have been added to `InfluxQLQueryAPI` to simplify using CSV if desired.
- When using `application/json`, timestamp fields are returned in the [RFC3339](https://www.rfc-editor.org/rfc/rfc3339) format unless `InfluxQLQuery.setPrecision()` has been previously called, in which case they are returned in the POSIX epoch format.
- When using `application/csv`, timestamp fields are returned in the POSIX epoch format.
- Convenience methods have been added to `InfluxQLQueryAPI` to simplify expressly specifying JSON or CSV calls.
- Epoch timestamps can also be ensured by calling `InfluxQLQuery.setPrecision()` before executing a query call.
- An `AcceptHeader` field has also been added to the `InfluxQLQuery` class and can be set with `InfluxQLQuery.setAcceptHeader()`.
- More information from the server side:
- [Generated REST API Documentation](https://docs.influxdata.com/influxdb/v2/api/v1-compatibility/#operation/PostQueryV1)
- [Influx 1.1 query compatibility](https://docs.influxdata.com/influxdb/latest/reference/api/influxdb-1x/query/)
- See the updated InfluxQLExample
- See the updated InfluxQLExample

### Bug Fixes

1. [#744](https://github.com/influxdata/influxdb-client-java/issues/744) following an `InfluxQLQueryAPI.query()` call, empty results from the server no longer result in a `null` result value.

### Dependencies

Expand Down
31 changes: 20 additions & 11 deletions client/src/main/java/com/influxdb/client/InfluxQLQueryApi.java
Original file line number Diff line number Diff line change
Expand Up @@ -34,19 +34,28 @@
* <strong>{@link InfluxQLQuery#getRetentionPolicy() retention policy}</strong> specified in the query request to
* map the request to an InfluxDB bucket.
*
* <p>Note that as of release 7.2 queries using the legacy <code>InfluxQL</code> compatible endpoint, will use
* the default <code>Accept</code> header mime type of <code>application/json</code> instead of the previous
* mime type of <code>application/csv</code>. This means timestamps will be returned in the RFC3339 format,
* e.g. <code>"2024-06-18T11:29:48.454Z"</code> instead of in the Epoch format, e.g. <code>1655900000000000000</code>.
* </p>
* <p>Note that as of release 7.2 queries using the legacy <code>InfluxQL</code> compatible endpoint can specify
* the <code>Accept</code> header MIME type. Two MIME types are supported. </p>
* <ul>
* <li><code>application/csv</code> - client default and legacy value.</li>
* <li><code>application/json</code></li>
* </ul>
*
* <p>To continue to use the <code>application/csv</code> mime type and to receive Epoch timestamps, use a
* new convenience method <code>queryCSV</code>. To explicitly indicate use of the <code>application/json</code>
* mime type additional convenience methods <code>queryJSON</code> are also now available. These are synonymous
* with the original <code>query</code> methods.</p>
* <p>The selected <code>Accept</code> header mime type impacts the timestamp format returned from the server.</p>
* <ul>
* <li><code>application/csv</code> returns timestamps in the POSIX epoch format.</li>
* <li><code>application/json</code> returns timestamps as RFC3339 strings.
* <ul>
* <li>Caveat. If <code>InfluxQLQuery.setPrecision()</code> is called before the query is sent, then
* the timestamp will be returned as a POSIX epoch reflecting the desired precision, even when using the
* <code>application/json</code> MIME type.</li>
* </ul>
* </li>
* </ul>
*
* <p>Note that the <code>Accept</code> header mime type can now also be specified when instantiating the
*{@link com.influxdb.client.domain.InfluxQLQuery} class.</p>
* <p>To explicitly choose one or the other MIME type new convenience methods are povided: <code>queryCSV</code>
* and <code>queryJSON</code>. Note that the <code>Accept</code> header MIME type can now also be specified
* when instantiating the {@link com.influxdb.client.domain.InfluxQLQuery} class.</p>
*
* <br>
* For more information, see:
Expand Down

0 comments on commit 92295f9

Please sign in to comment.