Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #1197 from influxdata/1x-compatibility=api 

1.x compatibility APIs and InfluxQL support
pull/1202/head
Scott Anderson 2020-07-11 22:33:30 -06:00 committed by GitHub
parent 3746a06827 685a2b3835
commit a3ff8fdb34
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 521 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
CONTRIBUTING.md
View File

@ -625,6 +625,19 @@ http://localhost:9999
``` ```
~~~ ~~~
### Code examples only supported in InfluxDB Cloud
Some functionality is only supported in InfluxDB Cloud and code examples should
only use InfluxDB Cloud URLs. In these cases, use `https://cloud2.influxdata.com`
as the placeholder in the code block. It will get updated on page load and when
users select a Cloud region in the URL select modal.
~~~
```sh
# This URL will get updated
https://cloud2.influxdata.com
```
~~~
## New Versions of InfluxDB ## New Versions of InfluxDB
Version bumps occur regularly in the documentation. Version bumps occur regularly in the documentation.
Each minor version has its own directory with unique content. Each minor version has its own directory with unique content.

12
assets/js/influxdb-url.js
View File

@ -1,4 +1,6 @@
var defaultUrl = "http://localhost:9999" var defaultUrl = "http://localhost:9999"
var placeholderCloudUrl = "https://cloud2.influxdata.com"
var defaultCloudUrl = "https://us-west-2-1.aws.cloud2.influxdata.com"
var elementSelector = ".article--content pre:not(.preserve)" var elementSelector = ".article--content pre:not(.preserve)"
// Retrieve the selected URL from the influxdb_url session cookie // Retrieve the selected URL from the influxdb_url session cookie
@ -99,6 +101,16 @@ updateUrls(defaultUrl, getUrl())
// Append URL selector buttons to code blocks // Append URL selector buttons to code blocks
appendUrlSelector(getUrl()) appendUrlSelector(getUrl())
// Append URL selector buttons to cloud-only code blocks
appendUrlSelector(placeholderCloudUrl)
// Update cloud-only URLs on load
if (cloudUrls.includes(getUrl())) {
updateUrls(placeholderCloudUrl, getUrl())
} else {
updateUrls(placeholderCloudUrl, defaultCloudUrl)
}
// Update URLs whenever you focus on the browser tab // Update URLs whenever you focus on the browser tab
$(window).focus(function() { $(window).focus(function() {
updateUrls(getPrevUrl(), getUrl()) updateUrls(getPrevUrl(), getUrl())

12
assets/styles/layouts/article/_code.scss
View File

@ -60,6 +60,18 @@ pre {
} }
} }
pre .api {
margin-right: .35rem;
padding: .15rem .5rem .25rem;
border-radius: $radius;
color: $g20-white;
font-weight: bold;
font-size: .9rem;
&.get { background: $gr-rainforest; }
&.post { background: $b-ocean; }
}
//////////////////////////////////////////////////////////////////////////////// ////////////////////////////////////////////////////////////////////////////////
///////////////////////////////// MEDIA QUERIES //////////////////////////////// ///////////////////////////////// MEDIA QUERIES ////////////////////////////////
//////////////////////////////////////////////////////////////////////////////// ////////////////////////////////////////////////////////////////////////////////

89
content/v2.0/query-data/influxql.md Normal file
View File

@ -0,0 +1,89 @@
---
title: Query data with InfluxQL
description: >
Use the [InfluxDB 1.x `/query` compatibility endpoint](/v2.0/reference/api/influxdb-1x/query)
to query data in InfluxDB 2.0 with **InfluxQL**.
weight: 102
v2.0/tags: [influxql, query]
menu:
v2_0:
name: Query with InfluxQL
parent: Query data
products: [cloud]
related:
- /v2.0/reference/api/influxdb-1x/
- /v2.0/reference/api/influxdb-1x/query
- /v2.0/reference/api/influxdb-1x/dbrp
---
Use the [InfluxDB 1.x `/query` compatibility endpoint](/v2.0/reference/api/influxdb-1x/query)
to query data in InfluxDB 2.0 with **InfluxQL**.
The [InfluxDB 1.x compatibility API](/v2.0/reference/api/influxdb-1x/) supports
all InfluxDB 1.x client libraries and integrations in InfluxDB 2.0.
Provide the following:
- InfluxDB [authentication token](/v2.0/security/tokens/)
_(See [compatibility API authentication](/v2.0/reference/api/influxdb-1x/#authentication))_
- **db query parameter**: 1.x database to query
- **rp query parameter**: 1.x retention policy to query
- **q query parameter**: InfluxQL query
{{% note %}}
**URL-encode** the InfluxQL query to ensure it's formatted correctly when submitted to InfluxDB.
{{% /note %}}
```sh
curl -G https://cloud2.influxdata.com/query?db=db&rp=rp \
-H "Authorization: Token YourAuthToken" \
--data-urlencode "q=SELECT used_percent FROM mem WHERE host=host1"
```
By default, the `/query` compatibility endpoint returns results in **JSON**.
To return results as **CSV**, include the `Accept: application/csv` header.
## Database and retention policy mapping
InfluxDB 2.0 combines the 1.x concept of [databases](https://docs.influxdata.com/influxdb/v1.8/concepts/glossary/#database)
and [retention policies](https://docs.influxdata.com/influxdb/v1.8/concepts/glossary/#retention-policy-rp)
into [buckets](/v2.0/reference/glossary/#bucket).
To support InfluxDB 1.x query and write patterns in InfluxDB 2.0, databases and retention
policies are mapped to buckets using the **database and retention policy (DBRP) mapping service**.
_See [DBRP mapping](/v2.0/reference/api/influxdb-1x/dbrp/) for more information._
## InfluxQL support
InfluxQL in InfluxDB 2.0 supports **read-only** queries.
{{< flex >}}
{{< flex-content >}}
{{% note %}}
##### Supported InfluxQL queries
- `SELECT` _(read-only)_
- `SHOW DATABASES`
- `SHOW MEASUREMENTS`
- `SHOW TAG KEYS`
- `SHOW TAG VALUES`
- `SHOW FIELD KEYS`
{{% /note %}}
{{< /flex-content >}}
{{< flex-content >}}
{{% warn %}}
##### Unsupported InfluxQL queries
- `SELECT INTO`
- `ALTER`
- `CREATE`
- `DELETE`
- `DROP`
- `GRANT`
- `KILL`
- `REVOKE`
{{% /warn %}}
{{< /flex-content >}}
{{< /flex >}}
Use the InfluxDB 2.0 UI, CLI, and API to perform the following actions:
- [Create and manage buckets](/v2.0/organizations/buckets/)
- [Manage users in InfluxDB Cloud](/v2.0/account-management/multi-user/)
- [Delete data](/v2.0/reference/cli/influx/delete/)

62
content/v2.0/reference/api/influxdb-1x/_index.md Normal file
View File

@ -0,0 +1,62 @@
---
title: InfluxDB 1.x compatibility API
description: >
placeholder
menu:
v2_0_ref:
name: 1.x compatibility
parent: InfluxDB v2 API
weight: 104
v2.0/tags: [influxql, query, write]
products: [cloud]
related:
- /v2.0/query-data/influxql
---
The InfluxDB v2 API includes InfluxDB 1.x compatibility endpoints that work with
InfluxDB 1.x client libraries and third-party integrations like [Grafana](https://grafana.com) and others.
## Authentication
InfluxDB 2.0 requires all query and write requests to be authenticated.
Use **basic authentication** or **token authentication** to authenticate requests to
InfluxDB 1.x compatibility endpoints.
### Basic Authentication
Basic authentications requires the following credentials:
- **username**: InfluxDB username
- **password**: InfluxDB [authentication token](/v2.0/security/tokens/)
There are multiple ways to provide basic authentication credentials.
The example below uses the `Authorization` header with the `Basic` scheme to
provide the required credentials:
##### Basic authentication with authorization header
```sh
# Header syntax
Authorization: Basic <username>:<password>
# Header example
Authorization: Basic admin:mYSuP3rs3cREtT0k3N
```
### Token Authentication
Token authentication requires the following credential:
- **token**: InfluxDB [authentication token](/v2.0/security/tokens/)
Use the `Authorization` header with the `Token` scheme to provide your
authentication token to InfluxDB.
##### Token authentication with authorization header
```sh
# Header syntax
Authorization: Token <token>
# Header example
Authorization: Token mYSuP3rs3cREtT0k3N
```
## Compatibility endpoints
{{< children readmore=true >}}

99
content/v2.0/reference/api/influxdb-1x/dbrp.md Normal file
View File

@ -0,0 +1,99 @@
---
title: Database and retention policy mapping
description: >
The database and retention policy (DBRP) mapping service maps InfluxDB 1.x
database and retention policy combinations to InfluxDB 2.0 buckets.
menu:
v2_0_ref:
name: DBRP mapping
parent: 1.x compatibility
weight: 302
products: [cloud]
related:
- /v2.0/reference/api/influxdb-1x/query
- /v2.0/reference/api/influxdb-1x/write
- /v2.0/api/#tag/DBRPs, InfluxDB 2.0 API /dbrps endpoint
---
The InfluxDB 1.x data model includes [databases](https://docs.influxdata.com/influxdb/v1.8/concepts/glossary/#database)
and [retention policies](https://docs.influxdata.com/influxdb/v1.8/concepts/glossary/#retention-policy-rp).
InfluxDB 2.0 replaces both with [buckets](/v2.0/reference/glossary/#bucket).
To support InfluxDB 1.x query and write patterns in InfluxDB 2.0, databases and retention
policies are mapped to buckets using the **database and retention policy (DBRP) mapping service**.
The DBRP mapping service uses the **database** and **retention policy** specified in
[compatibility API](/v2.0/reference/api/influxdb-1x/) requests to route operations to a bucket.
[Create DBRP mappings automatically](#dbrp-mapping-behavior) with the `/write` compatibility endpoint or
[create DBRP mappings manually](#manually-create-and-manage-dbrp-mappings) using the `/api/v2/dbrps` API endpoint.
- [DBRP mapping behavior](#dbrp-mapping-behavior)
- [Manually create and manage DBRP mappings](#manually-create-and-manage-dbrp-mappings)
### Default retention policies
A database can have multiple retention policies with one set as default.
If no retention policy is specified in a query or write request, InfluxDB uses
the default retention policy for the specified database.
## DBRP mapping behavior
- [When writing data](#when-writing-data)
- [When querying data](#when-querying-data)
### When writing data
When writing data to InfluxDB 2.0 using the [`/write` compatibility endpoint](/v2.0/reference/api/influxdb-1x/write/),
the DBRP mapping service checks for a bucket mapped to the database and retention policy:
- If a mapped bucket is found, data is written to the bucket.
- If an unmapped bucket with a name matching:
- **database/retention policy** exists, a DBRP mapping is added to the bucket,
and data is written to the bucket.
- **database** exists (without a specified retention policy), the default
database retention policy is used, a DBRP mapping is added to the bucket,
and data is written to the bucket.
- If no matching bucket is found, a new **database/retention-policy** bucket is
created with a DBRP mapping, and data is written to the bucket.
If no retention policy is specified, `autogen` is used.
{{% note %}}
To automatically create new buckets, the authentication token used for the
write request must be an **All Access token**.
{{% /note %}}
### When querying data
When querying data from InfluxDB 2.0 using the [`/query` compatibility endpoint](/v2.0/reference/api/influxdb-1x/query/),
the DBRP mapping service checks for the specified database and retention policy
(if no retention policy is specified, the database's default retention policy is used):
- If a mapped bucket exists, data is queried from the mapped bucket.
- If no mapped bucket exists, InfluxDB returns an error.
## Manually create and manage DBRP mappings
If you have an existing bucket that does't follow the **database/retention-policy**
naming convention, you **must** manually create a database and retention policy
mapping to query that bucket with the `/query` compatibility API.
Use the using the [`/api/v2/dbrps` API endpoint](/v2.0/api/#tag/DBRPs) to
manually create and manage DBRP mappings.
**To manually create a DBRP mapping, provide the following:**
- authentication token
- organization name or ID
- target bucket ID
- database to map
- retention policy to map
<!-- -->
```sh
curl -XPOST https://cloud2.influxdata.com/api/v2/dbrps \
-H "Authorization: Token YourAuthToken" \
-H 'Content-type: application/json' \
-d '{
"org": "example-org",
"bucketID": "12ab34cd56ef",
"database": "example-db",
"retention_policy": "example-rp",
"default": true
}'
```
_For more information, see the [`/api/v2/dbrps` endpoint documentation](/v2.0/api/#tag/DBRPs)._

125
content/v2.0/reference/api/influxdb-1x/query.md Normal file
View File

@ -0,0 +1,125 @@
---
title: /query 1.x compatibility API
list_title: /query
description: >
The `/query` 1.x compatibility endpoint queries InfluxDB 2.0 using **InfluxQL**.
menu:
v2_0_ref:
name: /query
parent: 1.x compatibility
weight: 301
v2.0/tags: [influxql, query]
products: [cloud]
list_code_example: |
<pre>
<span class="api get">GET</span> https://cloud2.influxdata.com/query
</pre>
related:
- /v2.0/query-data/influxql
---
The `/query` 1.x compatibility endpoint queries InfluxDB 2.0 using **InfluxQL**.
Use the `GET` request method to query data from the `/query` endpoint.
<pre>
<span class="api get">GET</span> https://cloud2.influxdata.com/query
</pre>
The `/query` compatibility endpoint use the **database** and **retention policy**
specified in the query request to map the request to an InfluxDB 2.0 bucket.
For more information, see [Database and retention policy mapping](/v2.0/reference/api/influxdb-1x/dbrp).
{{% note %}}
If you have an existing bucket that does't follow the **database/retention-policy** naming convention,
you **must** [manually create a database and retention policy mapping](/v2.0/reference/api/influxdb-1x/dbrp/#manually-create-and-manage-dbrp-mappings)
to query that bucket with the `/query` compatibility API.
{{% /note %}}
## Authentication
Use **basic authentication** or **token authentication**.
_For more information, see [Authentication](/v2.0/reference/api/influxdb-1x/#authentication)._
## Query string parameters
{{% note %}}
**URL-encode** all query string parameters.
{{% /note %}}
### db
<span class="req">Required</span> – The **database** to query data from.
This is mapped to an InfluxDB 2.0 [bucket](/v2.0/reference/glossary/#bucket).
_See [Database and retention policy mapping](/v2.0/reference/api/influxdb-1x/dbrp/)._
### rp
The **retention policy** to query data from.
This is mapped to an InfluxDB 2.0 [bucket](/v2.0/reference/glossary/#bucket).
_See [Database and retention policy mapping](/v2.0/reference/api/influxdb-1x/dbrp/)._
### q
<span class="req">Required</span> – The **InfluxQL** query to execute.
To execute multiple queries, delimit queries with a semicolon (`;`).
### epoch
Return results with [Unix timestamps](/v2.0/reference/glossary/#unix-timestamp)
(also known as epoch timestamps) in the specified precision instead of
[RFC3339 timestamps](/v2.0/reference/glossary/#rfc3339-timestamp) with nanosecond precision.
The following precisions are available:
- `ns` - nanoseconds
- `u` or `µ` - microseconds
- `ms` - milliseconds
- `s` - seconds
- `m` - minutes
- `h` - hours
## Query examples
- [Query using basic authentication](#query-using-basic-authentication)
- [Query a non-default retention policy](#query-a-non-default-retention-policy)
- [Execute multiple queries](#execute-multiple-queries)
- [Return query results with millisecond Unix timestamps](#return-query-results-with-millisecond-unix-timestamps)
- [Use `curl` to execute InfluxQL queries from a file](#use-curl-to-execute-influxql-queries-from-a-file)
##### Query using basic authentication
```sh
curl -G https://cloud2.influxdata.com/query \
-u username:YourAuthToken \
--data-urlencode "db=mydb" \
--data-urlencode "q=SELECT used_percent FROM mem WHERE host=host1"
```
##### Query a non-default retention policy
```sh
curl -G https://cloud2.influxdata.com/query \
-H "Authorization: Basic username:YourAuthToken" \
--data-urlencode "db=mydb" \
--data-urlencode "rp=customrp" \
--data-urlencode "q=SELECT used_percent FROM mem WHERE host=host1"
```
##### Execute multiple queries
```sh
curl -G https://cloud2.influxdata.com/query \
-H "Authorization: Token YourAuthToken" \
--data-urlencode "db=mydb" \
--data-urlencode "q=SELECT * FROM mem WHERE host=host1;SELECT mean(used_percent) FROM mem WHERE host=host1 GROUP BY time(10m)"
```
##### Return query results with millisecond Unix timestamps
```sh
curl -G https://cloud2.influxdata.com/query \
-H "Authorization: Token YourAuthToken" \
--data-urlencode "db=mydb" \
--data-urlencode "rp=myrp" \
--data-urlencode "q=SELECT used_percent FROM mem WHERE host=host1"
--data-urlencode "epoch=ms"
```
##### Use curl to execute InfluxQL queries from a file
```sh
curl -G https://cloud2.influxdata.com/query \
-H "Authorization: Token YourAuthToken" \
--data-urlencode "db=mydb" \
-F "q=@path/to/influxql.txt"
-F "async=true"
```

108
content/v2.0/reference/api/influxdb-1x/write.md Normal file
View File

@ -0,0 +1,108 @@
---
title: /write 1.x compatibility API
list_title: /write
description: >
The `/write` 1.x compatibilty endpoint writes data to InfluxDB 2.0 using patterns from the
InfluxDB 1.x `/write` API endpoint.
menu:
v2_0_ref:
name: /write
parent: 1.x compatibility
weight: 301
v2.0/tags: [write]
products: [cloud]
list_code_example: |
<pre>
<span class="api post">POST</span> https://cloud2.influxdata.com/write
</pre>
related:
- /v2.0/reference/syntax/line-protocol
---
The `/write` 1.x compatibilty endpoint writes data to InfluxDB 2.0 using patterns from the
InfluxDB 1.x `/write` API endpoint.
Use the `POST` request method to write [line protocol](/v2.0/reference/syntax/line-protocol/)
to the `/write` endpoint.
<pre>
<span class="api post">POST</span> https://cloud2.influxdata.com/write
</pre>
## Authentication
Use **basic authentication** or **token authentication**.
_For more information, see [Authentication](/v2.0/reference/api/influxdb-1x/#authentication)._
## Request body
Include your line protocol in the request body.
**Binary encode** the line protocol to prevent unintended formatting.
The examples [below](#write-examples) use the curl `--data-binary` flag to binary
encode the line protocol.
## Query string parameters
### db
<span class="req">Required</span> – The **database** to write data to.
This is mapped to an InfluxDB 2.0 [bucket](/v2.0/reference/glossary/#bucket).
_See [Database and retention policy mapping](/v2.0/reference/api/influxdb-1x/dbrp/)._
### rp
The **retention policy** to write data to.
This is mapped to an InfluxDB 2.0 [bucket](/v2.0/reference/glossary/#bucket).
_See [Database and retention policy mapping](/v2.0/reference/api/influxdb-1x/dbrp/)._
### precision
The precision of [Unix timestamps](/v2.0/reference/glossary/#unix-timestamp) in the line protocol.
Default is nanosconds (`ns`).
The following precisions are available:
- `ns` - nanoseconds
- `u` or `µ` - microseconds
- `ms` - milliseconds
- `s` - seconds
- `m` - minutes
- `h` - hours
## Write examples
- [Write data using basic authentication](#write-data-using-basic-authentication)
- [Write data to a non-default retention policy](#write-data-to-a-non-default-retention-policy)
- [Write multiple lines of line protocol](#write-multiple-lines-of-line-protocol)
- [Write data with millisecond Unix timestamps](#write-data-with-millisecond-unix-timestamps)
- [Use curl to write data from a file](#use-curl-to-write-data-from-a-file)
##### Write data using basic authentication
```sh
curl -XPOST https://cloud2.influxdata.com/write?db=mydb \
-H "Authorization: Basic username:YourAuthToken" \
--data-binary "measurement,host=host1 field1=2i,field2=2.0 1577836800000000000"
```
##### Write data to a non-default retention policy
```sh
curl -XPOST https://cloud2.influxdata.com/write?db=mydb&rp=customrp \
-H "Authorization: Basic username:YourAuthToken" \
--data-binary "measurement,host=host1 field1=2i,field2=2.0 1577836800000000000"
```
##### Write multiple lines of line protocol
```sh
curl -XPOST https://cloud2.influxdata.com/write?db=mydb \
-H "Authorization: Token YourAuthToken" \
--data-binary "measurement,host=host1 field1=2i,field2=2.0 1577836800000000000
measurement,host=host2 field1=14i,field2=12.7 1577836800000000000
measurement,host=host3 field1=5i,field2=6.8 1577836800000000000"
```
##### Write data with millisecond Unix timestamps
```sh
curl -XPOST https://cloud2.influxdata.com/write?db=mydb&precision=ms \
-H "Authorization: Token YourAuthToken" \
--data-binary "measurement,host=host1 field1=2i,field2=2.0 1577836800000"
```
##### Use curl to write data from a file
```sh
curl -XPOST https://cloud2.influxdata.com/write?db=mydb \
-H "Authorization: Token YourAuthToken" \
--data-binary @path/to/line-protocol.txt
```

1
content/v2.0/reference/cli/influx/delete/_index.md
View File

@ -11,6 +11,7 @@ v2.0/tags: [delete]
The `influx delete` command deletes [points](/v2.0/reference/glossary/#point) The `influx delete` command deletes [points](/v2.0/reference/glossary/#point)
from an InfluxDB bucket. from an InfluxDB bucket.
Identify points to delete using [delete predicate syntax](/v2.0/reference/syntax/delete-predicate).
## Usage ## Usage
``` ```