chore(influxdb3-distrib): Recommend best practices for adjusting client timeouts when querying InfluxDB 3 distributed.

content/influxdb3/cloud-dedicated/query-data/execute-queries/client-libraries/python.md

@@ -26,6 +26,7 @@ related:
     - /influxdb3/cloud-dedicated/reference/influxql/
     - /influxdb3/cloud-dedicated/reference/sql/
     - /influxdb3/cloud-dedicated/query-data/execute-queries/troubleshoot/
+    - /influxdb3/cloud-dedicated/query-data/troubleshoot-and-optimize/query-timeout-best-practices/
 
 list_code_example: |
     ```py
@@ -240,7 +241,8 @@ from influxdb_client_3 import InfluxDBClient3
 client = InfluxDBClient3(
     host='{{< influxdb/host >}}',
     token='DATABASE_TOKEN',
-    database='DATABASE_NAME'
+    database='DATABASE_NAME',
+    timeout=60  # Set default timeout to 60 seconds
 )
 ```
 {{% /code-placeholders %}}
@@ -275,6 +277,7 @@ client = InfluxDBClient3(
 host="{{< influxdb/host >}}",
 token='DATABASE_TOKEN',
 database='DATABASE_NAME',
+timeout=60,  # Set default timeout to 60 seconds
 flight_client_options=flight_client_options(
 tls_root_certs=cert))
 ...
