diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d22beba73..ea39c5e72 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 Version bumps occur regularly in the documentation. Each minor version has its own directory with unique content. diff --git a/assets/js/influxdb-url.js b/assets/js/influxdb-url.js index 955181d59..e5726940d 100644 --- a/assets/js/influxdb-url.js +++ b/assets/js/influxdb-url.js @@ -1,4 +1,6 @@ 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)" // Retrieve the selected URL from the influxdb_url session cookie @@ -99,6 +101,16 @@ updateUrls(defaultUrl, getUrl()) // Append URL selector buttons to code blocks 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 $(window).focus(function() { updateUrls(getPrevUrl(), getUrl()) diff --git a/assets/styles/layouts/article/_code.scss b/assets/styles/layouts/article/_code.scss index 85a88cc2b..5afcf3801 100644 --- a/assets/styles/layouts/article/_code.scss +++ b/assets/styles/layouts/article/_code.scss @@ -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 //////////////////////////////// //////////////////////////////////////////////////////////////////////////////// diff --git a/content/v2.0/query-data/influxql.md b/content/v2.0/query-data/influxql.md new file mode 100644 index 000000000..cfa8069d3 --- /dev/null +++ b/content/v2.0/query-data/influxql.md @@ -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/) diff --git a/content/v2.0/reference/api/influxdb-1x/_index.md b/content/v2.0/reference/api/influxdb-1x/_index.md new file mode 100644 index 000000000..ccb42c444 --- /dev/null +++ b/content/v2.0/reference/api/influxdb-1x/_index.md @@ -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 : + +# 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 + +# Header example +Authorization: Token mYSuP3rs3cREtT0k3N +``` + +## Compatibility endpoints + +{{< children readmore=true >}} diff --git a/content/v2.0/reference/api/influxdb-1x/dbrp.md b/content/v2.0/reference/api/influxdb-1x/dbrp.md new file mode 100644 index 000000000..d5d39cf2e --- /dev/null +++ b/content/v2.0/reference/api/influxdb-1x/dbrp.md @@ -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)._ diff --git a/content/v2.0/reference/api/influxdb-1x/query.md b/content/v2.0/reference/api/influxdb-1x/query.md new file mode 100644 index 000000000..3344896d1 --- /dev/null +++ b/content/v2.0/reference/api/influxdb-1x/query.md @@ -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: | +
+  GET https://cloud2.influxdata.com/query
+  
+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. + +
+GET https://cloud2.influxdata.com/query
+
+ +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 +Required – 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 +Required – 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" +``` diff --git a/content/v2.0/reference/api/influxdb-1x/write.md b/content/v2.0/reference/api/influxdb-1x/write.md new file mode 100644 index 000000000..3f84ff2e6 --- /dev/null +++ b/content/v2.0/reference/api/influxdb-1x/write.md @@ -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: | +
+  POST https://cloud2.influxdata.com/write
+  
+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. + +
+POST https://cloud2.influxdata.com/write
+
+ +## 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 +Required – 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 +``` diff --git a/content/v2.0/reference/cli/influx/delete/_index.md b/content/v2.0/reference/cli/influx/delete/_index.md index 352f6945f..02a92c979 100644 --- a/content/v2.0/reference/cli/influx/delete/_index.md +++ b/content/v2.0/reference/cli/influx/delete/_index.md @@ -11,6 +11,7 @@ v2.0/tags: [delete] The `influx delete` command deletes [points](/v2.0/reference/glossary/#point) from an InfluxDB bucket. +Identify points to delete using [delete predicate syntax](/v2.0/reference/syntax/delete-predicate). ## Usage ```