feat(influxdb3): Add missing precision CLI option, fix and enhance write documentation.\

jstirnaman · jstirnaman · commit 7674012aed0d · 2025-07-08T19:38:44.000-05:00
- Verified precision behavior in source code. Added auto-detection note for all APIs: Added a note
  explaining that InfluxDB 3 uses timestamp magnitude to
  auto-detect precision by default, and users can specify
   precision to avoid ambiguity.
- Fix allowed precision values\
- Add examples
diff --git a/.claude/commands/analyze-api-source.md b/.claude/commands/analyze-api-source.md
@@ -0,0 +1,25 @@
+analyze-api-source:
+  <product_name> <endpoint_name> <parameter_name>
+
+  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.
diff --git 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
 ---
 
 <!--
-The content of this file is at content/shared/influxdb3-cli/write.md
+//SOURCE - content/shared/influxdb3-cli/write.md
 -->
diff --git a/content/shared/influxdb3-cli/write.md b/content/shared/influxdb3-cli/write.md
@@ -31,6 +31,7 @@ influxdb3 write [OPTIONS] --database <DATABASE_NAME> [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:
+
+<!--pytest.mark.skip--> 
+
+```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
@@ -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:
-
-- `ns` (nanoseconds)
-- `us` (microseconds)
-- `ms` (milliseconds)
-- `s` (seconds)
+> [!Tip]
+> By default, in CLI and HTTP API write requests, {{% product-name %}} uses the timestamp magnitude to auto-detect the precision.
+
+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
@@ -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
@@ -7,12 +7,18 @@ syntax as previous versions of InfluxDB, and supports the following:
 
 - `?accept_partial=<BOOLEAN>`: Accept or reject partial writes (default is `true`).
 - `?no_sync=<BOOLEAN>`: 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=<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
@@ -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."
-
-<!--
-ADD THIS BACK WHEN THE precision FLAG IS ADDED
-
-- The timestamp precision as seconds (`s`) using the `--precision` option
-
-  > [!Note]
-  > If no precision is provided, {{< product-name >}} attempts to auto-detect
-  > 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 %}}