@@ -332,7 +335,8 @@ client = InfluxDBClient3(
 # Execute the query and return an Arrow table
 table = client.query(
     query="SELECT * FROM home",
-    language="sql"
+    language="sql",
+    timeout=30  # Override default timeout for simple queries (30 seconds)
 )
 
 print("\n#### View Schema information\n")
@@ -377,7 +381,8 @@ client = InfluxDBClient3(
 # Execute the query and return an Arrow table
 table = client.query(
     query="SELECT * FROM home",
-    language="influxql"
+    language="influxql",
+    timeout=30  # Override default timeout for simple queries (30 seconds)
 )
 
 print("\n#### View Schema information\n")

content/influxdb3/cloud-dedicated/query-data/execute-queries/influxctl-cli.md

@@ -13,6 +13,7 @@ influxdb3/cloud-dedicated/tags: [query, sql, influxql, influxctl, CLI]
 related:
   - /influxdb3/cloud-dedicated/reference/cli/influxctl/query/
   - /influxdb3/cloud-dedicated/get-started/query/#execute-an-sql-query, Get started querying data
+  - /influxdb3/cloud-dedicated/query-data/troubleshoot-and-optimize/query-timeout-best-practices/, Query timeout best practices
   - /influxdb3/cloud-dedicated/reference/sql/
   - /influxdb3/cloud-dedicated/reference/influxql/
 list_code_example: |
@@ -142,6 +143,34 @@ Replace the following:
 - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}:
   Name of the database to query
 
+## Query timeouts
+
+The [`influxctl --timeout` global flag](/influxdb3/cloud-dedicated/reference/cli/influxctl/) sets the maximum duration for API calls, including query requests.
+If a query takes longer than the specified timeout, the operation will be canceled.
+
+### Timeout examples
+
+Use different timeout values based on your query type:
+
+{{% code-placeholders "DATABASE_(TOKEN|NAME)" %}}
+```sh
+# Shorter timeout for testing dashboard queries (10 seconds)
+influxctl query \
+  --timeout 10s \
+  --token DATABASE_TOKEN \
+  --database DATABASE_NAME \
+  "SELECT AVG(temperature) FROM sensors WHERE time >= now() - INTERVAL '1 day'"
+
+# Longer timeout for analytical queries (5 minutes)
+influxctl query \
+  --timeout 5m \
+  --token DATABASE_TOKEN \
+  --database DATABASE_NAME \
+  "SELECT room, AVG(temperature) FROM sensors WHERE time >= now() - INTERVAL '30 days' GROUP BY room"
+```
+{{% /code-placeholders %}}
+
+For guidance on selecting appropriate timeout values, see [Query timeout best practices](/influxdb3/cloud-dedicated/query-data/troubleshoot-and-optimize/query-timeout-best-practices/).
 
 ## Output format
 
@@ -243,7 +272,7 @@ influxctl query \
 {{% /influxdb/custom-timestamps %}}
 
 {{< expand-wrapper >}}
-{{% expand "View example results with unix nanosecond timestamps" %}}
+{{% expand "View example results with Unix nanosecond timestamps" %}}
 {{% influxdb/custom-timestamps %}}
 ```
 +-------+--------+---------+------+---------------------+

content/influxdb3/cloud-dedicated/query-data/troubleshoot-and-optimize/query-timeout-best-practices.md

@@ -0,0 +1,10 @@
+---
+title: Query timeout best practices
+description: Learn how to set appropriate query timeouts to balance performance and resource protection.
+menu:
+  influxdb3_cloud_dedicated:
+    name: Query timeout best practices
+    parent: Troubleshoot and optimize queries
+weight: 205
+source: shared/influxdb3-query-guides/query-timeout-best-practices.md
+---

content/influxdb3/cloud-dedicated/query-data/troubleshoot-and-optimize/troubleshoot.md

@@ -12,6 +12,7 @@ related:
   - /influxdb3/cloud-dedicated/query-data/sql/
   - /influxdb3/cloud-dedicated/query-data/influxql/
   - /influxdb3/cloud-dedicated/reference/client-libraries/v3/
+  - /influxdb3/cloud-dedicated/query-data/troubleshoot-and-optimize/query-timeout-best-practices/
 aliases:
   - /influxdb3/cloud-dedicated/query-data/execute-queries/troubleshoot/
   - /influxdb3/cloud-dedicated/query-data/troubleshoot-and-optimize/trace/
@@ -30,7 +31,9 @@ If a query doesn't return any data, it might be due to the following:
 
 - Your data falls outside the time range (or other conditions) in the query--for example, the InfluxQL `SHOW TAG VALUES` command uses a default time range of 1 day.
 - The query (InfluxDB server) timed out.
-- The query client timed out.
+- The query client timed out. 
+  See [Query timeout best practices](/influxdb3/cloud-dedicated/query-data/troubleshoot-and-optimize/query-timeout-best-practices/) 
+  for guidance on setting appropriate timeouts.
 - The query return type is not supported by the client library.
   For example, array or list types may not be supported.
   In this case, use `array_to_string()` to convert the array value to a string--for example:

content/influxdb3/cloud-serverless/query-data/execute-queries/client-libraries/python.md

@@ -27,6 +27,7 @@ related:
     - /influxdb3/cloud-serverless/reference/influxql/
     - /influxdb3/cloud-serverless/reference/sql/
     - /influxdb3/cloud-serverless/query-data/execute-queries/troubleshoot/
+    - /influxdb3/cloud-serverless/query-data/troubleshoot-and-optimize/query-timeout-best-practices/
 
 list_code_example: |
     ```py
@@ -241,7 +242,8 @@ from influxdb_client_3 import InfluxDBClient3
 client = InfluxDBClient3(
     host='{{< influxdb/host >}}',
     token='API_TOKEN',
-    database='BUCKET_NAME'
+    database='BUCKET_NAME',
+    timeout=30  # Set default timeout to 30 seconds for serverless
 )
 ```
 {{% /code-placeholders %}}
@@ -332,7 +334,8 @@ client = InfluxDBClient3(
 # Execute the query and return an Arrow table
 table = client.query(
     query="SELECT * FROM home",
-    language="sql"
+    language="sql",
+    timeout=10  # Override default timeout for simple queries (10 seconds)
 )
 
 print("\n#### View Schema information\n")
@@ -377,7 +380,8 @@ client = InfluxDBClient3(
 # Execute the query and return an Arrow table
 table = client.query(
     query="SELECT * FROM home",
-    language="influxql"
+    language="influxql",
+    timeout=10  # Override default timeout for simple queries (10 seconds)
 )
 
 print("\n#### View Schema information\n")

content/influxdb3/cloud-serverless/query-data/troubleshoot-and-optimize/query-timeout-best-practices.md

@@ -0,0 +1,11 @@
+---
+title: Query timeout best practices
+description: Learn how to set appropriate query timeouts to balance performance and resource protection.
+menu:
+  influxdb3_cloud_serverless:
+    name: Query timeout best practices
+    parent: Troubleshoot and optimize queries
+    identifier: query-timeout-best-practices
+weight: 201
+source: shared/influxdb3-query-guides/query-timeout-best-practices.md
+---

content/influxdb3/cloud-serverless/query-data/troubleshoot-and-optimize/troubleshoot.md

@@ -12,6 +12,7 @@ related:
   - /influxdb3/cloud-serverless/query-data/sql/
   - /influxdb3/cloud-serverless/query-data/influxql/
   - /influxdb3/cloud-serverless/reference/client-libraries/v3/
+  - /influxdb3/cloud-serverless/query-data/troubleshoot-and-optimize/query-timeout-best-practices/
 aliases:
   - /influxdb3/cloud-serverless/query-data/execute-queries/troubleshoot/
 ---
@@ -29,7 +30,9 @@ If a query doesn't return any data, it might be due to the following:
 
 - Your data falls outside the time range (or other conditions) in the query--for example, the InfluxQL `SHOW TAG VALUES` command uses a default time range of 1 day.
 - The query (InfluxDB server) timed out.
-- The query client timed out.
+- The query client timed out. 
+  See [Query timeout best practices](/influxdb3/cloud-serverless/query-data/troubleshoot-and-optimize/query-timeout-best-practices/) 
+  for guidance on setting appropriate timeouts.
 - The query return type is not supported by the client library.
   For example, array or list types may not be supported.
   In this case, use `array_to_string()` to convert the array value to a string--for example:

content/influxdb3/clustered/query-data/execute-queries/client-libraries/python.md

@@ -20,6 +20,7 @@ related:
     - /influxdb3/clustered/query-data/sql/
     - /influxdb3/clustered/reference/influxql/
     - /influxdb3/clustered/reference/sql/
+    - /influxdb3/clustered/query-data/troubleshoot-and-optimize/query-timeout-best-practices/
 
 list_code_example: |
     ```py
@@ -234,7 +235,8 @@ from influxdb_client_3 import InfluxDBClient3
 client = InfluxDBClient3(
     host='{{< influxdb/host >}}',
     token='DATABASE_TOKEN',
-    database='DATABASE_NAME'
+    database='DATABASE_NAME',
+    timeout=60  # Set default timeout to 60 seconds
 )
 ```
 {{% /code-placeholders %}}
@@ -325,7 +327,8 @@ client = InfluxDBClient3(
 # Execute the query and return an Arrow table
 table = client.query(
     query="SELECT * FROM home",
-    language="sql"
+    language="sql",
+    timeout=30  # Override default timeout for simple queries (30 seconds)
 )
 
 print("\n#### View Schema information\n")
@@ -370,7 +373,8 @@ client = InfluxDBClient3(
 # Execute the query and return an Arrow table
 table = client.query(
     query="SELECT * FROM home",
-    language="influxql"
+    language="influxql",
+    timeout=30  # Override default timeout for simple queries (30 seconds)
 )
 
 print("\n#### View Schema information\n")

content/influxdb3/clustered/query-data/execute-queries/influxctl-cli.md

@@ -12,6 +12,7 @@ influxdb3/clustered/tags: [query, sql, influxql, influxctl, CLI]
 related:
   - /influxdb3/clustered/reference/cli/influxctl/query/
   - /influxdb3/clustered/get-started/query/#execute-an-sql-query, Get started querying data
+  - /influxdb3/clustered/query-data/troubleshoot-and-optimize/query-timeout-best-practices/, Query timeout best practices
   - /influxdb3/clustered/reference/sql/
   - /influxdb3/clustered/reference/influxql/
 list_code_example: |
@@ -141,6 +142,35 @@ Replace the following:
 - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}:
   Name of the database to query
 
+## Query timeouts
+
+The [`influxctl --timeout` global flag](/influxdb3/clustered/reference/cli/influxctl/) sets the maximum duration for API calls, including query requests.
+If a query takes longer than the specified timeout, the operation will be canceled.
+
+### Timeout examples
+
+Use different timeout values based on your query type:
+
+{{% code-placeholders "DATABASE_(TOKEN|NAME)" %}}
+```sh
+# Shorter timeout for testing dashboard queries (10 seconds)
+influxctl query \
+  --timeout 10s \
+  --token DATABASE_TOKEN \
+  --database DATABASE_NAME \
+  "SELECT * FROM sensors WHERE time >= now() - INTERVAL '1 hour' LIMIT 100"
+
+# Longer timeout for analytical queries (5 minutes)
+influxctl query \
+  --timeout 300s \
+  --token DATABASE_TOKEN \
+  --database DATABASE_NAME \
+  "SELECT room, AVG(temperature) FROM sensors WHERE time >= now() - INTERVAL '30 days' GROUP BY room"
+```
+{{% /code-placeholders %}}
+
+For guidance on selecting appropriate timeout values, see [Query timeout best practices](/influxdb3/clustered/query-data/troubleshoot-and-optimize/query-timeout-best-practices/).
+
 ## Output format
 
 The `influxctl query` command supports the following output formats:
@@ -241,7 +271,7 @@ influxctl query \
 {{% /influxdb/custom-timestamps %}}
 
 {{< expand-wrapper >}}
-{{% expand "View example results with unix nanosecond timestamps" %}}
+{{% expand "View example results with Unix nanosecond timestamps" %}}
 {{% influxdb/custom-timestamps %}}
 ```
 +-------+--------+---------+------+---------------------+

content/influxdb3/clustered/query-data/troubleshoot-and-optimize/query-timeout-best-practices.md

@@ -0,0 +1,11 @@
+---
+title: Query timeout best practices
+description: Learn how to set appropriate query timeouts to balance performance and resource protection.
+menu:
+  influxdb3_clustered:
+    name: Query timeout best practices
+    parent: Troubleshoot and optimize queries
+    identifier: query-timeout-best-practices
+weight: 201
+source: shared/influxdb3-query-guides/query-timeout-best-practices.md
+---

content/influxdb3/clustered/query-data/troubleshoot-and-optimize/troubleshoot.md

@@ -12,6 +12,7 @@ related:
   - /influxdb3/clustered/query-data/sql/
   - /influxdb3/clustered/query-data/influxql/
   - /influxdb3/clustered/reference/client-libraries/v3/
+  - /influxdb3/clustered/query-data/troubleshoot-and-optimize/query-timeout-best-practices/
 aliases:
   - /influxdb3/clustered/query-data/execute-queries/troubleshoot/
 ---
@@ -29,7 +30,9 @@ If a query doesn't return any data, it might be due to the following:
 
 - Your data falls outside the time range (or other conditions) in the query--for example, the InfluxQL `SHOW TAG VALUES` command uses a default time range of 1 day.
 - The query (InfluxDB server) timed out.
-- The query client timed out.
+- The query client timed out. 
+  See [Query timeout best practices](/influxdb3/clustered/query-data/troubleshoot-and-optimize/query-timeout-best-practices/) 
+  for guidance on setting appropriate timeouts.
 - The query return type is not supported by the client library.
   For example, array or list types may not be supported.
   In this case, use `array_to_string()` to convert the array value to a string--for example: