ContextQMD
Back to Influxdb

Use the InfluxDB v1 API with InfluxDB Clustered

content/influxdb3/clustered/guides/api-compatibility/v1/_index.md

latest20.9 KB
Original Source

Use the InfluxDB v1 API /write and /query endpoints with v1 workloads that you bring to {{% product-name %}}. The v1 endpoints work with username/password authentication and existing InfluxDB 1.x tools and code. The InfluxDB v1 API /write endpoint works with InfluxDB 1.x client libraries and the Telegraf v1 Output Plugin. The InfluxDB v1 API /query endpoint supports InfluxQL and third-party integrations like Grafana.

Learn how to authenticate requests, adjust request parameters for existing v1 workloads, and find compatible tools for writing and querying data stored in an {{% product-name %}} database.

<!-- TOC --> <!-- /TOC -->

Authenticate API requests

{{% product-name %}} requires each API request to be authenticated with a database token. With InfluxDB v1-compatible endpoints in InfluxDB 3, you can use database tokens in InfluxDB 1.x username and password schemes, in the InfluxDB v2 Authorization: Token scheme, or in the OAuth Authorization: Bearer scheme.

Authenticate with a username and password scheme

With InfluxDB v1-compatible endpoints, you can use the InfluxDB 1.x convention of username and password to authenticate database reads and writes by passing a database token as the password credential. When authenticating requests to the v1 API /write and /query endpoints, {{% product-name %}} checks that the password (p) value is an authorized database token. {{% product-name %}} ignores the username (u) parameter in the request.

Use one of the following authentication schemes with clients that support Basic authentication or query parameters (that don't support token authentication):

Basic authentication

Use the Authorization header with the Basic scheme to authenticate v1 API /write and /query requests. When authenticating requests, {{% product-name %}} checks that the password part of the decoded credential is an authorized database token. {{% product-name %}} ignores the username part of the decoded credential.

Syntax
http
Authorization: Basic <base64-encoded [USERNAME]:DATABASE_TOKEN>

Encode the [USERNAME]:DATABASE_TOKEN credential using base64 encoding, and then append the encoded string to the Authorization: Basic header.

{{% api/v1-compat/basic-auth-syntax %}}

Example

The following example shows how to use cURL with the Basic authentication scheme and a database token:

{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}}

sh
curl --get "https://{{< influxdb/host >}}/query" \
  --user "any:DATABASE_TOKEN" \
  --data-urlencode "db=DATABASE_NAME" \
  --data-urlencode "q=SELECT * FROM MEASUREMENT"

{{% /code-placeholders %}}

Replace the following:

  • {{% code-placeholder-key %}}DATABASE_NAME{{% /code-placeholder-key %}}: your {{% product-name %}} database
  • {{% code-placeholder-key %}}DATABASE_TOKEN{{% /code-placeholder-key %}}: a database token with sufficient permissions to the specified database

Query string authentication

In the URL, pass the p query parameter to authenticate /write and /query requests. When authenticating requests, {{% product-name %}} checks that the p (password) value is an authorized database token and ignores the u (username) parameter.

Syntax
http
https://{{< influxdb/host >}}/query/?[u=any]&p=DATABASE_TOKEN
https://{{< influxdb/host >}}/write/?[u=any]&p=DATABASE_TOKEN
Example

The following example shows how to use cURL with query string authentication and database token.

{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}}

sh
curl --get "https://{{< influxdb/host >}}/query" \
  --data-urlencode "p=DATABASE_TOKEN" \
  --data-urlencode "db=DATABASE_NAME" \
  --data-urlencode "q=SELECT * FROM MEASUREMENT"

{{% /code-placeholders %}}

Replace the following:

  • {{% code-placeholder-key %}}DATABASE_NAME{{% /code-placeholder-key %}}: your {{% product-name %}} database
  • {{% code-placeholder-key %}}DATABASE_TOKEN{{% /code-placeholder-key %}}: a database token with sufficient permissions to the specified database

Authenticate with a token scheme

Use the Authorization: Bearer or the Authorization: Token scheme to pass a database token for authenticating v1 API /write and /query requests.

Bearer and Token are equivalent in {{% product-name %}}. The Token scheme is used in the InfluxDB 2.x API. Bearer is defined by the OAuth 2.0 Framework. Support for one or the other may vary across InfluxDB API clients.

Include the word Bearer or Token, a space, and your token value (all case-sensitive).

Syntax

http
Authorization: Bearer DATABASE_TOKEN
http
Authorization: Token DATABASE_TOKEN

Examples

Use Bearer to authenticate a write request:

{{% influxdb/custom-timestamps %}} {{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}}

sh
curl -i "https://{{< influxdb/host >}}/write?db=DATABASE_NAME&precision=s" \
    --header "Authorization: Bearer DATABASE_TOKEN" \
    --header "Content-type: text/plain; charset=utf-8" \
    --data-binary 'home,room=kitchen temp=72 1641024000'

