diff --git a/.claude/commands/analyze-api-source.md b/.claude/commands/analyze-api-source.md new file mode 100644 index 000000000..32b651001 --- /dev/null +++ b/.claude/commands/analyze-api-source.md @@ -0,0 +1,25 @@ +analyze-api-source: + + + Analyze source code in the specified repo to determine: + 1. HTTP method and endpoint path + 2. Parameters for the given endpoint + 3. Whether the specified parameter is supported for the given API endpoint + 4. Parameter format, valid values, and default behavior + 5. Any limitations or quirks of the parameter + +For product InfluxDB 3 Core and Enterprise, + Search repo influxdata/influxdb + Search through: + - HTTP endpoint handlers in + influxdb3_server/src/http/ + - Parameter structs and deserialization + - Request routing and processing logic + - Type definitions in influxdb3_types/src/ + + In the output, provide: + - Comparison across v1, v2, and v3 API compatibility + +In the output, provide: + Concrete examples of endpoint and parameter usage + Cite specific source code locations. \ No newline at end of file diff --git a/content/influxdb3/core/reference/cli/influxdb3/write.md b/content/influxdb3/core/reference/cli/influxdb3/write.md index 0055d62a8..54e79dc2e 100644 --- a/content/influxdb3/core/reference/cli/influxdb3/write.md +++ b/content/influxdb3/core/reference/cli/influxdb3/write.md @@ -11,5 +11,5 @@ source: /shared/influxdb3-cli/write.md --- diff --git a/content/shared/influxdb3-cli/write.md b/content/shared/influxdb3-cli/write.md index 3ffcd0c4e..c19242f6f 100644 --- a/content/shared/influxdb3-cli/write.md +++ b/content/shared/influxdb3-cli/write.md @@ -31,6 +31,7 @@ influxdb3 write [OPTIONS] --database [LINE_PROTOCOL]... | | `--token` | _({{< req >}})_ Authentication token | | `-f` | `--file` | A file that contains line protocol to write | | | `--accept-partial` | Accept partial writes | +| | `--precision` | Precision of data timestamps (`ns`, `us`, `ms`, or `s`) | | | | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | `-h` | `--help` | Print help information | | | `--help-all` | Print detailed help information | @@ -144,4 +145,22 @@ cat ./data.lp | influxdb3 write \ {{% /code-tab-content %}} {{< /code-tabs-wrapper >}} +## Write line protocol with specific timestamp precision + +By default, in CLI and HTTP API write requests, {{% product-name %}} uses the timestamp magnitude to auto-detect the precision. +To avoid any ambiguity, specify the `--precision {ns|us|ms|s}` option: + + + +```bash +influxdb3 write \ + --database DATABASE_NAME \ + --token AUTH_TOKEN \ + --precision s \ + 'home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000 +home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000 +home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1641027600 +home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600 +' +``` {{% /code-placeholders %}} diff --git a/content/shared/influxdb3-write-guides/best-practices/optimize-writes.md b/content/shared/influxdb3-write-guides/best-practices/optimize-writes.md index 2441b414e..fe7dd9da6 100644 --- a/content/shared/influxdb3-write-guides/best-practices/optimize-writes.md +++ b/content/shared/influxdb3-write-guides/best-practices/optimize-writes.md @@ -84,15 +84,17 @@ if your data isn't collected in nanoseconds, there is no need to write at that p For better performance, use the coarsest timestamp precision you can for your use case. -By default, {{< product-name >}} attempts to auto-detect the precision of -timestamps in line protocol by identifying what precision would be relatively -close to "now." You can also specify your timestamp precision in your write -request. {{< product-name >}} supports the following timestamp precisions: +> [!Tip] +> By default, in CLI and HTTP API write requests, {{% product-name %}} uses the timestamp magnitude to auto-detect the precision. -- `ns` (nanoseconds) -- `us` (microseconds) -- `ms` (milliseconds) -- `s` (seconds) +To specify the precision of timestamps in your write +request, pass the `precision` option. + +For more information, see the following: + +- [`/api/v3/write_lp` endpoint parameters](/influxdb3/version/write-data/http-api/v3-write-lp/) +- [`/api/v2/write` v2 API endpoint parameters](/influxdb3/version/write-data/http-api/compatibility-apis/#v2-api-write-parameters) +- [`/write` v1 API endpoint parameters](/influxdb3/version/write-data/http-api/compatibility-apis/#v1-api-write-parameters) ## Use gzip compression diff --git a/content/shared/influxdb3-write-guides/http-api/compatibility-apis.md b/content/shared/influxdb3-write-guides/http-api/compatibility-apis.md index fc7dfa6ed..5f7b82102 100644 --- a/content/shared/influxdb3-write-guides/http-api/compatibility-apis.md +++ b/content/shared/influxdb3-write-guides/http-api/compatibility-apis.md @@ -75,6 +75,10 @@ Parameter | Allowed in | Ignored | Value #### Timestamp precision {#timestamp-precision-v2} +> [!Note] +> By default, {{% product-name %}} uses the timestamp magnitude to auto-detect the precision. +> To avoid any ambiguity, you can specify the precision of timestamps in your data. + Use one of the following `precision` values in v2 API `/api/v2/write` requests: - `ns`: nanoseconds @@ -224,6 +228,10 @@ Parameter | Allowed in | Ignored | Value #### Timestamp precision {#timestamp-precision-v1} +> [!Note] +> By default, {{% product-name %}} uses the timestamp magnitude to auto-detect the precision. +> To avoid any ambiguity, you can specify the precision of timestamps in your data. + Use one of the following `precision` values in v1 API `/write` requests: - `ns`: nanoseconds diff --git a/content/shared/influxdb3-write-guides/http-api/v3-write-lp.md b/content/shared/influxdb3-write-guides/http-api/v3-write-lp.md index ec00bb4c2..477b3bb2a 100644 --- a/content/shared/influxdb3-write-guides/http-api/v3-write-lp.md +++ b/content/shared/influxdb3-write-guides/http-api/v3-write-lp.md @@ -7,12 +7,18 @@ syntax as previous versions of InfluxDB, and supports the following: - `?accept_partial=`: Accept or reject partial writes (default is `true`). - `?no_sync=`: Control when writes are acknowledged: - - `no_sync=true`: Acknowledge writes before WAL persistence completes. + - `no_sync=true`: Acknowledges writes before WAL persistence completes. - `no_sync=false`: Acknowledges writes after WAL persistence completes (default). - `?precision=`: Specify the precision of the timestamp. - The default is `ns` (nanosecond) precision. - You can also use `auto` to let InfluxDB automatically determine the timestamp - precision by identifying which precisions resolves most closely to _now_. + By default, {{% product-name %}} uses the timestamp magnitude to auto-detect the precision. + To avoid any ambiguity, you can specify the precision of timestamps in your data. + + The {{< product-name >}} `/api/v3/write_lp` API endpoint supports the following timestamp precisions: + + - `ns` (nanoseconds) + - `us` (microseconds) + - `ms` (milliseconds) + - `s` (seconds) ##### Request body @@ -25,7 +31,7 @@ the {{< influxdb3/home-sample-link >}}, but you can use any HTTP client._ {{% influxdb/custom-timestamps %}} ```bash -curl -v "http://{{< influxdb/host >}}/api/v3/write_lp?db=sensors&precision=auto" \ +curl -v "http://{{< influxdb/host >}}/api/v3/write_lp?db=sensors&precision=s" \ --data-raw "home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1735545600 home,room=Kitchen temp=21.0,hum=35.9,co=0i 1735545600 home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1735549200 diff --git a/content/shared/influxdb3-write-guides/influxdb3-cli.md b/content/shared/influxdb3-write-guides/influxdb3-cli.md index 11aa37b35..88594efb7 100644 --- a/content/shared/influxdb3-write-guides/influxdb3-cli.md +++ b/content/shared/influxdb3-write-guides/influxdb3-cli.md @@ -73,19 +73,8 @@ Provide the following: - from stdin > [!Note] -> {{< product-name >}} auto-detects the timestamp precision by identifying which -> precision results in timestamps relatively close to "now." - - +> By default, {{% product-name %}} uses the timestamp magnitude to auto-detect the precision. +> To specify the precision of timestamps in your data, use the [`--precision {ns|us|ms|s}` option](/influxdb3/version/reference/cli/influxdb3/write/#options). {{< tabs-wrapper >}} {{% tabs %}} diff --git a/lefthook.yml b/lefthook.yml index e3176dc6b..c7c36c0de 100644 --- a/lefthook.yml +++ b/lefthook.yml @@ -137,13 +137,13 @@ pre-push: tags: test,codeblocks,v2 env: SERVICE: cloud-pytest - run: yarn test:codeblocks:cloud '{push_files}' + run: yarn test:codeblocks:cloud '{staged_files}' cloud-dedicated-pytest: tags: test,codeblocks,v3 glob: content/influxdb3/cloud-dedicated/*.md run: | - yarn test:codeblocks:cloud-dedicated '{push_files}' && + yarn test:codeblocks:cloud-dedicated '{staged_files}' && ./test/scripts/monitor-tests.sh stop cloud-dedicated-pytest cloud-serverless-pytest: @@ -151,13 +151,13 @@ pre-push: glob: content/influxdb3/cloud-serverless/*.md env: SERVICE: cloud-serverless-pytest - run: yarn test:codeblocks:cloud-serverless '{push_files}' + run: yarn test:codeblocks:cloud-serverless '{staged_files}' clustered-pytest: tags: test,codeblocks,v3 glob: content/influxdb3/clustered/*.md run: | - yarn test:codeblocks:clustered '{push_files}' && + yarn test:codeblocks:clustered '{staged_files}' && ./test/scripts/monitor-tests.sh stop clustered-pytest telegraf-pytest: @@ -165,11 +165,11 @@ pre-push: glob: content/telegraf/*.md env: SERVICE: telegraf-pytest - run: yarn test:codeblocks:telegraf '{push_files}' + run: yarn test:codeblocks:telegraf '{staged_files}' v2-pytest: tags: test,codeblocks,v2 glob: content/influxdb/v2/*.md env: SERVICE: v2-pytest - run: yarn test:codeblocks:v2 '{push_files}' \ No newline at end of file + run: yarn test:codeblocks:v2 '{staged_files}' \ No newline at end of file