1773 lines
56 KiB
YAML
1773 lines
56 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: InfluxDB 3 Core API Service
|
|
description: |
|
|
The InfluxDB HTTP API for InfluxDB 3 Core provides a programmatic interface for
|
|
interacting with InfluxDB 3 Core databases and resources.
|
|
Use this API to:
|
|
|
|
- Write data to InfluxDB 3 Core databases
|
|
- Query data using SQL or InfluxQL
|
|
- Process data using Processing engine plugins
|
|
- Manage databases, tables, and Processing engine triggers
|
|
- Perform administrative tasks and access system information
|
|
|
|
The API includes endpoints under the following paths:
|
|
- `/api/v3`: InfluxDB 3 Core native endpoints
|
|
- `/`: Compatibility endpoints for InfluxDB v1 workloads and clients
|
|
- `/api/v2/write`: Compatibility endpoint for InfluxDB v2 workloads and clients
|
|
|
|
<!-- TODO: verify where to host the spec that users can download.
|
|
This documentation is generated from the
|
|
[InfluxDB OpenAPI specification](https://raw.githubusercontent.com/influxdata/).
|
|
-->
|
|
version: ''
|
|
license:
|
|
name: MIT
|
|
url: https://opensource.org/licenses/MIT
|
|
contact:
|
|
name: InfluxData
|
|
url: https://www.influxdata.com
|
|
email: support@influxdata.com
|
|
servers:
|
|
- url: https://{baseurl}
|
|
description: InfluxDB 3 Core API URL
|
|
variables:
|
|
baseurl:
|
|
enum:
|
|
- localhost:8181
|
|
default: localhost:8181
|
|
description: InfluxDB 3 Core URL
|
|
security:
|
|
- BearerAuth: []
|
|
tags:
|
|
- name: Authentication
|
|
description: |
|
|
During the initial Alpha phase, InfluxDB 3 Core does not require authentication.
|
|
x-traitTag: true
|
|
- name: Compatibility endpoints
|
|
description: |
|
|
InfluxDB 3 provides compatibility endpoints for InfluxDB 1.x and InfluxDB 2.x workloads and clients.
|
|
|
|
### Write data using v1- or v2-compatible endpoints
|
|
|
|
- [`/api/v2/write` endpoint](#operation/PostV2Write)
|
|
for InfluxDB v2 clients and when you bring existing InfluxDB v2 write workloads to InfluxDB 3.
|
|
- [`/write` endpoint](#operation/PostV1Write) for InfluxDB v1 clients and when you bring existing InfluxDB v1 write workloads to InfluxDB 3.
|
|
|
|
For new workloads, use the [`/api/v3/write_lp` endpoint](#operation/PostWriteLP).
|
|
|
|
All endpoints accept the same line protocol format.
|
|
|
|
### Query data
|
|
|
|
Use the HTTP [`/query`](#operation/GetV1ExecuteQuery) endpoint for InfluxDB v1 clients and v1 query workloads using InfluxQL.
|
|
|
|
For new workloads, use one of the following:
|
|
|
|
- HTTP [`/api/v3/query_sql` endpoint](#operation/GetExecuteQuerySQL) for new query workloads using SQL.
|
|
- HTTP [`/api/v3/query_influxql` endpoint](#operation/GetExecuteInfluxQLQuery) for new query workloads using InfluxQL.
|
|
- Flight SQL and InfluxDB 3 _Flight+gRPC_ APIs for querying with SQL or InfluxQL. For more information about using Flight APIs, see [InfluxDB 3 client libraries](https://github.com/InfluxCommunity).
|
|
|
|
### Server information
|
|
|
|
Server information endpoints such as `/health` and `metrics` are compatible with InfluxDB 1.x and InfluxDB 2.x clients.
|
|
- name: Data I/O
|
|
description: Write and query data
|
|
- name: Databases
|
|
description: Create, read, update, and delete database and cache resources
|
|
- description: |
|
|
Most InfluxDB API endpoints require parameters in the request--for example, specifying the database to use.
|
|
|
|
### Common parameters
|
|
|
|
The following table shows common parameters used by many InfluxDB API endpoints.
|
|
Many endpoints may require other parameters in the query string or in the
|
|
request body that perform functions specific to those endpoints.
|
|
|
|
| Query parameter | Value type | Description |
|
|
|:------------------------ |:--------------------- |:-------------------------------------------|
|
|
| `db` | string | The database name |
|
|
|
|
InfluxDB HTTP API endpoints use standard HTTP request and response headers.
|
|
The following table shows common headers used by many InfluxDB API endpoints.
|
|
Some endpoints may use other headers that perform functions more specific to those endpoints--for example,
|
|
the write endpoints accept the `Content-Encoding` header to indicate that line protocol is compressed in the request body.
|
|
|
|
| Header | Value type | Description |
|
|
|:------------------------ |:--------------------- |:-------------------------------------------|
|
|
| `Accept` | string | The content type that the client can understand. |
|
|
| `Authorization` | string | The authorization scheme and credential. |
|
|
| `Content-Length` | integer | The size of the entity-body, in bytes. |
|
|
| `Content-Type` | string | The format of the data in the request body. |
|
|
name: Headers and parameters
|
|
x-traitTag: true
|
|
- name: Processing engine
|
|
description: |
|
|
Manage Processing engine triggers, test plugins, and send requests to trigger On Request plugins.
|
|
|
|
InfluxDB 3 Core provides the InfluxDB 3 Processing engine, an embedded Python VM that can dynamically load and trigger Python plugins in response to events in your database.
|
|
Use Processing engine plugins and triggers to run code and perform tasks for different database events.
|
|
|
|
To get started with the Processing engine, see the [Processing engine and Python plugins](/influxdb3/core/processing-engine/) guide.
|
|
- name: Quick start
|
|
description: |
|
|
1. [Check the status](#section/Server-information) of the InfluxDB server.
|
|
|
|
```bash
|
|
curl "http://localhost:8181/health"
|
|
```
|
|
|
|
2. [Write data](#section/Compatibility-endpoints/Write-data) to InfluxDB.
|
|
|
|
```bash
|
|
curl "http://localhost:8181/api/v3/write_lp?db=sensors&precision=auto" \
|
|
--data-raw "home,room=Kitchen temp=72.0
|
|
home,room=Living\ room temp=71.5"
|
|
```
|
|
|
|
If all data is written, the response is `204 No Content`.
|
|
|
|
3. [Query data](#section/Compatibility-endpoints/Query-data) from InfluxDB.
|
|
|
|
```bash
|
|
curl -G "http://localhost:8181/api/v3/query_sql" \
|
|
--data-urlencode "db=sensors" \
|
|
--data-urlencode "q=SELECT * FROM home WHERE room='Living room'" \
|
|
--data-urlencode "format=jsonl"
|
|
```
|
|
|
|
Output:
|
|
|
|
```jsonl
|
|
{"room":"Living room","temp":71.5,"time":"2025-02-25T20:19:34.984098"}
|
|
```
|
|
|
|
For more information about using InfluxDB 3 Core, see the [Get started](/influxdb3/core/get-started/) guide.
|
|
x-traitTag: true
|
|
- name: Server information
|
|
description: Retrieve server metrics, status, and version information
|
|
- name: Tables
|
|
description: Manage table schemas and data
|
|
paths:
|
|
/write:
|
|
post:
|
|
operationId: PostV1Write
|
|
summary: Write line protocol (v1-compatible)
|
|
description: |
|
|
Writes line protocol to the specified database.
|
|
|
|
This endpoint provides backward compatibility for InfluxDB 1.x write workloads using tools such as InfluxDB 1.x client libraries, the Telegraf `outputs.influxdb` output plugin, or third-party tools.
|
|
|
|
Use this endpoint to send data in [line protocol](https://docs.influxdata.com/influxdb3/core/reference/syntax/line-protocol/) format to InfluxDB.
|
|
Use query parameters to specify options for writing data.
|
|
parameters:
|
|
- $ref: '#/components/parameters/dbWriteParam'
|
|
- $ref: '#/components/parameters/compatibilityPrecisionParam'
|
|
- name: Content-Type
|
|
in: header
|
|
description: |
|
|
The content type of the request payload.
|
|
schema:
|
|
$ref: '#/components/schemas/LineProtocol'
|
|
required: false
|
|
- name: Accept
|
|
in: header
|
|
description: |
|
|
The content type that the client can understand.
|
|
Writes only return a response body if they fail (partially or completely)--for example,
|
|
due to a syntax problem or type mismatch.
|
|
schema:
|
|
type: string
|
|
default: application/json
|
|
enum:
|
|
- application/json
|
|
required: false
|
|
- $ref: '#/components/parameters/ContentEncoding'
|
|
- $ref: '#/components/parameters/ContentLength'
|
|
requestBody:
|
|
$ref: '#/components/requestBodies/lineProtocolRequestBody'
|
|
responses:
|
|
'204':
|
|
description: Success ("No Content"). All data in the batch is written and queryable.
|
|
'400':
|
|
description: |
|
|
Bad request. Some (a _partial write_) or all of the data from the batch was rejected and not written.
|
|
If a partial write occurred, then some points from the batch are written and queryable.
|
|
|
|
The response body:
|
|
- indicates if a partial write occurred or all data was rejected.
|
|
- contains details about the [rejected points](/influxdb3/core/write-data/troubleshoot/#troubleshoot-rejected-points), up to 100 points.
|
|
content:
|
|
application/json:
|
|
examples:
|
|
rejectedAllPoints:
|
|
summary: Rejected all points in the batch
|
|
value: |
|
|
{
|
|
"error": "write of line protocol failed",
|
|
"data": [
|
|
{
|
|
"original_line": "dquote> home,room=Kitchen temp=hi",
|
|
"line_number": 2,
|
|
"error_message": "No fields were provided"
|
|
}
|
|
]
|
|
}
|
|
partialWriteErrorWithRejectedPoints:
|
|
summary: Partial write rejected some points in the batch
|
|
value: |
|
|
{
|
|
"error": "partial write of line protocol occurred",
|
|
"data": [
|
|
{
|
|
"original_line": "dquote> home,room=Kitchen temp=hi",
|
|
"line_number": 2,
|
|
"error_message": "No fields were provided"
|
|
}
|
|
]
|
|
}
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
description: Access denied.
|
|
'413':
|
|
description: Request entity too large.
|
|
tags:
|
|
- Compatibility endpoints
|
|
- Data I/O
|
|
/api/v2/write:
|
|
post:
|
|
operationId: PostV2Write
|
|
summary: Write line protocol (v2-compatible)
|
|
description: |
|
|
Writes line protocol to the specified database.
|
|
|
|
This endpoint provides backward compatibility for InfluxDB 2.x write workloads using tools such as InfluxDB 2.x client libraries, the Telegraf `outputs.influxdb_v2` output plugin, or third-party tools.
|
|
|
|
Use this endpoint to send data in [line protocol](/influxdb3/core/reference/syntax/line-protocol/) format to InfluxDB.
|
|
Use query parameters to specify options for writing data.
|
|
parameters:
|
|
- name: Content-Type
|
|
in: header
|
|
description: |
|
|
The content type of the request payload.
|
|
schema:
|
|
$ref: '#/components/schemas/LineProtocol'
|
|
required: false
|
|
- description: |
|
|
The compression applied to the line protocol in the request payload.
|
|
To send a gzip payload, pass `Content-Encoding: gzip` header.
|
|
in: header
|
|
name: Content-Encoding
|
|
schema:
|
|
default: identity
|
|
description: |
|
|
Content coding.
|
|
Use `gzip` for compressed data or `identity` for unmodified, uncompressed data.
|
|
enum:
|
|
- gzip
|
|
- identity
|
|
type: string
|
|
- description: |
|
|
The size of the entity-body, in bytes, sent to InfluxDB.
|
|
in: header
|
|
name: Content-Length
|
|
schema:
|
|
description: The length in decimal number of octets.
|
|
type: integer
|
|
- description: |
|
|
The content type that the client can understand.
|
|
Writes only return a response body if they fail (partially or completely)--for example,
|
|
due to a syntax problem or type mismatch.
|
|
in: header
|
|
name: Accept
|
|
schema:
|
|
default: application/json
|
|
description: Error content type.
|
|
enum:
|
|
- application/json
|
|
type: string
|
|
- name: db
|
|
in: query
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: |
|
|
A database name.
|
|
InfluxDB creates the database if it doesn't already exist, and then
|
|
writes all points in the batch to the database.
|
|
- name: accept_partial
|
|
in: query
|
|
required: false
|
|
schema:
|
|
$ref: '#/components/schemas/AcceptPartial'
|
|
- $ref: '#/components/parameters/compatibilityPrecisionParam'
|
|
requestBody:
|
|
$ref: '#/components/requestBodies/lineProtocolRequestBody'
|
|
responses:
|
|
'204':
|
|
description: Success ("No Content"). All data in the batch is written and queryable.
|
|
'400':
|
|
description: Bad request.
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
description: Access denied.
|
|
'413':
|
|
description: Request entity too large.
|
|
tags:
|
|
- Compatibility endpoints
|
|
- Data I/O
|
|
/api/v3/write_lp:
|
|
post:
|
|
operationId: PostWriteLP
|
|
summary: Write line protocol
|
|
description: |
|
|
Writes line protocol to the specified database.
|
|
|
|
Use this endpoint to send data in [line protocol](/influxdb3/core/reference/syntax/line-protocol/) format to InfluxDB.
|
|
Use query parameters to specify options for writing data.
|
|
parameters:
|
|
- $ref: '#/components/parameters/dbWriteParam'
|
|
- $ref: '#/components/parameters/accept_partial'
|
|
- name: precision
|
|
in: query
|
|
required: true
|
|
schema:
|
|
$ref: '#/components/schemas/PrecisionWrite'
|
|
description: Precision of timestamps.
|
|
- name: no_sync
|
|
in: query
|
|
schema:
|
|
$ref: '#/components/schemas/NoSync'
|
|
- name: Content-Type
|
|
in: header
|
|
description: |
|
|
The content type of the request payload.
|
|
schema:
|
|
$ref: '#/components/schemas/LineProtocol'
|
|
required: false
|
|
- name: Accept
|
|
in: header
|
|
description: |
|
|
The content type that the client can understand.
|
|
Writes only return a response body if they fail (partially or completely)--for example,
|
|
due to a syntax problem or type mismatch.
|
|
schema:
|
|
type: string
|
|
default: application/json
|
|
enum:
|
|
- application/json
|
|
required: false
|
|
- $ref: '#/components/parameters/ContentEncoding'
|
|
- $ref: '#/components/parameters/ContentLength'
|
|
requestBody:
|
|
$ref: '#/components/requestBodies/lineProtocolRequestBody'
|
|
responses:
|
|
'204':
|
|
description: Success ("No Content"). All data in the batch is written and queryable.
|
|
'400':
|
|
description: Bad request.
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
description: Access denied.
|
|
'413':
|
|
description: Request entity too large.
|
|
'422':
|
|
description: Unprocessable entity.
|
|
tags:
|
|
- Data I/O
|
|
/api/v3/query_sql:
|
|
get:
|
|
operationId: GetExecuteQuerySQL
|
|
summary: Execute SQL query
|
|
description: Executes an SQL query to retrieve data from the specified database.
|
|
parameters:
|
|
- $ref: '#/components/parameters/db'
|
|
- name: q
|
|
in: query
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: format
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: string
|
|
- $ref: '#/components/parameters/AcceptQueryHeader'
|
|
- $ref: '#/components/parameters/ContentType'
|
|
responses:
|
|
'200':
|
|
description: Success. The response body contains query results.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/QueryResponse'
|
|
example:
|
|
results:
|
|
- series:
|
|
- name: mytable
|
|
columns:
|
|
- time
|
|
- value
|
|
values:
|
|
- - '2024-02-02T12:00:00Z'
|
|
- 42
|
|
text/csv:
|
|
schema:
|
|
type: string
|
|
application/vnd.apache.parquet:
|
|
schema:
|
|
type: string
|
|
application/jsonl:
|
|
schema:
|
|
type: string
|
|
'400':
|
|
description: Bad request.
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
description: Access denied.
|
|
'404':
|
|
description: Database not found.
|
|
'405':
|
|
description: Method not allowed.
|
|
'422':
|
|
description: Unprocessable entity.
|
|
tags:
|
|
- Data I/O
|
|
post:
|
|
operationId: PostExecuteQuerySQL
|
|
summary: Execute SQL query
|
|
description: Executes an SQL query to retrieve data from the specified database.
|
|
parameters:
|
|
- $ref: '#/components/parameters/AcceptQueryHeader'
|
|
- $ref: '#/components/parameters/ContentType'
|
|
requestBody:
|
|
$ref: '#/components/requestBodies/queryRequestBody'
|
|
responses:
|
|
'200':
|
|
description: Success. The response body contains query results.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/QueryResponse'
|
|
text/csv:
|
|
schema:
|
|
type: string
|
|
application/vnd.apache.parquet:
|
|
schema:
|
|
type: string
|
|
application/jsonl:
|
|
schema:
|
|
type: string
|
|
'400':
|
|
description: Bad request.
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
description: Access denied.
|
|
'404':
|
|
description: Database not found.
|
|
'405':
|
|
description: Method not allowed.
|
|
'422':
|
|
description: Unprocessable entity.
|
|
tags:
|
|
- Data I/O
|
|
/api/v3/query_influxql:
|
|
get:
|
|
operationId: GetExecuteInfluxQLQuery
|
|
summary: Execute InfluxQL query
|
|
description: Executes an InfluxQL query to retrieve data from the specified database.
|
|
parameters:
|
|
- $ref: '#/components/parameters/dbQueryParam'
|
|
- name: q
|
|
in: query
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: format
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: string
|
|
- $ref: '#/components/parameters/AcceptQueryHeader'
|
|
responses:
|
|
'200':
|
|
description: Success. The response body contains query results.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/QueryResponse'
|
|
text/csv:
|
|
schema:
|
|
type: string
|
|
application/vnd.apache.parquet:
|
|
schema:
|
|
type: string
|
|
application/jsonl:
|
|
schema:
|
|
type: string
|
|
'400':
|
|
description: Bad request.
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
description: Access denied.
|
|
'404':
|
|
description: Database not found.
|
|
'405':
|
|
description: Method not allowed.
|
|
'422':
|
|
description: Unprocessable entity.
|
|
tags:
|
|
- Data I/O
|
|
post:
|
|
operationId: PostExecuteQueryInfluxQL
|
|
summary: Execute InfluxQL query
|
|
description: Executes an InfluxQL query to retrieve data from the specified database.
|
|
parameters:
|
|
- $ref: '#/components/parameters/AcceptQueryHeader'
|
|
- $ref: '#/components/parameters/ContentType'
|
|
requestBody:
|
|
$ref: '#/components/requestBodies/queryRequestBody'
|
|
responses:
|
|
'200':
|
|
description: Success. The response body contains query results.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/QueryResponse'
|
|
text/csv:
|
|
schema:
|
|
type: string
|
|
application/vnd.apache.parquet:
|
|
schema:
|
|
type: string
|
|
application/jsonl:
|
|
schema:
|
|
type: string
|
|
'400':
|
|
description: Bad request.
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
description: Access denied.
|
|
'404':
|
|
description: Database not found.
|
|
'405':
|
|
description: Method not allowed.
|
|
'422':
|
|
description: Unprocessable entity.
|
|
tags:
|
|
- Data I/O
|
|
/query:
|
|
get:
|
|
operationId: GetV1ExecuteQuery
|
|
summary: Execute InfluxQL query (v1-compatible)
|
|
description: |
|
|
Executes an InfluxQL query to retrieve data from the specified database.
|
|
|
|
This endpoint is compatible with InfluxDB 1.x client libraries and third-party integrations such as Grafana.
|
|
Use query parameters to specify the database and the InfluxQL query.
|
|
parameters:
|
|
- name: Accept
|
|
in: header
|
|
schema:
|
|
type: string
|
|
default: application/json
|
|
enum:
|
|
- application/json
|
|
- application/csv
|
|
- text/csv
|
|
required: false
|
|
description: |
|
|
The content type that the client can understand.
|
|
|
|
If `text/csv` is specified, the `Content-type` response header is `application/csv` and the response is formatted as CSV.
|
|
|
|
Returns an error if the format is invalid or non-UTF8.
|
|
- in: query
|
|
name: chunked
|
|
description: |
|
|
If true, the response is divided into chunks of size `chunk_size`.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
- in: query
|
|
name: chunk_size
|
|
description: |
|
|
The number of records that will go into a chunk.
|
|
This parameter is only used if `chunked=true`.
|
|
schema:
|
|
type: integer
|
|
default: 10000
|
|
- in: query
|
|
name: db
|
|
description: The database to query. If not provided, the InfluxQL query string must specify the database.
|
|
schema:
|
|
type: string
|
|
format: InfluxQL
|
|
- in: query
|
|
name: pretty
|
|
description: |
|
|
If true, the JSON response is formatted in a human-readable format.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
- in: query
|
|
name: q
|
|
description: The InfluxQL query string.
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: epoch
|
|
description: |
|
|
Formats timestamps as [unix (epoch) timestamps](/influxdb3/core/reference/glossary/#unix-timestamp) with the specified precision
|
|
instead of [RFC3339 timestamps](/influxdb3/core/reference/glossary/#rfc3339-timestamp) with nanosecond precision.
|
|
in: query
|
|
schema:
|
|
$ref: '#/components/schemas/EpochCompatibility'
|
|
responses:
|
|
'200':
|
|
description: |
|
|
Success. The response body contains query results.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/QueryResponse'
|
|
application/csv:
|
|
schema:
|
|
type: string
|
|
headers:
|
|
Content-Type:
|
|
description: |
|
|
The content type of the response.
|
|
Default is `application/json`.
|
|
|
|
If the `Accept` request header is `application/csv` or `text/csv`, the `Content-type` response header is `application/csv`
|
|
and the response is formatted as CSV.
|
|
schema:
|
|
type: string
|
|
default: application/json
|
|
enum:
|
|
- application/json
|
|
- application/csv
|
|
'400':
|
|
description: Bad request.
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
description: Access denied.
|
|
'404':
|
|
description: Database not found.
|
|
'405':
|
|
description: Method not allowed.
|
|
'422':
|
|
description: Unprocessable entity.
|
|
tags:
|
|
- Data I/O
|
|
- Compatibility endpoints
|
|
post:
|
|
operationId: PostExecuteV1Query
|
|
summary: Execute InfluxQL query (v1-compatible)
|
|
description: Executes an InfluxQL query to retrieve data from the specified database.
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
db:
|
|
type: string
|
|
description: The database to query. If not provided, the InfluxQL query string must specify the database.
|
|
q:
|
|
description: The InfluxQL query string.
|
|
type: string
|
|
chunked:
|
|
description: |
|
|
If true, the response is divided into chunks of size `chunk_size`.
|
|
type: boolean
|
|
chunk_size:
|
|
description: |
|
|
The number of records that will go into a chunk.
|
|
This parameter is only used if `chunked=true`.
|
|
type: integer
|
|
default: 10000
|
|
epoch:
|
|
description: |
|
|
A unix timestamp precision.
|
|
|
|
- `h` for hours
|
|
- `m` for minutes
|
|
- `s` for seconds
|
|
- `ms` for milliseconds
|
|
- `u` or `µ` for microseconds
|
|
- `ns` for nanoseconds
|
|
|
|
Formats timestamps as [unix (epoch) timestamps](/influxdb3/core/reference/glossary/#unix-timestamp) with the specified precision
|
|
instead of [RFC3339 timestamps](/influxdb3/core/reference/glossary/#rfc3339-timestamp) with nanosecond precision.
|
|
enum:
|
|
- ns
|
|
- u
|
|
- µ
|
|
- ms
|
|
- s
|
|
- m
|
|
- h
|
|
type: string
|
|
pretty:
|
|
description: |
|
|
If true, the JSON response is formatted in a human-readable format.
|
|
type: boolean
|
|
required:
|
|
- q
|
|
parameters:
|
|
- name: Accept
|
|
in: header
|
|
schema:
|
|
type: string
|
|
default: application/json
|
|
enum:
|
|
- application/json
|
|
- application/csv
|
|
- text/csv
|
|
required: false
|
|
description: |
|
|
The content type that the client can understand.
|
|
|
|
If `text/csv` is specified, the `Content-type` response header is `application/csv` and the response is formatted as CSV.
|
|
|
|
Returns an error if the format is invalid or non-UTF8.
|
|
responses:
|
|
'200':
|
|
description: |
|
|
Success. The response body contains query results.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/QueryResponse'
|
|
application/csv:
|
|
schema:
|
|
type: string
|
|
headers:
|
|
Content-Type:
|
|
description: |
|
|
The content type of the response.
|
|
Default is `application/json`.
|
|
|
|
If the `Accept` request header is `application/csv` or `text/csv`, the `Content-type` response header is `application/csv`
|
|
and the response is formatted as CSV.
|
|
schema:
|
|
type: string
|
|
default: application/json
|
|
enum:
|
|
- application/json
|
|
- application/csv
|
|
'400':
|
|
description: Bad request.
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
description: Access denied.
|
|
'404':
|
|
description: Database not found.
|
|
'405':
|
|
description: Method not allowed.
|
|
'422':
|
|
description: Unprocessable entity.
|
|
tags:
|
|
- Data I/O
|
|
- Compatibility endpoints
|
|
/health:
|
|
get:
|
|
operationId: GetHealth
|
|
summary: Health check
|
|
description: Checks the status of the service.
|
|
responses:
|
|
'200':
|
|
description: Service is running.
|
|
'500':
|
|
description: Service is unavailable.
|
|
tags:
|
|
- Server information
|
|
/api/v1/health:
|
|
get:
|
|
operationId: GetHealthV1
|
|
summary: Health check (v1)
|
|
description: Checks the status of the service.
|
|
responses:
|
|
'200':
|
|
description: Service is running.
|
|
'500':
|
|
description: Service is unavailable.
|
|
tags:
|
|
- Server information
|
|
- Compatibility endpoints
|
|
/ping:
|
|
get:
|
|
operationId: GetPing
|
|
tags:
|
|
- Server information
|
|
summary: Ping the server
|
|
description: Returns version information for the server.
|
|
responses:
|
|
'200':
|
|
description: Success. The response body contains server information.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
example:
|
|
version: 0.1.0
|
|
revision: f3d3d3d
|
|
/metrics:
|
|
get:
|
|
operationId: GetMetrics
|
|
summary: Metrics
|
|
description: Retrieves Prometheus-compatible server metrics.
|
|
responses:
|
|
'200':
|
|
description: Success. The response body contains Prometheus-compatible server metrics.
|
|
tags:
|
|
- Server information
|
|
/api/v3/configure/database:
|
|
get:
|
|
operationId: GetConfigureDatabase
|
|
summary: List databases
|
|
description: Retrieves a list of databases.
|
|
parameters:
|
|
- $ref: '#/components/parameters/formatRequired'
|
|
responses:
|
|
'200':
|
|
description: Success. The response body contains the list of databases.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ShowDatabasesResponse'
|
|
'400':
|
|
description: Bad request.
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'404':
|
|
description: Database not found.
|
|
tags:
|
|
- Databases
|
|
post:
|
|
operationId: PostConfigureDatabase
|
|
summary: Create a database
|
|
description: Creates a new database in the system.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CreateDatabaseRequest'
|
|
responses:
|
|
'201':
|
|
description: Success. Database created.
|
|
'400':
|
|
description: Bad request.
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'409':
|
|
description: Database already exists.
|
|
tags:
|
|
- Databases
|
|
delete:
|
|
operationId: DeleteConfigureDatabase
|
|
summary: Delete a database
|
|
description: |
|
|
Soft deletes a database.
|
|
The database is scheduled for deletion and unavailable for querying.
|
|
parameters:
|
|
- $ref: '#/components/parameters/db'
|
|
responses:
|
|
'200':
|
|
description: Success. Database deleted.
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'404':
|
|
description: Database not found.
|
|
tags:
|
|
- Databases
|
|
/api/v3/configure/table:
|
|
post:
|
|
operationId: PostConfigureTable
|
|
summary: Create a table
|
|
description: Creates a new table within a database.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CreateTableRequest'
|
|
responses:
|
|
'201':
|
|
description: Success. The table has been created.
|
|
'400':
|
|
description: Bad request.
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'404':
|
|
description: Database not found.
|
|
tags:
|
|
- Tables
|
|
delete:
|
|
operationId: DeleteConfigureTable
|
|
summary: Delete a table
|
|
description: |
|
|
Soft deletes a table.
|
|
The table is scheduled for deletion and unavailable for querying.
|
|
parameters:
|
|
- $ref: '#/components/parameters/db'
|
|
- name: table
|
|
in: query
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: Success (no content). The table has been deleted.
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'404':
|
|
description: Table not found.
|
|
tags:
|
|
- Tables
|
|
/api/v3/configure/distinct_cache:
|
|
post:
|
|
operationId: PostConfigureDistinctCache
|
|
summary: Create distinct cache
|
|
description: Creates a distinct cache for a table.
|
|
tags:
|
|
- Tables
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/DistinctCacheCreateRequest'
|
|
responses:
|
|
'201':
|
|
description: Success. The distinct cache has been created.
|
|
'204':
|
|
description: Not created. A distinct cache with this configuration already exists.
|
|
'400':
|
|
description: |
|
|
Bad request.
|
|
|
|
The server responds with status `400` if the request would overwrite an existing cache with a different configuration.
|
|
/api/v3/configure/last_cache:
|
|
post:
|
|
operationId: PostConfigureLastCache
|
|
summary: Create last cache
|
|
description: Creates a last cache for a table.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/LastCacheCreateRequest'
|
|
responses:
|
|
'201':
|
|
description: Success. Last cache created.
|
|
'400':
|
|
description: Bad request.
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'404':
|
|
description: Cache not found.
|
|
'409':
|
|
description: Cache already exists.
|
|
tags:
|
|
- Tables
|
|
delete:
|
|
operationId: DeleteConfigureLastCache
|
|
summary: Delete last cache
|
|
description: Deletes a last cache.
|
|
parameters:
|
|
- $ref: '#/components/parameters/db'
|
|
- name: table
|
|
in: query
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: name
|
|
in: query
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: Success. The last cache has been deleted.
|
|
'400':
|
|
description: Bad request.
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'404':
|
|
description: Cache not found.
|
|
tags:
|
|
- Tables
|
|
/api/v3/configure/processing_engine_trigger:
|
|
post:
|
|
operationId: PostConfigureProcessingEngineTrigger
|
|
summary: Create processing engine trigger
|
|
description: Creates a new processing engine trigger.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ProcessingEngineTriggerRequest'
|
|
responses:
|
|
'201':
|
|
description: Success. Processing engine trigger created.
|
|
'400':
|
|
description: Bad request.
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'404':
|
|
description: Trigger not found.
|
|
tags:
|
|
- Processing engine
|
|
delete:
|
|
operationId: DeleteConfigureProcessingEngineTrigger
|
|
summary: Delete processing engine trigger
|
|
description: Deletes a processing engine trigger.
|
|
parameters:
|
|
- $ref: '#/components/parameters/db'
|
|
- name: trigger_name
|
|
in: query
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: force
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
responses:
|
|
'200':
|
|
description: Success. The processing engine trigger has been deleted.
|
|
'400':
|
|
description: Bad request.
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'404':
|
|
description: Trigger not found.
|
|
tags:
|
|
- Processing engine
|
|
/api/v3/configure/processing_engine_trigger/disable:
|
|
post:
|
|
operationId: PostDisableProcessingEngineTrigger
|
|
summary: Disable processing engine trigger
|
|
description: Disables a processing engine trigger.
|
|
parameters:
|
|
- $ref: '#/components/parameters/ContentType'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ProcessingEngineTriggerRequest'
|
|
responses:
|
|
'200':
|
|
description: Success. The processing engine trigger has been disabled.
|
|
'400':
|
|
description: Bad request.
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'404':
|
|
description: Trigger not found.
|
|
tags:
|
|
- Processing engine
|
|
/api/v3/configure/processing_engine_trigger/enable:
|
|
post:
|
|
operationId: PostEnableProcessingEngineTrigger
|
|
summary: Enable processing engine trigger
|
|
description: Enables a processing engine trigger.
|
|
parameters:
|
|
- $ref: '#/components/parameters/ContentType'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ProcessingEngineTriggerRequest'
|
|
responses:
|
|
'200':
|
|
description: Success. The processing engine trigger has been enabled.
|
|
'400':
|
|
description: Bad request.
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'404':
|
|
description: Trigger not found.
|
|
tags:
|
|
- Processing engine
|
|
/api/v3/configure/plugin_environment/install_packages:
|
|
post:
|
|
operationId: PostInstallPluginPackages
|
|
summary: Install plugin packages
|
|
description: Installs packages for the plugin environment.
|
|
parameters:
|
|
- $ref: '#/components/parameters/ContentType'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
additionalProperties: true
|
|
responses:
|
|
'200':
|
|
description: Success. The packages have been installed.
|
|
'400':
|
|
description: Bad request.
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
tags:
|
|
- Processing engine
|
|
/api/v3/configure/plugin_environment/install_requirements:
|
|
post:
|
|
operationId: PostInstallPluginRequirements
|
|
summary: Install plugin requirements
|
|
description: Installs requirements for the plugin environment.
|
|
parameters:
|
|
- $ref: '#/components/parameters/ContentType'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
additionalProperties: true
|
|
responses:
|
|
'200':
|
|
description: Success. The requirements have been installed.
|
|
'400':
|
|
description: Bad request.
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
tags:
|
|
- Processing engine
|
|
/api/v3/plugin_test/wal:
|
|
post:
|
|
operationId: PostTestWALPlugin
|
|
summary: Test WAL plugin
|
|
description: Executes a test of a write-ahead logging (WAL) plugin.
|
|
responses:
|
|
'200':
|
|
description: Success. The plugin test has been executed.
|
|
'400':
|
|
description: Bad request.
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'404':
|
|
description: Plugin not enabled.
|
|
tags:
|
|
- Processing engine
|
|
/api/v3/plugin_test/schedule:
|
|
post:
|
|
operationId: PostTestSchedulingPlugin
|
|
summary: Test scheduling plugin
|
|
description: Executes a test of a scheduling plugin.
|
|
responses:
|
|
'200':
|
|
description: Success. The plugin test has been executed.
|
|
'400':
|
|
description: Bad request.
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'404':
|
|
description: Plugin not enabled.
|
|
tags:
|
|
- Processing engine
|
|
/api/v3/engine/{plugin_path}:
|
|
parameters:
|
|
- name: plugin_path
|
|
description: |
|
|
The path configured in the `trigger-spec` for the plugin.
|
|
|
|
For example, if you define a trigger with the following:
|
|
|
|
```
|
|
trigger-spec: "request:hello-world"
|
|
```
|
|
|
|
then, the HTTP API exposes the following plugin endpoint:
|
|
|
|
```
|
|
<INFLUXDB_HOST>/api/v3/engine/hello-world
|
|
```
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
get:
|
|
operationId: GetProcessingEnginePluginRequest
|
|
summary: On Request processing engine plugin request
|
|
description: |
|
|
Sends a request to invoke an _On Request_ processing engine plugin.
|
|
The request can include request headers, query string parameters, and a request body, which InfluxDB passes to the plugin.
|
|
|
|
An On Request plugin implements the following signature:
|
|
|
|
```python
|
|
def process_request(influxdb3_local, query_parameters, request_headers, request_body, args=None)
|
|
```
|
|
|
|
The response depends on the plugin implementation.
|
|
responses:
|
|
'200':
|
|
description: Success. The plugin request has been executed.
|
|
'400':
|
|
description: Malformed request.
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'404':
|
|
description: Plugin not found.
|
|
'500':
|
|
description: Processing failure.
|
|
tags:
|
|
- Processing engine
|
|
post:
|
|
operationId: PostProcessingEnginePluginRequest
|
|
summary: On Request processing engine plugin request
|
|
description: |
|
|
Sends a request to invoke an _On Request_ processing engine plugin.
|
|
The request can include request headers, query string parameters, and a request body, which InfluxDB passes to the plugin.
|
|
|
|
An On Request plugin implements the following signature:
|
|
|
|
```python
|
|
def process_request(influxdb3_local, query_parameters, request_headers, request_body, args=None)
|
|
```
|
|
|
|
The response depends on the plugin implementation.
|
|
parameters:
|
|
- $ref: '#/components/parameters/ContentType'
|
|
requestBody:
|
|
required: false
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
additionalProperties: true
|
|
responses:
|
|
'200':
|
|
description: Success. The plugin request has been executed.
|
|
'400':
|
|
description: Malformed request.
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'404':
|
|
description: Plugin not found.
|
|
'500':
|
|
description: Processing failure.
|
|
tags:
|
|
- Processing engine
|
|
components:
|
|
parameters:
|
|
AcceptQueryHeader:
|
|
name: Accept
|
|
in: header
|
|
schema:
|
|
type: string
|
|
default: application/json
|
|
enum:
|
|
- application/json
|
|
- application/jsonl
|
|
- application/vnd.apache.parquet
|
|
- text/csv
|
|
required: false
|
|
description: |
|
|
The content type that the client can understand.
|
|
ContentEncoding:
|
|
name: Content-Encoding
|
|
in: header
|
|
description: |
|
|
The compression applied to the line protocol in the request payload.
|
|
To send a gzip payload, pass `Content-Encoding: gzip` header.
|
|
schema:
|
|
$ref: '#/components/schemas/ContentEncoding'
|
|
required: false
|
|
ContentLength:
|
|
name: Content-Length
|
|
in: header
|
|
description: |
|
|
The size of the entity-body, in bytes, sent to InfluxDB.
|
|
schema:
|
|
$ref: '#/components/schemas/ContentLength'
|
|
ContentType:
|
|
name: Content-Type
|
|
description: |
|
|
The format of the data in the request body.
|
|
in: header
|
|
schema:
|
|
type: string
|
|
enum:
|
|
- application/json
|
|
required: false
|
|
db:
|
|
name: db
|
|
in: query
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: |
|
|
The name of the database.
|
|
dbWriteParam:
|
|
name: db
|
|
in: query
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: |
|
|
The name of the database.
|
|
The name of the database.
|
|
InfluxDB creates the database if it doesn't already exist, and then
|
|
writes all points in the batch to the database.
|
|
dbQueryParam:
|
|
name: db
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: string
|
|
description: |
|
|
The name of the database.
|
|
|
|
If you provide a query that specifies the database, you can omit the 'db' parameter from your request.
|
|
accept_partial:
|
|
name: accept_partial
|
|
in: query
|
|
required: false
|
|
schema:
|
|
$ref: '#/components/schemas/AcceptPartial'
|
|
compatibilityPrecisionParam:
|
|
name: precision
|
|
in: query
|
|
required: true
|
|
schema:
|
|
$ref: '#/components/schemas/PrecisionWriteCompatibility'
|
|
description: The precision for unix timestamps in the line protocol batch.
|
|
precisionParam:
|
|
name: precision
|
|
in: query
|
|
required: true
|
|
schema:
|
|
$ref: '#/components/schemas/PrecisionWrite'
|
|
description: The precision for unix timestamps in the line protocol batch.
|
|
querySqlParam:
|
|
name: q
|
|
in: query
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: SQL
|
|
description: |
|
|
The query to execute.
|
|
format:
|
|
name: format
|
|
in: query
|
|
required: false
|
|
schema:
|
|
$ref: '#/components/schemas/Format'
|
|
formatRequired:
|
|
name: format
|
|
in: query
|
|
required: true
|
|
schema:
|
|
$ref: '#/components/schemas/Format'
|
|
requestBodies:
|
|
lineProtocolRequestBody:
|
|
required: true
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
examples:
|
|
line:
|
|
summary: Example line protocol
|
|
value: measurement,tag=value field=1 1234567890
|
|
multiline:
|
|
summary: Example line protocol with UTF-8 characters
|
|
value: |
|
|
measurement,tag=value field=1 1234567890
|
|
measurement,tag=value field=2 1234567900
|
|
measurement,tag=value field=3 1234568000
|
|
queryRequestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/QueryRequestObject'
|
|
schemas:
|
|
ContentEncoding:
|
|
type: string
|
|
enum:
|
|
- gzip
|
|
- identity
|
|
description: |
|
|
Content coding.
|
|
Use `gzip` for compressed data or `identity` for unmodified, uncompressed data.
|
|
default: identity
|
|
LineProtocol:
|
|
type: string
|
|
enum:
|
|
- text/plain
|
|
- text/plain; charset=utf-8
|
|
description: |
|
|
`text/plain` is the content type for line protocol. `UTF-8` is the default character set.
|
|
default: text/plain; charset=utf-8
|
|
ContentLength:
|
|
type: integer
|
|
description: The length in decimal number of octets.
|
|
Database:
|
|
type: string
|
|
AcceptPartial:
|
|
type: boolean
|
|
default: true
|
|
description: Accept partial writes.
|
|
Format:
|
|
type: string
|
|
enum:
|
|
- json
|
|
- csv
|
|
- parquet
|
|
- jsonl
|
|
description: |
|
|
The format of data in the response body.
|
|
NoSync:
|
|
type: boolean
|
|
default: false
|
|
description: |
|
|
Do not sync writes.
|
|
|
|
By default, InfluxDB writes ingested data to the WAL file and then waits for the WAL to be persistend to disk before acknowledging the write.
|
|
|
|
If `no_sync=true`, InfluxDB writes ingested data to the WAL file and the server does not wait for the write to be persisted before acknowledging the write.
|
|
PrecisionWriteCompatibility:
|
|
enum:
|
|
- ms
|
|
- s
|
|
- us
|
|
- ns
|
|
type: string
|
|
description: |
|
|
The precision for unix timestamps in the line protocol batch.
|
|
Use `ms` for milliseconds, `s` for seconds, `us` for microseconds, or `ns` for nanoseconds.
|
|
PrecisionWrite:
|
|
enum:
|
|
- auto
|
|
- millisecond
|
|
- second
|
|
- microsecond
|
|
- nanosecond
|
|
type: string
|
|
description: |
|
|
The precision for unix timestamps in the line protocol batch.
|
|
QueryRequestObject:
|
|
type: object
|
|
properties:
|
|
database:
|
|
description: |
|
|
The name of the database to query.
|
|
Required if the query (`query_str`) doesn't specify the database.
|
|
type: string
|
|
query_str:
|
|
description: The query to execute.
|
|
type: string
|
|
format:
|
|
description: The format of the query results.
|
|
type: string
|
|
enum:
|
|
- json
|
|
- csv
|
|
- parquet
|
|
- jsonl
|
|
params:
|
|
description: |
|
|
Additional parameters for the query.
|
|
Use this field to pass query parameters.
|
|
type: object
|
|
additionalProperties: true
|
|
required:
|
|
- database
|
|
- query_str
|
|
example:
|
|
database: mydb
|
|
query_str: SELECT * FROM mytable
|
|
format: json
|
|
params: {}
|
|
CreateDatabaseRequest:
|
|
type: object
|
|
properties:
|
|
db:
|
|
type: string
|
|
required:
|
|
- db
|
|
CreateTableRequest:
|
|
type: object
|
|
properties:
|
|
db:
|
|
type: string
|
|
table:
|
|
type: string
|
|
tags:
|
|
type: array
|
|
items:
|
|
type: string
|
|
fields:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
type:
|
|
type: string
|
|
required:
|
|
- name
|
|
- type
|
|
required:
|
|
- db
|
|
- table
|
|
- tags
|
|
DistinctCacheCreateRequest:
|
|
type: object
|
|
properties:
|
|
db:
|
|
type: string
|
|
table:
|
|
type: string
|
|
name:
|
|
type: string
|
|
description: Optional cache name.
|
|
columns:
|
|
type: array
|
|
items:
|
|
type: string
|
|
max_cardinality:
|
|
type: integer
|
|
description: Optional maximum cardinality.
|
|
max_age:
|
|
type: integer
|
|
description: Optional maximum age in seconds.
|
|
required:
|
|
- db
|
|
- table
|
|
- columns
|
|
example:
|
|
db: mydb
|
|
table: mytable
|
|
columns:
|
|
- tag1
|
|
- tag2
|
|
max_cardinality: 1000
|
|
max_age: 3600
|
|
LastCacheCreateRequest:
|
|
type: object
|
|
properties:
|
|
db:
|
|
type: string
|
|
table:
|
|
type: string
|
|
name:
|
|
type: string
|
|
description: Optional cache name.
|
|
key_columns:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Optional list of key columns.
|
|
value_columns:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Optional list of value columns.
|
|
count:
|
|
type: integer
|
|
description: Optional count.
|
|
ttl:
|
|
type: integer
|
|
description: Optional time-to-live in seconds.
|
|
required:
|
|
- db
|
|
- table
|
|
example:
|
|
db: mydb
|
|
table: mytable
|
|
key_columns:
|
|
- tag1
|
|
value_columns:
|
|
- field1
|
|
count: 100
|
|
ttl: 3600
|
|
ProcessingEngineTriggerRequest:
|
|
type: object
|
|
properties:
|
|
db:
|
|
type: string
|
|
plugin_filename:
|
|
type: string
|
|
trigger_name:
|
|
type: string
|
|
trigger_specification:
|
|
type: string
|
|
trigger_arguments:
|
|
type: object
|
|
additionalProperties: true
|
|
disabled:
|
|
type: boolean
|
|
required:
|
|
- db
|
|
- plugin_filename
|
|
- trigger_name
|
|
- trigger_specification
|
|
ShowDatabasesResponse:
|
|
type: object
|
|
properties:
|
|
databases:
|
|
type: array
|
|
items:
|
|
type: string
|
|
QueryResponse:
|
|
type: object
|
|
properties:
|
|
results:
|
|
type: array
|
|
items:
|
|
type: object
|
|
example:
|
|
results:
|
|
- series:
|
|
- name: mytable
|
|
columns:
|
|
- time
|
|
- value
|
|
values:
|
|
- - '2024-02-02T12:00:00Z'
|
|
- 42
|
|
ErrorMessage:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
data:
|
|
type: object
|
|
nullable: true
|
|
LineProtocolError:
|
|
properties:
|
|
code:
|
|
description: Code is the machine-readable error code.
|
|
enum:
|
|
- internal error
|
|
- not found
|
|
- conflict
|
|
- invalid
|
|
- empty value
|
|
- unavailable
|
|
readOnly: true
|
|
type: string
|
|
err:
|
|
description: Stack of errors that occurred during processing of the request. Useful for debugging.
|
|
readOnly: true
|
|
type: string
|
|
line:
|
|
description: First line in the request body that contains malformed data.
|
|
format: int32
|
|
readOnly: true
|
|
type: integer
|
|
message:
|
|
description: Human-readable message.
|
|
readOnly: true
|
|
type: string
|
|
op:
|
|
description: Describes the logical code operation when the error occurred. Useful for debugging.
|
|
readOnly: true
|
|
type: string
|
|
required:
|
|
- code
|
|
EpochCompatibility:
|
|
description: |
|
|
A unix timestamp precision.
|
|
- `h` for hours
|
|
- `m` for minutes
|
|
- `s` for seconds
|
|
- `ms` for milliseconds
|
|
- `u` or `µ` for microseconds
|
|
- `ns` for nanoseconds
|
|
enum:
|
|
- ns
|
|
- u
|
|
- µ
|
|
- ms
|
|
- s
|
|
- m
|
|
- h
|
|
type: string
|
|
responses:
|
|
Unauthorized:
|
|
description: Unauthorized access.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorMessage'
|
|
BadRequest:
|
|
description: |
|
|
Request failed. Possible reasons:
|
|
|
|
- Invalid database name
|
|
- Malformed request body
|
|
- Invalid timestamp precision
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorMessage'
|
|
Forbidden:
|
|
description: Access denied.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorMessage'
|
|
NotFound:
|
|
description: Resource not found.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorMessage'
|
|
securitySchemes:
|
|
BearerAuth:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: JWT
|
|
description: |
|
|
_During Alpha release, an API token is not required._
|
|
|
|
A Bearer token for authentication.
|
|
|
|
Provide the scheme and the API token in the `Authorization` header--for example:
|
|
|
|
```bash
|
|
curl http://localhost:8181/api/v3/query_influxql \
|
|
--header "Authorization: Bearer API_TOKEN"
|
|
```
|
|
x-tagGroups:
|
|
- name: Using the InfluxDB HTTP API
|
|
tags:
|
|
- Quick start
|
|
- Authentication
|
|
- Common parameters
|
|
- Response codes
|
|
- Compatibility endpoints
|
|
- Data I/O
|
|
- Databases
|
|
- Processing engine
|
|
- Server information
|
|
- Tables
|