Add note about mapping a single DBRP to a single bucket (#4054)
* add note about mapping a single DBRP to a single bucket, closes influxdata/DAR#298 * removed read-only query descriptor in influxql docpull/4057/head^2
Scott Anderson
GitHub
parent
8856073366
commit
331ee73812
|
|
@ -15,165 +15,4 @@ related:
|
|||
- /influxdb/cloud/reference/api/influxdb-1x/dbrp
|
||||
---
|
||||
|
||||
In InfluxDB 1.x, data is stored in [databases](/{{< latest "influxdb" "v1" >}}/concepts/glossary/#database)
|
||||
and [retention policies](/{{< latest "influxdb" "v1" >}}/concepts/glossary/#retention-policy-rp).
|
||||
In InfluxDB Cloud, data is stored in [buckets](/influxdb/cloud/reference/glossary/#bucket).
|
||||
Because InfluxQL uses the 1.x data model, a bucket must be mapped to a database and retention policy (DBRP) before it can be queried using InfluxQL.
|
||||
|
||||
{{% note %}}
|
||||
#### InfluxQL reference documentation
|
||||
For complete InfluxQL reference documentation, see
|
||||
[Influx Query Language in the latest InfluxDB 1.x documentation](/{{< latest "influxdb" "v1" >}}/query_language/).
|
||||
{{% /note %}}
|
||||
|
||||
**To use InfluxQL to query bucket data, complete the following steps:**
|
||||
|
||||
1. [Verify buckets have a mapping](#verify-buckets-have-a-mapping).
|
||||
2. [Map unmapped buckets](#map-unmapped-buckets).
|
||||
3. [Query a mapped bucket with InfluxQL](#query-a-mapped-bucket-with-influxql).
|
||||
|
||||
## Verify buckets have a mapping
|
||||
|
||||
{{% note %}}
|
||||
When writing to an InfluxDB Cloud bucket using the `/write` 1.x compatibility API,
|
||||
InfluxDB Cloud automatically creates a DBRP mapping for the bucket that matches the `db/rp` naming convention.
|
||||
For more information, see [Database and retention policy mapping](/influxdb/cloud/reference/api/influxdb-1x/dbrp/).
|
||||
If you're not sure how data was written into a bucket, verify the bucket has a mapping.
|
||||
{{% /note %}}
|
||||
|
||||
Use the [`/api/v2/dbrps` API endpoint](/influxdb/cloud/api/#operation/GetDBRPs) to list DBRP mappings.
|
||||
Include the following:
|
||||
|
||||
- **Request method:** `GET`
|
||||
- **Headers:**
|
||||
- **Authorization:** `Token` schema with your InfluxDB [API token](/influxdb/cloud/security/tokens/)
|
||||
- **Query parameters:**
|
||||
{{< req type="key" >}}
|
||||
- {{< req "\*" >}} **organization_id:** [organization ID](/influxdb/cloud/organizations/view-orgs/#view-your-organization-id)
|
||||
- **bucket_id:** [bucket ID](/influxdb/cloud/organizations/buckets/view-buckets/) _(to list DBRP mappings for a specific bucket)_
|
||||
- **database:** database name _(to list DBRP mappings with a specific database name)_
|
||||
- **retention_policy:** retention policy name _(to list DBRP mappings with a specific retention policy name)_
|
||||
- **id:** DBRP mapping ID _(to list a specific DBRP mapping)_
|
||||
|
||||
##### View all DBRP mappings
|
||||
```sh
|
||||
curl --request GET \
|
||||
https://cloud2.influxdata.com/api/v2/dbrps?organization_id=00oxo0oXx000x0Xo \
|
||||
--header "Authorization: Token YourAuthToken"
|
||||
```
|
||||
|
||||
##### Filter DBRP mappings by database
|
||||
```sh
|
||||
curl --request GET \
|
||||
https://cloud2.influxdata.com/api/v2/dbrps?organization_id=00oxo0oXx000x0Xo&database=example-db \
|
||||
--header "Authorization: Token YourAuthToken"
|
||||
```
|
||||
|
||||
##### Filter DBRP mappings by bucket ID
|
||||
```sh
|
||||
curl --request GET \
|
||||
https://cloud2.influxdata.com/api/v2/dbrps?organization_id=00oxo0oXx000x0Xo&bucket_id=00oxo0oXx000x0Xo \
|
||||
--header "Authorization: Token YourAuthToken"
|
||||
```
|
||||
|
||||
If you **do not find a DBRP mapping for a bucket**, complete the next procedure to map the unmapped bucket.
|
||||
_For more information on the DBRP mapping API, see the [`/api/v2/dbrps` endpoint documentation](/influxdb/cloud/api/#tag/DBRPs)._
|
||||
|
||||
## Map unmapped buckets
|
||||
Use the [`/api/v2/dbrps` API endpoint](/influxdb/cloud/api/#operation/PostDBRP)
|
||||
to create a new DBRP mapping for a bucket.
|
||||
Include the following:
|
||||
|
||||
- **Request method:** `POST`
|
||||
- **Headers:**
|
||||
- **Authorization:** `Token` schema with your InfluxDB [API token](/influxdb/cloud/security/tokens/)
|
||||
- **Content-type:** `application/json`
|
||||
- **Request body:** JSON object with the following fields:
|
||||
{{< req type="key" >}}
|
||||
- {{< req "\*" >}} **bucket_id:** [bucket ID](/influxdb/cloud/organizations/buckets/view-buckets/)
|
||||
- {{< req "\*" >}} **database:** database name
|
||||
- **default:** set the provided retention policy as the default retention policy for the database
|
||||
- {{< req "\*" >}} **organization** or **organization_id:** organization name or [organization ID](/influxdb/cloud/organizations/view-orgs/#view-your-organization-id)
|
||||
- {{< req "\*" >}} **retention_policy:** retention policy name
|
||||
|
||||
<!-- -->
|
||||
```sh
|
||||
curl --request POST https://cloud2.influxdata.com/api/v2/dbrps \
|
||||
--header "Authorization: Token YourAuthToken" \
|
||||
--header 'Content-type: application/json' \
|
||||
--data '{
|
||||
"bucket_id": "00oxo0oXx000x0Xo",
|
||||
"database": "example-db",
|
||||
"default": true,
|
||||
"organization_id": "00oxo0oXx000x0Xo",
|
||||
"retention_policy": "example-rp"
|
||||
}'
|
||||
```
|
||||
|
||||
After you've verified the bucket is mapped, query the bucket using the `query` 1.x compatibility endpoint.
|
||||
|
||||
## Query a mapped bucket with InfluxQL
|
||||
|
||||
The [InfluxDB 1.x compatibility API](/influxdb/cloud/reference/api/influxdb-1x/) supports
|
||||
all InfluxDB 1.x client libraries and integrations in InfluxDB Cloud.
|
||||
|
||||
To query a mapped bucket with InfluxQL, use the [`/query` 1.x compatibility endpoint](/influxdb/cloud/reference/api/influxdb-1x/query/).
|
||||
Include the following in your request:
|
||||
|
||||
- **Request method:** `GET`
|
||||
- **Headers:**
|
||||
- **Authorization:** _See [compatibility API authentication](/influxdb/cloud/reference/api/influxdb-1x/#authentication)_
|
||||
- **Query parameters:**
|
||||
- **db**: 1.x database to query
|
||||
- **rp**: 1.x retention policy to query _(if no retention policy is specified, InfluxDB uses the default retention policy for the specified database)_
|
||||
- **q**: URL-encoded InfluxQL query
|
||||
|
||||
{{% api/url-encode-note %}}
|
||||
|
||||
```sh
|
||||
curl --get https://cloud2.influxdata.com/query?db=example-db \
|
||||
--header "Authorization: Token YourAuthToken" \
|
||||
--data-urlencode "q=SELECT used_percent FROM example-db.example-rp.example-measurement WHERE host=host1"
|
||||
```
|
||||
|
||||
By default, the `/query` compatibility endpoint returns results in **JSON**.
|
||||
To return results as **CSV**, include the `Accept: application/csv` header.
|
||||
|
||||
## InfluxQL support
|
||||
|
||||
InfluxDB Cloud supports InfluxQL **read-only** queries. See supported and unsupported queries below.
|
||||
To learn more about InfluxQL, see [Influx Query Language (InfluxQL)](/{{< latest "influxdb" "v1" >}}/query_language/).
|
||||
|
||||
{{< flex >}}
|
||||
{{< flex-content >}}
|
||||
{{% note %}}
|
||||
##### Supported InfluxQL queries
|
||||
|
||||
- `DELETE`*
|
||||
- `DROP MEASUREMENT`*
|
||||
- `EXPLAIN ANALYZE`
|
||||
- `SELECT` _(read-only)_
|
||||
- `SHOW DATABASES`
|
||||
- `SHOW MEASUREMENTS`
|
||||
- `SHOW TAG KEYS`
|
||||
- `SHOW TAG VALUES`
|
||||
- `SHOW FIELD KEYS`
|
||||
|
||||
\* These commands delete data.
|
||||
{{% /note %}}
|
||||
{{< /flex-content >}}
|
||||
{{< flex-content >}}
|
||||
{{% warn %}}
|
||||
|
||||
##### Unsupported InfluxQL queries
|
||||
|
||||
- `SELECT INTO`
|
||||
- `ALTER`
|
||||
- `CREATE`
|
||||
- `DROP` _(limited support)_
|
||||
- `GRANT`
|
||||
- `KILL`
|
||||
- `REVOKE`
|
||||
{{% /warn %}}
|
||||
{{< /flex-content >}}
|
||||
{{< /flex >}}
|
||||
{{< duplicate-oss >}}
|
||||
|
|
|
|||
|
|
@ -12,6 +12,7 @@ related:
|
|||
- /influxdb/cloud/reference/api/influxdb-1x/query
|
||||
- /influxdb/cloud/reference/api/influxdb-1x/write
|
||||
- /influxdb/cloud/api/#tag/DBRPs, InfluxDB v2 API /dbrps endpoint
|
||||
- /influxdb/cloud/query-data/influxql/
|
||||
---
|
||||
|
||||
{{% duplicate-oss %}}
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@ related:
|
|||
|
||||
In InfluxDB 1.x, data is stored in [databases](/{{< latest "influxdb" "v1" >}}/concepts/glossary/#database)
|
||||
and [retention policies](/{{< latest "influxdb" "v1" >}}/concepts/glossary/#retention-policy-rp).
|
||||
In InfluxDB OSS {{< current-version >}}, data is stored in [buckets](/influxdb/v2.2/reference/glossary/#bucket).
|
||||
In InfluxDB {{< current-version >}}, data is stored in [buckets](/influxdb/v2.2/reference/glossary/#bucket).
|
||||
Because InfluxQL uses the 1.x data model, a bucket must be mapped to a database and retention policy (DBRP) before it can be queried using InfluxQL.
|
||||
|
||||
{{% note %}}
|
||||
|
|
@ -183,10 +183,17 @@ curl --request POST http://localhost:8086/api/v2/dbrps \
|
|||
|
||||
After you've verified the bucket is mapped, query the bucket using the `query` 1.x compatibility endpoint.
|
||||
|
||||
{{% note %}}
|
||||
#### A DBRP combination can only be mapped to a single bucket
|
||||
Each unique DBRP combination can only be mapped to a single bucket.
|
||||
If you map a DBRP combination that is already mapped to another bucket,
|
||||
it will overwrite the existing DBRP mapping.
|
||||
{{% /note %}}
|
||||
|
||||
## Query a mapped bucket with InfluxQL
|
||||
|
||||
The [InfluxDB 1.x compatibility API](/influxdb/v2.2/reference/api/influxdb-1x/) supports
|
||||
all InfluxDB 1.x client libraries and integrations in InfluxDB OSS {{< current-version >}}.
|
||||
all InfluxDB 1.x client libraries and integrations in InfluxDB {{< current-version >}}.
|
||||
|
||||
To query a mapped bucket with InfluxQL, use the [`/query` 1.x compatibility endpoint](/influxdb/v2.2/reference/api/influxdb-1x/query/).
|
||||
Include the following in your request:
|
||||
|
|
@ -212,7 +219,8 @@ To return results as **CSV**, include the `Accept: application/csv` header.
|
|||
|
||||
## InfluxQL support
|
||||
|
||||
InfluxDB OSS {{< current-version >}} supports InfluxQL **read-only** queries. See supported and unsupported queries below.
|
||||
InfluxDB {{< current-version >}} supports InfluxQL queries.
|
||||
See supported and unsupported queries below.
|
||||
To learn more about InfluxQL, see [Influx Query Language (InfluxQL)](/{{< latest "influxdb" "v1" >}}/query_language/).
|
||||
|
||||
{{< flex >}}
|
||||
|
|
|
|||
|
|
@ -12,19 +12,23 @@ related:
|
|||
- /influxdb/v2.2/reference/api/influxdb-1x/query
|
||||
- /influxdb/v2.2/reference/api/influxdb-1x/write
|
||||
- /influxdb/v2.2/api/#tag/DBRPs, InfluxDB v2 API /dbrps endpoint
|
||||
- /influxdb/v2.2/query-data/influxql/
|
||||
---
|
||||
|
||||
The InfluxDB 1.x data model includes [databases](/influxdb/v1.8/concepts/glossary/#database)
|
||||
and [retention policies](/influxdb/v1.8/concepts/glossary/#retention-policy-rp).
|
||||
InfluxDB Cloud and InfluxDB OSS {{< current-version >}} replace databases and retention policies with [buckets](/influxdb/v2.2/reference/glossary/#bucket).
|
||||
To support InfluxDB 1.x query and write patterns in InfluxDB OSS {{< current-version >}} and Cloud, databases and retention
|
||||
policies are mapped to buckets using the **database and retention policy (DBRP) mapping service**.
|
||||
InfluxDB {{% cloud-only %}}Cloud{{% /cloud-only %}}{{% oss-only %}}OSS 2.x{{% /oss-only %}}
|
||||
replaces databases and retention policies with [buckets](/influxdb/v2.2/reference/glossary/#bucket).
|
||||
To support InfluxDB 1.x query and write patterns in InfluxDB
|
||||
{{% cloud-only %}}Cloud{{% /cloud-only %}}{{% oss-only %}}OSS 2.x{{% /oss-only %}},
|
||||
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
|
||||
[1.x compatibility API](/influxdb/v2.2/reference/api/influxdb-1x/) requests to route operations to a bucket.
|
||||
|
||||
{{% note %}}
|
||||
To query data in InfluxQL that was written using the 2.x `/write` API,
|
||||
To query data in InfluxQL that was written using the `api/v2/write` API,
|
||||
you must **manually create a DBRP mapping** to map a bucket to a database and retention policy.
|
||||
For more information, see [Map unmapped buckets](/influxdb/v2.2/query-data/influxql/#map-unmapped-buckets).
|
||||
{{% /note %}}
|
||||
|
|
@ -63,8 +67,8 @@ the DBRP mapping service checks for a bucket mapped to the database and retentio
|
|||
|
||||
### When querying data
|
||||
|
||||
When querying data from InfluxDB Cloud and InfluxDB OSS {{< current-version >}} using the
|
||||
[`/query` compatibility endpoint](/influxdb/v2.2/reference/api/influxdb-1x/query/),
|
||||
When querying data from InfluxDB {{< current-version >}}
|
||||
using the [`/query` compatibility endpoint](/influxdb/v2.2/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):
|
||||
|
||||
|
|
@ -72,3 +76,10 @@ the DBRP mapping service checks for the specified database and retention policy
|
|||
- If no mapped bucket exists, InfluxDB returns an error. See how to [Map unmapped buckets](/influxdb/v2.2/query-data/influxql/#map-unmapped-buckets).
|
||||
|
||||
_For more information on the DBRP mapping API, see the [`/api/v2/dbrps` endpoint documentation](/influxdb/v2.2/api/#tag/DBRPs)._
|
||||
|
||||
{{% note %}}
|
||||
#### A DBRP combination can only be mapped to a single bucket
|
||||
Each unique DBRP combination can only be mapped to a single bucket.
|
||||
If you map a DBRP combination that is already mapped to another bucket,
|
||||
it will overwrite the existing DBRP mapping.
|
||||
{{% /note %}}
|
||||
|
|
|
|||
Loading…
Reference in New Issue