{{% /code-placeholders %}} {{% /influxdb/custom-timestamps %}}

Use Token to authenticate a write request:

{{% influxdb/custom-timestamps %}} {{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}}

sh
curl -i "https://{{< influxdb/host >}}/write?db=DATABASE_NAME&precision=s" \
    --header "Authorization: Token DATABASE_TOKEN" \
    --header "Content-type: text/plain; charset=utf-8" \
    --data-binary 'home,room=kitchen temp=72 1641024000'

{{% /code-placeholders %}} {{% /influxdb/custom-timestamps %}}

Replace the following:

  • {{% code-placeholder-key %}}DATABASE_NAME{{% /code-placeholder-key %}}: your {{% product-name %}} database
  • {{% code-placeholder-key %}}DATABASE_TOKEN{{% /code-placeholder-key %}}: a database token with sufficient permissions to the specified database

Responses

InfluxDB API responses use standard HTTP status codes. For successful writes, InfluxDB responds with a 204 No Content status code. Error responses contain a JSON object with code and message properties that describe the error. Response body messages may differ across {{% product-name %}} v1 API, v2 API, InfluxDB Cloud, and InfluxDB OSS.

Error examples

  • Invalid namespace name:

    http
    400 Bad Request
    json
    { "code":"invalid",
  "message":"namespace name length must be between 1 and 64 characters"
}

    The ?db= parameter value is missing in the request. Provide the database name.

  • Failed to deserialize db/rp/precision

    http
    400 Bad Request
    json
    { "code":"invalid",
  "message":"failed to deserialize db/rp/precision in request: unknown variant `u`, expected one of `s`, `ms`, `us`, `ns`"
}

    The ?precision= parameter contains an unknown value. Provide a timestamp precision.

Write data

Write data with your existing workloads that already use the InfluxDB v1 or v1.x-compatibility /write API endpoint.

{{% api-endpoint endpoint="https://{{< influxdb/host >}}/write" method="post" %}}

v1 API /write parameters

For {{% product-name %}} v1 API /write requests, set parameters as listed in the following table:

ParameterAllowed inIgnoredValue
consistencyQuery stringIgnoredN/A
db {{% req " *" %}}Query stringHonoredDatabase name
precisionQuery stringHonoredTimestamp precision
rpQuery stringHonored, but discouragedRetention policy
uQuery stringIgnoredFor query string authentication, any arbitrary string
pQuery stringHonoredFor query string authentication, a database token with permission to write to the database
Content-EncodingHeaderHonoredgzip (compressed data) or identity (uncompressed)
AuthorizationHeaderHonoredBearer DATABASE_TOKEN, Token DATABASE_TOKEN, or Basic <base64 [USERNAME]:DATABASE_TOKEN>

{{% caption %}}{{% req " *" %}} = {{% req "Required" %}}{{% /caption %}}

Timestamp precision

Use one of the following precision values in v1 API /write requests:

  • ns: nanoseconds
  • us: microseconds
  • ms: milliseconds
  • s: seconds
  • m: minutes
  • h: hours

Tools for writing to the v1 API

The following tools work with the {{% product-name %}} /write endpoint:

Telegraf

If you have existing v1 workloads that use Telegraf, you can use the InfluxDB v1.x influxdb Telegraf output plugin to write data.

[!Note] See how to use Telegraf and the v2 API for new workloads that don't already use the v1 API.

The following table shows outputs.influxdb plugin parameters and values for writing to the {{% product-name %}} v1 API:

ParameterIgnoredValue
databaseHonoredDatabase name
retention_policyHonored, but discouragedDuration
usernameIgnoredString or empty
passwordHonoreddatabase token with permission to write to the database
content_encodingHonoredgzip (compressed data) or identity (uncompressed)
skip_database_creationIgnoredN/A (see how to create a database)

To configure the v1.x output plugin for writing to {{% product-name %}}, add the following outputs.influxdb configuration in your telegraf.conf file:

{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}}

toml
[[outputs.influxdb]]
  urls = ["https://{{< influxdb/host >}}"]
  database = "DATABASE_NAME"
  skip_database_creation = true
  retention_policy = ""
  username = "ignored"
  password = "DATABASE_TOKEN"
  content_encoding = "gzip”

{{% /code-placeholders %}}

Replace the following:

  • {{% code-placeholder-key %}}DATABASE_NAME{{% /code-placeholder-key %}}: your {{% product-name %}} database
  • {{% code-placeholder-key %}}DATABASE_TOKEN{{% /code-placeholder-key %}}: a database token with sufficient permissions to the specified database
Other Telegraf configuration options

influx_uint_support: supported in InfluxDB 3.

For more plugin options, see influxdb on GitHub.

Interactive clients

