Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 61 additions & 9 deletions content/enterprise_influxdb/v1/tools/api.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: InfluxDB API reference
description: >
Use the InfluxDB API endpoints to run queries, write data, check server status, and troubleshoot by tracking HTTP client requests, collecting server statistics, and using Go "pprof" profiles.

Check warning on line 4 in content/enterprise_influxdb/v1/tools/api.md

View workflow job for this annotation

GitHub Actions / Vale style check

InfluxDataDocs.Spelling

Did you really mean 'pprof'?
aliases:
- /enterprise_influxdb/v1/concepts/api/
menu:
Expand All @@ -16,9 +16,9 @@

The following sections assume your InfluxDB instance is running on `localhost`
port `8086` and HTTPS is not enabled.
Those settings [are configurable](/enterprise_influxdb/v1/administration/configure/config-data-nodes/#http-endpoints-settings).
Those settings [are configurable](/enterprise_influxdb/v1/administration/configure/config-data-nodes/#http-endpoint-settings).

- [InfluxDB 2.x API compatibility endpoints](#influxdb-20-api-compatibility-endpoints)
- [InfluxDB 2.x API compatibility endpoints](#influxdb-2x-api-compatibility-endpoints)
- [InfluxDB 1.x HTTP endpoints](#influxdb-1x-http-endpoints)

## InfluxDB 2.x API compatibility endpoints
Expand Down Expand Up @@ -49,14 +49,14 @@
### `/api/v2/query/` HTTP endpoint

The `/api/v2/query` endpoint accepts `POST` HTTP requests.
Use this endpoint to query data using [Flux](/enterprise_influxdb/v1/flux/) and [InfluxDB 2.x client libraries](/influxdb/v2.x/api-guide/client-libraries/).
Use this endpoint to query data using [Flux](/enterprise_influxdb/v1/flux/) and [InfluxDB 2.x client libraries](/influxdb/v2/api-guide/client-libraries/).
Flux is the primary language for working with data in InfluxDB 2.x.

**Include the following HTTP headers:**

- `Accept: application/csv`
- `Content-type: application/vnd.flux`
- If [authentication is enabled](/enterprise_influxdb/v1/administration/authentication_and_authorization),
- If [authentication is enabled](/enterprise_influxdb/v1/administration/configure/security/authentication/),
provide your InfluxDB username and password:
`Authorization: Token USERNAME:PASSWORD`

Expand Down Expand Up @@ -397,6 +397,58 @@

>**Note:** The [InfluxDB input plugin](https://github.com/influxdata/telegraf/tree/master/plugins/inputs/influxdb) is available to collect metrics (using the `/debug/vars` endpoint) from specified Kapacitor instances. For a list of the measurements and fields, see the [InfluxDB input plugin README](https://github.com/influxdata/telegraf/tree/master/plugins/inputs/influxdb#readme).

#### Running configuration {metadata="v1.12.3+"}

The `/debug/vars` response includes a `config` key that contains the running [TSDB storage configuration](/enterprise_influxdb/v1/administration/configure/config-data-nodes/#data-settings).
Use this to inspect active server settings without direct access to configuration files.

Values in the JSON output use the following representations:

- Size values (such as `cache-max-memory-size`) appear as integers in bytes.
- Duration values (such as `cache-snapshot-write-cold-duration`) appear as human-readable strings (for example, `"10m0s"`).

The output is similar to the following:

```json
{
"config": {
"cache-max-memory-size": 1073741824,
"cache-snapshot-memory-size": 26214400,
"cache-snapshot-write-cold-duration": "10m0s",
"compact-full-write-cold-duration": "4h0m0s",
"compact-throughput": 50331648,
"compact-throughput-burst": 50331648,
"dir": "/var/lib/influxdb/data",
"max-concurrent-compactions": 0,
"max-index-log-file-size": 1048576,
"max-series-per-database": 1000000,
"max-values-per-tag": 100000,
"series-id-set-cache-size": 100,
"wal-dir": "/var/lib/influxdb/wal",
"wal-fsync-delay": "0s"
}
}
```

> [!Note]
> InfluxDB Enterprise data nodes also expose [cluster configuration](/enterprise_influxdb/v1/administration/configure/config-data-nodes/#cluster-settings) fields through their own diagnostics, including `dial-timeout`, `shard-reader-timeout`, and `rpc-resettable-*-timeout` settings.

#### Continuous query statistics {metadata="v1.12.3+"}

The `/debug/vars` response includes a `cq` key with continuous query execution counters:

```json
{
"cq": {
"queryOk": 2,
"queryFail": 0
}
}
```

- `queryOk`: Number of CQ executions that completed successfully.
- `queryFail`: Number of CQ executions that failed.

### `/ping` HTTP endpoint

The ping endpoint accepts both `GET` and `HEAD` HTTP requests.
Expand Down Expand Up @@ -537,7 +589,7 @@
| chunked=[true \| \<number_of_points>] | Optional | Returns points in streamed batches instead of in a single response. If set to `true`, InfluxDB chunks responses by series or by every 10,000 points, whichever occurs first. If set to a specific value, InfluxDB chunks responses by series or by that number of points.* |
| db=\<database_name> | Required for database-dependent queries (most [`SELECT`](/enterprise_influxdb/v1/query_language/spec/#select) queries and [`SHOW`](/enterprise_influxdb/v1/query_language/spec/#show-continuous-queries) queries require this parameter). | Sets the target [database](/enterprise_influxdb/v1/concepts/glossary/#database) for the query. |
| epoch=[ns,u,µ,ms,s,m,h] | Optional | Returns epoch timestamps with the specified precision. By default, InfluxDB returns timestamps in RFC3339 format with nanosecond precision. Both `u` and `µ` indicate microseconds. |
| p=\<password> | Optional if you haven't [enabled authentication](/enterprise_influxdb/v1/administration/authentication_and_authorization/#set-up-authentication). Required if you've enabled authentication.** | Sets the password for authentication if you've enabled authentication. Use with the query string parameter `u`. |
| p=\<password> | Optional if you haven't [enabled authentication](/enterprise_influxdb/v1/administration/configure/security/authentication/#enable-authentication). Required if you've enabled authentication.** | Sets the password for authentication if you've enabled authentication. Use with the query string parameter `u`. |
| pretty=true | Optional | Enables pretty-printed JSON output. While this is useful for debugging it is not recommended for production use as it consumes unnecessary network bandwidth. |
| q=\<query> | Required | InfluxQL string to execute. See also [Request Body](/enterprise_influxdb/v1/tools/api/#request-body). |
| time_format=[epoch \| rfc3339] | Optional | Sets the timestamp format in query responses. `epoch` _(default)_ returns epoch timestamps (use with the `epoch` parameter to set precision). `rfc3339` returns timestamps as RFC3339Nano-formatted strings (for example, `2017-03-01T00:16:18.000000000Z`). Returns `400` if set to an invalid value. _Available in InfluxDB Enterprise v1.12.3+._ |
Expand All @@ -548,7 +600,7 @@
configuration option for more information.

\** The InfluxDB API also supports basic authentication.
Use basic authentication if you've [enabled authentication](/enterprise_influxdb/v1/administration/authentication_and_authorization/#set-up-authentication)
Use basic authentication if you've [enabled authentication](/enterprise_influxdb/v1/administration/configure/security/authentication/#enable-authentication)
and aren't using the query string parameters `u` and `p`.
See below for an [example](#create-a-database-using-basic-authentication) of basic authentication.

Expand Down Expand Up @@ -942,13 +994,13 @@
| :--------------------- | :---------------- | :---------- |
| consistency=[any,one,quorum,all] | Optional, available with [InfluxDB Enterprise clusters](/enterprise_influxdb/v1/) only. | Sets the write consistency for the point. InfluxDB assumes that the write consistency is `one` if you do not specify `consistency`. See the [InfluxDB Enterprise documentation](/enterprise_influxdb/v1/concepts/clustering#write-consistency) for detailed descriptions of each consistency option. |
| db=\<database> | Required | Sets the target [database](/enterprise_influxdb/v1/concepts/glossary/#database) for the write. |
| p=\<password> | Optional if you haven't [enabled authentication](/enterprise_influxdb/v1/administration/authentication_and_authorization/#set-up-authentication). Required if you've enabled authentication.* | Sets the password for authentication if you've enabled authentication. Use with the query string parameter `u`. |
| p=\<password> | Optional if you haven't [enabled authentication](/enterprise_influxdb/v1/administration/configure/security/authentication/#enable-authentication). Required if you've enabled authentication.* | Sets the password for authentication if you've enabled authentication. Use with the query string parameter `u`. |
| precision=[ns,u,ms,s,m,h] | Optional | Sets the precision for the supplied Unix time values. InfluxDB assumes that timestamps are in nanoseconds if you do not specify `precision`.** |
| rp=\<retention_policy_name> | Optional | Sets the target [retention policy](/enterprise_influxdb/v1/concepts/glossary/#retention-policy-rp) for the write. InfluxDB writes to the `DEFAULT` retention policy if you do not specify a retention policy. |
| u=\<username> | Optional if you haven't [enabled authentication](/enterprise_influxdb/v1/administration/authentication_and_authorization/#set-up-authentication). Required if you've enabled authentication.* | Sets the username for authentication if you've enabled authentication. The user must have write access to the database. Use with the query string parameter `p`. |
| u=\<username> | Optional if you haven't [enabled authentication](/enterprise_influxdb/v1/administration/configure/security/authentication/#enable-authentication). Required if you've enabled authentication.* | Sets the username for authentication if you've enabled authentication. The user must have write access to the database. Use with the query string parameter `p`. |

\* The InfluxDB API also supports basic authentication.
Use basic authentication if you've [enabled authentication](/enterprise_influxdb/v1/administration/authentication_and_authorization/#set-up-authentication)
Use basic authentication if you've [enabled authentication](/enterprise_influxdb/v1/administration/configure/security/authentication/#enable-authentication)
and aren't using the query string parameters `u` and `p`.
See below for an [example](#write-a-point-to-the-database-mydb-using-basic-authentication) of basic authentication.

Expand Down
2 changes: 1 addition & 1 deletion content/influxdb/v1/about_the_project/release-notes.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@
- Add [`advanced-expiration` TLS configuration option](/influxdb/v1/administration/config/#advanced-expiration)
to configure how far in advance to log warnings about TLS certificate expiration.
- Add TLS certificate reloading on `SIGHUP`.
- Add `config` and `cq` (continuous query) diagnostics to the `/debug/vars` endpoint.
- Add [`config`](/influxdb/v1/tools/api/#running-configuration) and [`cq` (continuous query) statistics](/influxdb/v1/tools/api/#continuous-query-statistics) to the `/debug/vars` endpoint.
- Improve dropped point logging.
- Show user when displaying or logging queries.
- Add [`time_format` parameter](/influxdb/v1/tools/api/#query-data-with-a-select-statement-and-the-time_format-parameter) for the HTTP API.
Expand Down Expand Up @@ -318,7 +318,7 @@

This release is for InfluxDB Enterprise 1.8.6 customers only. No OSS-specific
changes were made for InfluxDB 1.8.6--updates were made to the code base to
support [InfluxDB Enterprise 1.8.6](/enterprise_influxdb/v1/about-the-project/release-notes/#v186).

Check notice on line 321 in content/influxdb/v1/about_the_project/release-notes.md

View workflow job for this annotation

GitHub Actions / Vale style check

write-good.E-Prime

Try to avoid using 'is'.

## v1.8.5 {date="2021-04-20"}

Expand Down Expand Up @@ -1747,25 +1747,25 @@
- Fix compaction planning re-compacting large TSM files.
- Ensure client sends correct precision when inserting points.
- Accept points with trailing whitespace.
- Fix panic in SHOW FIELD KEYS.

Check notice on line 1750 in content/influxdb/v1/about_the_project/release-notes.md

View workflow job for this annotation

GitHub Actions / Vale style check

InfluxDataDocs.Acronyms

Spell out 'KEYS', if it's unfamiliar to the audience.

Check notice on line 1750 in content/influxdb/v1/about_the_project/release-notes.md

View workflow job for this annotation

GitHub Actions / Vale style check

InfluxDataDocs.Acronyms

Spell out 'FIELD', if it's unfamiliar to the audience.
- Disable limit optimization when using an aggregate.
- Fix panic: interface conversion: tsm1.Value is \*tsm1.StringValue, not \*tsm1.FloatValue.
- Data race when dropping a database immediately after writing to it.
- Make sure admin exists before authenticating query.

Check warning on line 1754 in content/influxdb/v1/about_the_project/release-notes.md

View workflow job for this annotation

GitHub Actions / Vale style check

InfluxDataDocs.WordList

Use 'administrator' instead of 'admin'.
- Print the query executor's stack trace on a panic to the log.
- Fix read tombstones: EOF.

Check notice on line 1756 in content/influxdb/v1/about_the_project/release-notes.md

View workflow job for this annotation

GitHub Actions / Vale style check

InfluxDataDocs.Acronyms

Spell out 'EOF', if it's unfamiliar to the audience.
- Query-log-enabled in config not ignored anymore.
- Ensure clients requesting gzip encoded bodies don't receive empty body.
- Optimize shard loading.
- Queries slow down hundreds times after overwriting points.
- SHOW TAG VALUES accepts != and !~ in WHERE clause.

Check notice on line 1761 in content/influxdb/v1/about_the_project/release-notes.md

View workflow job for this annotation

GitHub Actions / Vale style check

InfluxDataDocs.Acronyms

Spell out 'TAG', if it's unfamiliar to the audience.
- Remove old cluster code.
- Ensure that future points considered in SHOW queries.
- Fix full compactions conflicting with level compactions.
- Overwriting points on large series can cause memory spikes during compactions.
- Fix parseFill to check for fill ident before attempting to parse an expression.

Check warning on line 1766 in content/influxdb/v1/about_the_project/release-notes.md

View workflow job for this annotation

GitHub Actions / Vale style check

InfluxDataDocs.Spelling

Did you really mean 'ident'?
- Max index entries exceeded.
- Address slow startup time.
- Fix measurement field panic in tsm1 engine.
- Queries against files that have just been compacted need to point to new files.

Check notice on line 1770 in content/influxdb/v1/about_the_project/release-notes.md

View workflow job for this annotation

GitHub Actions / Vale style check

Google.Passive

In general, use active voice instead of passive voice ('been compacted').

Check notice on line 1770 in content/influxdb/v1/about_the_project/release-notes.md

View workflow job for this annotation

GitHub Actions / Vale style check

write-good.E-Prime

Try to avoid using 'been'.

Check warning on line 1770 in content/influxdb/v1/about_the_project/release-notes.md

View workflow job for this annotation

GitHub Actions / Vale style check

write-good.Passive

'been compacted' may be passive voice. Use active voice if you can.
- Check that retention policies exist before creating CQ.
59 changes: 54 additions & 5 deletions content/influxdb/v1/tools/api.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: InfluxDB API reference
description: >
Use the InfluxDB API endpoints to run queries, write data, check server status, and troubleshoot by tracking HTTP client requests, collecting server statistics, and using Go "pprof" profiles.

Check warning on line 4 in content/influxdb/v1/tools/api.md

View workflow job for this annotation

GitHub Actions / Vale style check

InfluxDataDocs.Spelling

Did you really mean 'pprof'?
aliases:
- /influxdb/v1/concepts/api/
menu:
Expand Down Expand Up @@ -64,8 +64,8 @@

| Endpoint | Description |
| :--------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------ |
| [/api/v2/query](#api-v2-query-http-endpoint) | Query data in InfluxDB 1.8.0+ using the InfluxDB v2 API and [Flux](/flux/latest/) |
| [/api/v2/write](#api-v2-write-http-endpoint) | Write data to InfluxDB 1.8.0+ using the InfluxDB v2 API _(compatible with InfluxDB v2 client libraries)_ |
| [/api/v2/query](#apiv2query-http-endpoint) | Query data in InfluxDB 1.8.0+ using the InfluxDB v2 API and [Flux](/flux/latest/) |
| [/api/v2/write](#apiv2write-http-endpoint) | Write data to InfluxDB 1.8.0+ using the InfluxDB v2 API _(compatible with InfluxDB v2 client libraries)_ |
| [/api/v2/buckets](#apiv2buckets-http-endpoint) | Allows some client code using buckets to run against 1.x and 2.x without modification |
| [/api/v2/delete](#apiv2delete-http-endpoint) | Supports deletion by tag value, timestamp, and measurement using the InfluxDB v2 API _(compatible with InfluxDB v2 client libraries)_ |
| [/health](#health-http-endpoint) | Check the health of your InfluxDB instance |
Expand Down Expand Up @@ -284,9 +284,9 @@

| Endpoint | Description |
|:---------- |:---------- |
| [/debug/pprof ](#debug-pprof-http-endpoint) | Generate profiles for troubleshooting |
| [/debug/requests](#debug-requests-http-endpoint) | Track HTTP client requests to the `/write` and `/query` endpoints |
| [/debug/vars](#debug-vars-http-endpoint) | Collect internal InfluxDB statistics |
| [/debug/pprof ](#debugpprof-http-endpoint) | Generate profiles for troubleshooting |
| [/debug/requests](#debugrequests-http-endpoint) | Track HTTP client requests to the `/write` and `/query` endpoints |
| [/debug/vars](#debugvars-http-endpoint) | Collect internal InfluxDB statistics |
| [/ping](#ping-http-endpoint) | Check the status of your InfluxDB instance and your version of InfluxDB |
| [/query](#query-http-endpoint) | Query data using **InfluxQL**, manage databases, retention policies, and users |
| [/write](#write-http-endpoint) | Write data to a database |
Expand Down Expand Up @@ -420,6 +420,55 @@

>**Note:** The [InfluxDB input plugin](https://github.com/influxdata/telegraf/tree/master/plugins/inputs/influxdb) is available to collect metrics (using the `/debug/vars` endpoint) from specified Kapacitor instances. For a list of the measurements and fields, see the [InfluxDB input plugin README](https://github.com/influxdata/telegraf/tree/master/plugins/inputs/influxdb#readme).

#### Running configuration {metadata="v1.12.3+"}

The `/debug/vars` response includes a `config` key that contains the running [TSDB storage configuration](/influxdb/v1/administration/config/#data-settings).
Use this to inspect active server settings without direct access to configuration files.

Values in the JSON output use the following representations:

- Size values (such as `cache-max-memory-size`) appear as integers in bytes.
- Duration values (such as `cache-snapshot-write-cold-duration`) appear as human-readable strings (for example, `"10m0s"`).

The output is similar to the following:

```json
{
"config": {
"cache-max-memory-size": 1073741824,
"cache-snapshot-memory-size": 26214400,
"cache-snapshot-write-cold-duration": "10m0s",
"compact-full-write-cold-duration": "4h0m0s",
"compact-throughput": 50331648,
"compact-throughput-burst": 50331648,
"dir": "/var/lib/influxdb/data",
"max-concurrent-compactions": 0,
"max-index-log-file-size": 1048576,
"max-series-per-database": 1000000,
"max-values-per-tag": 100000,
"series-id-set-cache-size": 100,
"wal-dir": "/var/lib/influxdb/wal",
"wal-fsync-delay": "0s"
}
}
```

#### Continuous query statistics {metadata="v1.12.3+"}

The `/debug/vars` response includes a `cq` key with continuous query execution counters:

```json
{
"cq": {
"queryOk": 2,
"queryFail": 0
}
}
```

- `queryOk`: Number of CQ executions that completed successfully.
- `queryFail`: Number of CQ executions that failed.

### `/ping` HTTP endpoint

The ping endpoint accepts both `GET` and `HEAD` HTTP requests.
Expand Down
2 changes: 1 addition & 1 deletion layouts/partials/article/feedback.html
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
{{ $product := index $productPathData 0 }}
{{ $version := index $productPathData 1 }}
{{ $productKey := cond (eq $product "influxdb3") (print "influxdb3_" (replaceRE "-" "_" $version)) $product }}
{{ $productNamespace := cond (eq $product "influxdb3") "influxdb" $product }}
{{ $productNamespace := cond (or (eq $product "influxdb3") (eq $product "enterprise_influxdb")) "influxdb" $product }}
{{ $productName := (index .Site.Data.products $productKey).name }}
{{ $supportBlacklist := slice "chronograf" "kapacitor" }}

Expand Down
Loading