Skip to content

Commit 7de4b11

Browse files
jstirnamanjstirnaman
authored
Merge pull request #6294 from influxdata/jts-dar-526-clustered-timeouts
chore(influxdb3-distrib): Recommend best practices for adjusting client timeouts when querying InfluxDB 3 distributed.
2 parents aaad37b + a97cbf8 commit 7de4b11

File tree

12 files changed

+448
-14
lines changed

12 files changed

+448
-14
lines changed

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

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ related:
2626
- /influxdb3/cloud-dedicated/reference/influxql/
2727
- /influxdb3/cloud-dedicated/reference/sql/
2828
- /influxdb3/cloud-dedicated/query-data/execute-queries/troubleshoot/
29+
- /influxdb3/cloud-dedicated/query-data/troubleshoot-and-optimize/query-timeout-best-practices/
2930

3031
list_code_example: |
3132
```py
@@ -240,7 +241,8 @@ from influxdb_client_3 import InfluxDBClient3
240241
client = InfluxDBClient3(
241242
host='{{< influxdb/host >}}',
242243
token='DATABASE_TOKEN',
243-
database='DATABASE_NAME'
244+
database='DATABASE_NAME',
245+
timeout=60 # Set default timeout to 60 seconds
244246
)
245247
```
246248
{{% /code-placeholders %}}
@@ -275,6 +277,7 @@ client = InfluxDBClient3(
275277
host="{{< influxdb/host >}}",
276278
token='DATABASE_TOKEN',
277279
database='DATABASE_NAME',
280+
timeout=60, # Set default timeout to 60 seconds
278281
flight_client_options=flight_client_options(
279282
tls_root_certs=cert))
280283
...
@@ -332,7 +335,8 @@ client = InfluxDBClient3(
332335
# Execute the query and return an Arrow table
333336
table = client.query(
334337
query="SELECT * FROM home",
335-
language="sql"
338+
language="sql",
339+
timeout=30 # Override default timeout for simple queries (30 seconds)
336340
)
337341
338342
print("\n#### View Schema information\n")
@@ -377,7 +381,8 @@ client = InfluxDBClient3(
377381
# Execute the query and return an Arrow table
378382
table = client.query(
379383
query="SELECT * FROM home",
380-
language="influxql"
384+
language="influxql",
385+
timeout=30 # Override default timeout for simple queries (30 seconds)
381386
)
382387
383388
print("\n#### View Schema information\n")

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

Lines changed: 30 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ influxdb3/cloud-dedicated/tags: [query, sql, influxql, influxctl, CLI]
1313
related:
1414
- /influxdb3/cloud-dedicated/reference/cli/influxctl/query/
1515
- /influxdb3/cloud-dedicated/get-started/query/#execute-an-sql-query, Get started querying data
16+
- /influxdb3/cloud-dedicated/query-data/troubleshoot-and-optimize/query-timeout-best-practices/, Query timeout best practices
1617
- /influxdb3/cloud-dedicated/reference/sql/
1718
- /influxdb3/cloud-dedicated/reference/influxql/
1819
list_code_example: |
@@ -142,6 +143,34 @@ Replace the following:
142143
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}:
143144
Name of the database to query
144145

146+
## Query timeouts
147+
148+
The [`influxctl --timeout` global flag](/influxdb3/cloud-dedicated/reference/cli/influxctl/) sets the maximum duration for API calls, including query requests.
149+
If a query takes longer than the specified timeout, the operation will be canceled.
150+
151+
### Timeout examples
152+
153+
Use different timeout values based on your query type:
154+
155+
{{% code-placeholders "DATABASE_(TOKEN|NAME)" %}}
156+
```sh
157+
# Shorter timeout for testing dashboard queries (10 seconds)
158+
influxctl query \
159+
--timeout 10s \
160+
--token DATABASE_TOKEN \
161+
--database DATABASE_NAME \
162+
"SELECT AVG(temperature) FROM sensors WHERE time >= now() - INTERVAL '1 day'"
163+
164+
# Longer timeout for analytical queries (5 minutes)
165+
influxctl query \
166+
--timeout 5m \
167+
--token DATABASE_TOKEN \
168+
--database DATABASE_NAME \
169+
"SELECT room, AVG(temperature) FROM sensors WHERE time >= now() - INTERVAL '30 days' GROUP BY room"
170+
```
171+
{{% /code-placeholders %}}
172+
173+
For guidance on selecting appropriate timeout values, see [Query timeout best practices](/influxdb3/cloud-dedicated/query-data/troubleshoot-and-optimize/query-timeout-best-practices/).
145174

146175
## Output format
147176

@@ -243,7 +272,7 @@ influxctl query \
243272
{{% /influxdb/custom-timestamps %}}
244273

245274
{{< expand-wrapper >}}
246-
{{% expand "View example results with unix nanosecond timestamps" %}}
275+
{{% expand "View example results with Unix nanosecond timestamps" %}}
247276
{{% influxdb/custom-timestamps %}}
248277
```
249278
+-------+--------+---------+------+---------------------+

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

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
title: Query timeout best practices
3+
description: Learn how to set appropriate query timeouts to balance performance and resource protection.
4+
menu:
5+
influxdb3_cloud_dedicated:
6+
name: Query timeout best practices
7+
parent: Troubleshoot and optimize queries
8+
weight: 205
9+
related:
10+
- /influxdb3/cloud-dedicated/reference/client-libraries/v3/
11+
- /influxdb3/cloud-dedicated/query-data/execute-queries/influxctl-cli/
12+
source: shared/influxdb3-query-guides/query-timeout-best-practices.md
13+
---
14+
15+
<!--
16+
//SOURCE - content/shared/influxdb3-query-guides/query-timeout-best-practices.md
17+
>

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

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ related:
1212
- /influxdb3/cloud-dedicated/query-data/sql/
1313
- /influxdb3/cloud-dedicated/query-data/influxql/
1414
- /influxdb3/cloud-dedicated/reference/client-libraries/v3/
15+
- /influxdb3/cloud-dedicated/query-data/troubleshoot-and-optimize/query-timeout-best-practices/
1516
aliases:
1617
- /influxdb3/cloud-dedicated/query-data/execute-queries/troubleshoot/
1718
- /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:
3031

3132
- 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.
3233
- The query (InfluxDB server) timed out.
33-
- The query client timed out.
34+
- The query client timed out.
35+
See [Query timeout best practices](/influxdb3/cloud-dedicated/query-data/troubleshoot-and-optimize/query-timeout-best-practices/)
36+
for guidance on setting appropriate timeouts.
3437
- The query return type is not supported by the client library.
3538
For example, array or list types may not be supported.
3639
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

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ related:
2727
- /influxdb3/cloud-serverless/reference/influxql/
2828
- /influxdb3/cloud-serverless/reference/sql/
2929
- /influxdb3/cloud-serverless/query-data/execute-queries/troubleshoot/
30+
- /influxdb3/cloud-serverless/query-data/troubleshoot-and-optimize/query-timeout-best-practices/
3031

3132
list_code_example: |
3233
```py
@@ -241,7 +242,8 @@ from influxdb_client_3 import InfluxDBClient3
241242
client = InfluxDBClient3(
242243
host='{{< influxdb/host >}}',
243244
token='API_TOKEN',
244-
database='BUCKET_NAME'
245+
database='BUCKET_NAME',
246+
timeout=30 # Set default timeout to 30 seconds for serverless
245247
)
246248
```
247249
{{% /code-placeholders %}}
@@ -332,7 +334,8 @@ client = InfluxDBClient3(
332334
# Execute the query and return an Arrow table
333335
table = client.query(
334336
query="SELECT * FROM home",
335-
language="sql"
337+
language="sql",
338+
timeout=10 # Override default timeout for simple queries (10 seconds)
336339
)
337340
338341
print("\n#### View Schema information\n")
@@ -377,7 +380,8 @@ client = InfluxDBClient3(
377380
# Execute the query and return an Arrow table
378381
table = client.query(
379382
query="SELECT * FROM home",
380-
language="influxql"
383+
language="influxql",
384+
timeout=10 # Override default timeout for simple queries (10 seconds)
381385
)
382386
383387
print("\n#### View Schema information\n")

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

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
title: Query timeout best practices
3+
description: Learn how to set appropriate query timeouts to balance performance and resource protection.
4+
menu:
5+
influxdb3_cloud_serverless:
6+
name: Query timeout best practices
7+
parent: Troubleshoot and optimize queries
8+
identifier: query-timeout-best-practices
9+
weight: 201
10+
related:
11+
- /influxdb3/cloud-serverless/reference/client-libraries/v3/
12+
source: shared/influxdb3-query-guides/query-timeout-best-practices.md
13+
---
14+
15+
<!--
16+
//SOURCE - content/shared/influxdb3-query-guides/query-timeout-best-practices.md
17+
>

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

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ related:
1212
- /influxdb3/cloud-serverless/query-data/sql/
1313
- /influxdb3/cloud-serverless/query-data/influxql/
1414
- /influxdb3/cloud-serverless/reference/client-libraries/v3/
15+
- /influxdb3/cloud-serverless/query-data/troubleshoot-and-optimize/query-timeout-best-practices/
1516
aliases:
1617
- /influxdb3/cloud-serverless/query-data/execute-queries/troubleshoot/
1718
---
@@ -29,7 +30,9 @@ If a query doesn't return any data, it might be due to the following:
2930

3031
- 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.
3132
- The query (InfluxDB server) timed out.
32-
- The query client timed out.
33+
- The query client timed out.
34+
See [Query timeout best practices](/influxdb3/cloud-serverless/query-data/troubleshoot-and-optimize/query-timeout-best-practices/)
35+
for guidance on setting appropriate timeouts.
3336
- The query return type is not supported by the client library.
3437
For example, array or list types may not be supported.
3538
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

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ related:
2020
- /influxdb3/clustered/query-data/sql/
2121
- /influxdb3/clustered/reference/influxql/
2222
- /influxdb3/clustered/reference/sql/
23+
- /influxdb3/clustered/query-data/troubleshoot-and-optimize/query-timeout-best-practices/
2324

2425
list_code_example: |
2526
```py
@@ -234,7 +235,8 @@ from influxdb_client_3 import InfluxDBClient3
234235
client = InfluxDBClient3(
235236
host='{{< influxdb/host >}}',
236237
token='DATABASE_TOKEN',
237-
database='DATABASE_NAME'
238+
database='DATABASE_NAME',
239+
timeout=60 # Set default timeout to 60 seconds
238240
)
239241
```
240242
{{% /code-placeholders %}}
@@ -325,7 +327,8 @@ client = InfluxDBClient3(
325327
# Execute the query and return an Arrow table
326328
table = client.query(
327329
query="SELECT * FROM home",
328-
language="sql"
330+
language="sql",
331+
timeout=30 # Override default timeout for simple queries (30 seconds)
329332
)
330333
331334
print("\n#### View Schema information\n")
@@ -370,7 +373,8 @@ client = InfluxDBClient3(
370373
# Execute the query and return an Arrow table
371374
table = client.query(
372375
query="SELECT * FROM home",
373-
language="influxql"
376+
language="influxql",
377+
timeout=30 # Override default timeout for simple queries (30 seconds)
374378
)
375379
376380
print("\n#### View Schema information\n")

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

Lines changed: 31 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ influxdb3/clustered/tags: [query, sql, influxql, influxctl, CLI]
1212
related:
1313
- /influxdb3/clustered/reference/cli/influxctl/query/
1414
- /influxdb3/clustered/get-started/query/#execute-an-sql-query, Get started querying data
15+
- /influxdb3/clustered/query-data/troubleshoot-and-optimize/query-timeout-best-practices/, Query timeout best practices
1516
- /influxdb3/clustered/reference/sql/
1617
- /influxdb3/clustered/reference/influxql/
1718
list_code_example: |
@@ -141,6 +142,35 @@ Replace the following:
141142
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}:
142143
Name of the database to query
143144

145+
## Query timeouts
146+
147+
The [`influxctl --timeout` global flag](/influxdb3/clustered/reference/cli/influxctl/) sets the maximum duration for API calls, including query requests.
148+
If a query takes longer than the specified timeout, the operation will be canceled.
149+
150+
### Timeout examples
151+
152+
Use different timeout values based on your query type:
153+
154+
{{% code-placeholders "DATABASE_(TOKEN|NAME)" %}}
155+
```sh
156+
# Shorter timeout for testing dashboard queries (10 seconds)
157+
influxctl query \
158+
--timeout 10s \
159+
--token DATABASE_TOKEN \
160+
--database DATABASE_NAME \
161+
"SELECT * FROM sensors WHERE time >= now() - INTERVAL '1 hour' LIMIT 100"
162+
163+
# Longer timeout for analytical queries (5 minutes)
164+
influxctl query \
165+
--timeout 300s \
166+
--token DATABASE_TOKEN \
167+
--database DATABASE_NAME \
168+
"SELECT room, AVG(temperature) FROM sensors WHERE time >= now() - INTERVAL '30 days' GROUP BY room"
169+
```
170+
{{% /code-placeholders %}}
171+
172+
For guidance on selecting appropriate timeout values, see [Query timeout best practices](/influxdb3/clustered/query-data/troubleshoot-and-optimize/query-timeout-best-practices/).
173+
144174
## Output format
145175

146176
The `influxctl query` command supports the following output formats:
@@ -241,7 +271,7 @@ influxctl query \
241271
{{% /influxdb/custom-timestamps %}}
242272

243273
{{< expand-wrapper >}}
244-
{{% expand "View example results with unix nanosecond timestamps" %}}
274+
{{% expand "View example results with Unix nanosecond timestamps" %}}
245275
{{% influxdb/custom-timestamps %}}
246276
```
247277
+-------+--------+---------+------+---------------------+

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

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
title: Query timeout best practices
3+
description: Learn how to set appropriate query timeouts to balance performance and resource protection.
4+
menu:
5+
influxdb3_clustered:
6+
name: Query timeout best practices
7+
parent: Troubleshoot and optimize queries
8+
identifier: query-timeout-best-practices
9+
weight: 201
10+
related:
11+
- /influxdb3/clustered/reference/client-libraries/v3/
12+
- /influxdb3/clustered/query-data/execute-queries/influxctl-cli/
13+
source: shared/influxdb3-query-guides/query-timeout-best-practices.md
14+
---
15+
16+
<!--
17+
//SOURCE - content/shared/influxdb3-query-guides/query-timeout-best-practices.md
18+
>

0 commit comments

Comments
 (0)