To test InfluxDB v1 API writes interactively from the command line, use common HTTP clients such as cURL and Postman.

Include the following in your request:

The following example shows how to use the cURL command line tool and the {{% product-name %}} v1 API to write line protocol data to a database:

{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}} {{% influxdb/custom-timestamps %}}

sh
curl -i 'https://{{< influxdb/host >}}/write?db=DATABASE_NAME&precision=s' \
    --header 'Authorization: Bearer DATABASE_TOKEN' \
    --header "Content-type: text/plain; charset=utf-8" \
    --data-binary 'home,room=kitchen temp=72 1641024000'

{{% /influxdb/custom-timestamps %}} {{% /code-placeholders %}}

Replace the following:

  • {{% code-placeholder-key %}}DATABASE_NAME{{% /code-placeholder-key %}}: your {{% product-name %}} database
  • {{% code-placeholder-key %}}DATABASE_TOKEN{{% /code-placeholder-key %}}: a database token with sufficient permissions to the specified database
v1 CLI (not supported)

Don't use the v1 CLI with {{% product-name %}}. While it may coincidentally work, it isn't officially supported.

Client libraries

Use language-specific v1 client libraries and your custom code to write data to InfluxDB. v1 client libraries send data in line protocol syntax to the v1 API /write endpoint.

The following samples show how to configure v1 client libraries for writing to {{% product-name %}}:

{{< tabs-wrapper >}} {{% tabs %}} Node.js Python {{% /tabs %}} {{% tab-content %}}

<!-- Start NodeJS -->

Create a v1 API client using the node-influx JavaScript client library:

{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}}

js
const Influx = require('influx')

// Instantiate a client for writing to {{% product-name %}} v1 API
const client = new Influx.InfluxDB({
  host: '{{< influxdb/host >}}',
  port: 443,
  protocol: 'https'
  database: 'DATABASE_NAME',
  username: 'ignored',
  password: 'DATABASE_TOKEN'
})

{{% /code-placeholders %}}

<!-- End NodeJS -->

{{% /tab-content %}} {{% tab-content %}}

<!-- Start Python -->

Create a v1 API client using the influxdb-python Python client library:

{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}}

py
from influxdb import InfluxDBClient

# Instantiate a client for writing to {{% product-name %}} v1 API
client = InfluxDBClient(
  host='{{< influxdb/host >}}',
  ssl=True,
  database='DATABASE_NAME',
  username='',
  password='DATABASE_TOKEN'
  headers={'Content-Type': 'text/plain; charset=utf-8'}
  )

{{% /code-placeholders %}}

<!-- End Python -->

{{% /tab-content %}} {{< /tabs-wrapper >}}

Replace the following:

  • {{% code-placeholder-key %}}DATABASE_NAME{{% /code-placeholder-key %}}: your {{% product-name %}} database
  • {{% code-placeholder-key %}}DATABASE_TOKEN{{% /code-placeholder-key %}}: a database token with sufficient permissions to the specified database

Query data

{{% product-name %}} provides the following protocols for executing a query:

  • Flight+gRPC request that contains an SQL or InfluxQL query. To learn how to query {{% product-name %}} using Flight and SQL, see the Get started tutorial.
  • InfluxDB v1 API /query request that contains an InfluxQL query. Use this endpoint with {{% product-name %}} when you bring InfluxDB 1.x workloads that already use InfluxQL and the v1 API /query endpoint.

[!Note]

Tools to execute queries

{{% product-name %}} supports many different tools for querying data, including:

v1 API /query parameters

For {{% product-name %}} v1 API /query requests, set parameters as listed in the following table:

ParameterAllowed inIgnoredValue
chunkedQuery stringHonoredReturns 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.
chunked_sizeQuery stringHonoredRequires chunked to be set to true. If set to a specific value, InfluxDB chunks responses by series or by this number of points.
dbQuery stringHonoredDatabase name
epochQuery stringHonoredTimestamp precision
pQuery stringHonoredDatabase token
prettyQuery stringIgnoredN/A
uQuery stringIgnoredFor query string authentication, any arbitrary string
pQuery stringHonoredFor query string authentication, a database token with permission to write to the database
rpQuery stringHonored, but discouragedRetention policy

[!Note] When bringing v1 API workloads to {{% product-name %}}, you'll need to adjust request parameters in your client configuration or code.

Timestamp precision

Use one of the following values for timestamp precision:

  • ns: nanoseconds
  • us: microseconds
  • ms: milliseconds
  • s: seconds
  • m: minutes
  • h: hours

Database management with InfluxQL (not supported)

{{% product-name %}} doesn't allow InfluxQL commands for managing or modifying databases. You can't use the following InfluxQL commands:

sql
SELECT INTO
CREATE
DELETE
DROP
GRANT
EXPLAIN
REVOKE
ALTER
SET
KILL