From ebf9b1bfd3c5d65b01174bb40a6a8b3ff9e30208 Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Mon, 3 Feb 2025 09:25:41 -0700 Subject: [PATCH] Add admin > database docs to Core and Enterprise (#5813) * add influxdb3 database admin docs * Apply suggestions from code review Co-authored-by: Jason Stirnaman --------- Co-authored-by: Jason Stirnaman --- content/influxdb3/core/admin/_index.md | 15 +++ .../influxdb3/core/admin/databases/_index.md | 25 ++++ .../influxdb3/core/admin/databases/create.md | 25 ++++ .../influxdb3/core/admin/databases/delete.md | 24 ++++ .../influxdb3/core/admin/databases/list.md | 21 ++++ .../influxdb3/core/visualize-data/_index.md | 2 +- content/influxdb3/enterprise/admin/_index.md | 15 +++ .../enterprise/admin/databases/_index.md | 25 ++++ .../enterprise/admin/databases/create.md | 25 ++++ .../enterprise/admin/databases/delete.md | 24 ++++ .../enterprise/admin/databases/list.md | 21 ++++ .../enterprise/visualize-data/_index.md | 2 +- content/shared/influxdb3-admin/_index.md | 5 + .../influxdb3-admin/databases/_index.md | 103 +++++++++++++++++ .../influxdb3-admin/databases/create.md | 108 ++++++++++++++++++ .../influxdb3-admin/databases/delete.md | 25 ++++ .../shared/influxdb3-admin/databases/list.md | 99 ++++++++++++++++ layouts/shortcodes/children.html | 2 +- layouts/shortcodes/influxdb3/limit.html | 8 ++ 19 files changed, 571 insertions(+), 3 deletions(-) create mode 100644 content/influxdb3/core/admin/_index.md create mode 100644 content/influxdb3/core/admin/databases/_index.md create mode 100644 content/influxdb3/core/admin/databases/create.md create mode 100644 content/influxdb3/core/admin/databases/delete.md create mode 100644 content/influxdb3/core/admin/databases/list.md create mode 100644 content/influxdb3/enterprise/admin/_index.md create mode 100644 content/influxdb3/enterprise/admin/databases/_index.md create mode 100644 content/influxdb3/enterprise/admin/databases/create.md create mode 100644 content/influxdb3/enterprise/admin/databases/delete.md create mode 100644 content/influxdb3/enterprise/admin/databases/list.md create mode 100644 content/shared/influxdb3-admin/_index.md create mode 100644 content/shared/influxdb3-admin/databases/_index.md create mode 100644 content/shared/influxdb3-admin/databases/create.md create mode 100644 content/shared/influxdb3-admin/databases/delete.md create mode 100644 content/shared/influxdb3-admin/databases/list.md create mode 100644 layouts/shortcodes/influxdb3/limit.html diff --git a/content/influxdb3/core/admin/_index.md b/content/influxdb3/core/admin/_index.md new file mode 100644 index 000000000..b0bda9eb6 --- /dev/null +++ b/content/influxdb3/core/admin/_index.md @@ -0,0 +1,15 @@ +--- +title: Administer {{< product-name >}} +description: > + Perform administrative tasks in {{< product-name >}} such as creating and + managing databases and tokens. +menu: + influxdb3_core: + name: Administer InfluxDB +weight: 11 +source: /shared/influxdb3-admin/_index.md +--- + + diff --git a/content/influxdb3/core/admin/databases/_index.md b/content/influxdb3/core/admin/databases/_index.md new file mode 100644 index 000000000..ddbfb0a16 --- /dev/null +++ b/content/influxdb3/core/admin/databases/_index.md @@ -0,0 +1,25 @@ +--- +title: Manage databases +seotitle: Manage databases in {{< product-name >}} +description: > + An {{< product-name >}} database is a named location where time series data is + stored. Each database can contain multiple tables. +menu: + influxdb3_core: + parent: Administer InfluxDB +weight: 103 +influxdb3/core/tags: [databases] +related: + - /influxdb3/core/write-data/best-practices/schema-design/ + - /influxdb3/core/reference/cli/influxdb3/ +alt_links: + cloud: /influxdb/cloud/admin/buckets/ + cloud_dedicated: /influxdb3/cloud-dedicated/admin/databases/ + cloud_serverless: /influxdb3/cloud-serverless/admin/buckets/ + v2: /influxdb/v2/admin/buckets/ +source: /shared/influxdb3-admin/databases/_index.md +--- + + diff --git a/content/influxdb3/core/admin/databases/create.md b/content/influxdb3/core/admin/databases/create.md new file mode 100644 index 000000000..a05fe548f --- /dev/null +++ b/content/influxdb3/core/admin/databases/create.md @@ -0,0 +1,25 @@ +--- +title: Create a database +description: > + Use the [`influxdb3 create database` command](/influxdb3/core/reference/cli/influxdb3/create/database/) + to create a new database in {{< product-name >}}. +menu: + influxdb3_core: + parent: Manage databases +weight: 201 +list_code_example: | + + + {{% code-placeholders "DATABASE_NAME" %}} + ```sh + influxdb3 create database DATABASE_NAME + ``` + {{% /code-placeholders %}} +related: + - /influxdb3/core/reference/cli/influxdb3/create/database/ +source: /shared/influxdb3-admin/databases/create.md +--- + + diff --git a/content/influxdb3/core/admin/databases/delete.md b/content/influxdb3/core/admin/databases/delete.md new file mode 100644 index 000000000..96750c65e --- /dev/null +++ b/content/influxdb3/core/admin/databases/delete.md @@ -0,0 +1,24 @@ +--- +title: Delete a database +description: > + Use the [`influxdb3 delete database` command](/influxdb3/core/reference/cli/influxdb3/delete/database/) + to delete a database from {{< product-name >}}. + Provide the name of the database you want to delete. +menu: + influxdb3_core: + parent: Manage databases +weight: 203 +list_code_example: | + {{% code-placeholders "DATABASE_NAME" %}} + ```sh + influxdb3 delete database DATABASE_NAME + ``` + {{% /code-placeholders %}} +related: + - /influxdb3/core/reference/cli/influxdb3/delete/database/ +source: /shared/influxdb3-admin/databases/delete.md +--- + + diff --git a/content/influxdb3/core/admin/databases/list.md b/content/influxdb3/core/admin/databases/list.md new file mode 100644 index 000000000..e416c267b --- /dev/null +++ b/content/influxdb3/core/admin/databases/list.md @@ -0,0 +1,21 @@ +--- +title: List databases +description: > + Use the [`influxdb3 show databases` command](/influxdb3/core/reference/cli/influxdb3/show/databases/) + to list databases in {{< product-name >}}. +menu: + influxdb3_core: + parent: Manage databases +weight: 202 +list_code_example: | + ```sh + influxdb3 show databases + ``` +related: + - /influxdb3/core/reference/cli/influxdb3/show/databases/ +source: /shared/influxdb3-admin/databases/list.md +--- + + diff --git a/content/influxdb3/core/visualize-data/_index.md b/content/influxdb3/core/visualize-data/_index.md index 0e2f294c3..f4a36b023 100644 --- a/content/influxdb3/core/visualize-data/_index.md +++ b/content/influxdb3/core/visualize-data/_index.md @@ -4,7 +4,7 @@ description: > Use visualization tools like Grafana, Superset, and others to visualize time series data stored in InfluxDB 3 Core. menu: influxdb3_core -weight: 19 +weight: 10 related: - /influxdb3/clustered/query-data/ --- diff --git a/content/influxdb3/enterprise/admin/_index.md b/content/influxdb3/enterprise/admin/_index.md new file mode 100644 index 000000000..f546ae387 --- /dev/null +++ b/content/influxdb3/enterprise/admin/_index.md @@ -0,0 +1,15 @@ +--- +title: Administer {{< product-name >}} +description: > + Perform administrative tasks in {{< product-name >}} such as creating and + managing databases and tokens. +menu: + influxdb3_enterprise: + name: Administer InfluxDB +weight: 11 +source: /shared/influxdb3-admin/_index.md +--- + + diff --git a/content/influxdb3/enterprise/admin/databases/_index.md b/content/influxdb3/enterprise/admin/databases/_index.md new file mode 100644 index 000000000..d5ede41b1 --- /dev/null +++ b/content/influxdb3/enterprise/admin/databases/_index.md @@ -0,0 +1,25 @@ +--- +title: Manage databases +seotitle: Manage databases in {{< product-name >}} +description: > + An {{< product-name >}} database is a named location where time series data is + stored. Each database can contain multiple tables. +menu: + influxdb3_enterprise: + parent: Administer InfluxDB +weight: 103 +influxdb3/enterprise/tags: [databases] +related: + - /influxdb3/enterprise/write-data/best-practices/schema-design/ + - /influxdb3/enterprise/reference/cli/influxdb3/ +alt_links: + cloud: /influxdb/cloud/admin/buckets/ + cloud_dedicated: /influxdb3/cloud-dedicated/admin/databases/ + cloud_serverless: /influxdb3/cloud-serverless/admin/buckets/ + v2: /influxdb/v2/admin/buckets/ +source: /shared/influxdb3-admin/databases/_index.md +--- + + diff --git a/content/influxdb3/enterprise/admin/databases/create.md b/content/influxdb3/enterprise/admin/databases/create.md new file mode 100644 index 000000000..bccfacff2 --- /dev/null +++ b/content/influxdb3/enterprise/admin/databases/create.md @@ -0,0 +1,25 @@ +--- +title: Create a database +description: > + Use the [`influxdb3 create database` command](/influxdb3/enterprise/reference/cli/influxdb3/create/database/) + to create a new database in {{< product-name >}}. +menu: + influxdb3_enterprise: + parent: Manage databases +weight: 201 +list_code_example: | + + + {{% code-placeholders "DATABASE_NAME" %}} + ```sh + influxdb3 create database DATABASE_NAME + ``` + {{% /code-placeholders %}} +related: + - /influxdb3/enterprise/reference/cli/influxdb3/create/database/ +source: /shared/influxdb3-admin/databases/create.md +--- + + diff --git a/content/influxdb3/enterprise/admin/databases/delete.md b/content/influxdb3/enterprise/admin/databases/delete.md new file mode 100644 index 000000000..395ab611a --- /dev/null +++ b/content/influxdb3/enterprise/admin/databases/delete.md @@ -0,0 +1,24 @@ +--- +title: Delete a database +description: > + Use the [`influxdb3 delete database` command](/influxdb3/enterprise/reference/cli/influxdb3/delete/database/) + to delete a database from {{< product-name >}}. + Provide the name of the database you want to delete. +menu: + influxdb3_enterprise: + parent: Manage databases +weight: 203 +list_code_example: | + {{% code-placeholders "DATABASE_NAME" %}} + ```sh + influxdb3 delete database DATABASE_NAME + ``` + {{% /code-placeholders %}} +related: + - /influxdb3/enterprise/reference/cli/influxdb3/delete/database/ +source: /shared/influxdb3-admin/databases/delete.md +--- + + diff --git a/content/influxdb3/enterprise/admin/databases/list.md b/content/influxdb3/enterprise/admin/databases/list.md new file mode 100644 index 000000000..c579a9816 --- /dev/null +++ b/content/influxdb3/enterprise/admin/databases/list.md @@ -0,0 +1,21 @@ +--- +title: List databases +description: > + Use the [`influxdb3 show databases` command](/influxdb3/enterprise/reference/cli/influxdb3/show/databases/) + to list databases in {{< product-name >}}. +menu: + influxdb3_enterprise: + parent: Manage databases +weight: 202 +list_code_example: | + ```sh + influxdb3 show databases + ``` +related: + - /influxdb3/enterprise/reference/cli/influxdb3/show/databases/ +source: /shared/influxdb3-admin/databases/list.md +--- + + diff --git a/content/influxdb3/enterprise/visualize-data/_index.md b/content/influxdb3/enterprise/visualize-data/_index.md index 051ca248a..a5200cf7b 100644 --- a/content/influxdb3/enterprise/visualize-data/_index.md +++ b/content/influxdb3/enterprise/visualize-data/_index.md @@ -4,7 +4,7 @@ description: > Use visualization tools like Grafana, Superset, and others to visualize time series data stored in InfluxDB 3 Core. menu: influxdb3_enterprise -weight: 19 +weight: 10 related: - /influxdb3/enterprise/query-data/ --- diff --git a/content/shared/influxdb3-admin/_index.md b/content/shared/influxdb3-admin/_index.md new file mode 100644 index 000000000..1d9916f37 --- /dev/null +++ b/content/shared/influxdb3-admin/_index.md @@ -0,0 +1,5 @@ + +The following articles provide information about managing your +{{< product-name >}} resources: + +{{< children >}} diff --git a/content/shared/influxdb3-admin/databases/_index.md b/content/shared/influxdb3-admin/databases/_index.md new file mode 100644 index 000000000..73d148aae --- /dev/null +++ b/content/shared/influxdb3-admin/databases/_index.md @@ -0,0 +1,103 @@ + +An {{< product-name >}} database is a named location where time series data is +stored. Each database can contain multiple tables. + +> [!Note] +> **If coming from InfluxDB v1**, the concepts of databases and retention policies +> have been combined into a single concept--database. Retention policies are no +> longer part of the InfluxDB data model. +> However, {{% product-name %}} does +> support InfluxQL, which requires databases and retention policies. +> See [InfluxQL DBRP naming convention](/influxdb3/version/admin/databases/create/#influxql-dbrp-naming-convention). +> +> **If coming from InfluxDB v2, InfluxDB Cloud (TSM), or InfluxDB Cloud Serverless**, +> _database_ and _bucket_ are synonymous. + + + +## Database, table, and column limits + +{{< product-name >}} places the following limits on databases, tables, and columns: + +### Database limit + +**Maximum number of databases**: {{% influxdb3/limit "database" %}} + +### Table limit + +**Maximum number of tables across all databases**: {{% influxdb3/limit "table" %}} + +{{< product-name >}} limits the number of tables you can have across _all_ +databases to {{% influxdb3/limit "table" %}}. There is no specific limit on how +many tables you can have in an individual database, as long as the total across +all databases is below the limit. + +Having more tables affects your {{% product-name %}} installation in the +following ways: + +{{< expand-wrapper >}} +{{% expand "**May improve query performance** View more info" %}} + +Schemas with many tables that contain +[focused sets of tags and fields](/influxdb3/version/write-data/best-practices/schema-design/#design-for-performance) +can make it easier for the query engine to identify what Parquet files contain +the queried data, resulting in better query performance. + +{{% /expand %}} +{{% expand "**More PUTs into object storage** View more info" %}} + +When using cloud-based object storage as your data backend, the more tables you +have, the more `PUT` requests there are into your object store as InfluxDB +persists data to Parquet files. Each `PUT` request incurs a monetary cost and +increases the operating cost of {{< product-name >}}. + +{{% /expand %}} +{{% expand "**More work for the compactor** _(Enterprise only)_ View more info" %}} + +To optimize storage over time, InfluxDB 3 Enterprise has a compactor that +routinely compacts Parquet files. +With more tables and Parquet files to compact, the compactor may need to be scaled +to keep up with demand, adding to the operating cost of InfluxDB 3 Enterprise. + +{{% /expand %}} +{{< /expand-wrapper >}} + +### Column limit + +**Maximum number of columns per table**: {{% influxdb3/limit "column" %}} + +Each row must include a time column, with the remaining columns representing +tags and fields. +As a result, a table can have one time column and up to {{% influxdb3/limit "column" -1 %}} +_combined_ field and tag columns. +If you attempt to write to a table and exceed the column limit, the write +request fails and InfluxDB returns an error. + +Higher numbers of columns has the following side-effects: + +{{< expand-wrapper >}} +{{% expand "May adversely affect system performance" %}} + +InfluxData identified {{% influxdb3/limit "column" %}} columns as the safe limit +for maintaining system performance and stability. +Exceeding this threshold can result in +[wide schemas](/influxdb3/version/write-data/best-practices/schema-design/#avoid-wide-schemas), +which can negatively impact performance and resource use, +depending on your queries, the shape of your schema, and data types in the schema. + +{{% /expand %}} +{{< /expand-wrapper >}} + +{{< children hlevel="h2" readmore=true hr=true >}} diff --git a/content/shared/influxdb3-admin/databases/create.md b/content/shared/influxdb3-admin/databases/create.md new file mode 100644 index 000000000..11eb4e368 --- /dev/null +++ b/content/shared/influxdb3-admin/databases/create.md @@ -0,0 +1,108 @@ + +Use the [`influxdb3 create database` command](/influxdb3/version/reference/cli/influxdb3/create/database/) +to create a database in {{< product-name >}}. +Provide the following: + +- Database name _(see [Database naming restrictions](#database-naming-restrictions))_ +- {{< product-name >}} authorization token + + > [!Note] + > While in alpha, {{< product-name >}} does not require an authorization token. + + + + +{{% code-placeholders "DATABASE_NAME" %}} + +```sh +influxdb3 create database DATABASE_NAME +``` + +{{% /code-placeholders %}} + +- [Database naming restrictions](#database-naming-restrictions) +- [InfluxQL DBRP naming convention](#influxql-dbrp-naming-convention) +- [Database limit](#database-limit) + + + +## Database naming restrictions + +Database names must adhere to the following naming restrictions: + +- Alphanumeric characters +- Dashes (`-`), underscores (`_`), and forward slashes (`/`) are allowed +- Must start with a letter or number +- Maximum length of 64 characters + +## InfluxQL DBRP naming convention + +In InfluxDB 1.x, data is stored in [databases](/influxdb/v1/concepts/glossary/#database) +and [retention policies](/influxdb/v1/concepts/glossary/#retention-policy-rp). +In {{% product-name %}}, databases and retention policies have been merged into +_databases_; retention policies are no longer part of the data model. +Because InfluxQL uses the 1.x data model, to support InfluxQL queries the use +databases and retention policies, an {{< product-name >}} database must +be mapped to a v1 database and retention policy (DBRP) to be queryable with InfluxQL. + +**When naming a database that you want to query with InfluxQL**, use the +following naming convention to automatically map v1 DBRP combinations to an +{{% product-name %}} database: + +```text +database_name/retention_policy_name +``` + +##### Database naming examples + +| v1 Database name | v1 Retention Policy name | New database name | +| :--------------- | :----------------------- | :------------------------ | +| db | rp | db/rp | +| telegraf | autogen | telegraf/autogen | +| webmetrics | 1w-downsampled | webmetrics/1w-downsampled | + +## Database limit + +**Maximum number of databases**: {{% influxdb3/limit "database" %}} + +_For more information about {{< product-name >}} database, table, and column limits, +see [Database, table, and column limits](/influxdb3/version/admin/databases/#database-table-and-column-limits)._ diff --git a/content/shared/influxdb3-admin/databases/delete.md b/content/shared/influxdb3-admin/databases/delete.md new file mode 100644 index 000000000..773d82884 --- /dev/null +++ b/content/shared/influxdb3-admin/databases/delete.md @@ -0,0 +1,25 @@ + +Use the [`influxdb3 delete database` command](/influxdb3/version/reference/cli/influxdb3/delete/database/) +to delete a database from {{< product-name >}}. + +> [!Caution] +> #### Deleting a database cannot be undone +> +> Deleting a database is a destructive action. +> Once a database is deleted, data stored in that database cannot be recovered. + +Provide the following: + +- Name of the database to delete +- {{< product-name >}} authorization token + + > [!Note] + > While in alpha, {{< product-name >}} does not require an authorization token. + +{{% code-placeholders "DATABASE_NAME" %}} +```sh +influxdb3 delete database DATABASE_NAME +``` +{{% /code-placeholders %}} + +Enter `yes` to confirm that you want to delete the database. diff --git a/content/shared/influxdb3-admin/databases/list.md b/content/shared/influxdb3-admin/databases/list.md new file mode 100644 index 000000000..905e7e102 --- /dev/null +++ b/content/shared/influxdb3-admin/databases/list.md @@ -0,0 +1,99 @@ + +Use the [`influxdb3 show databases` command](/influxdb3/version/reference/cli/influxdb3/show/databases/) +to list databases in {{< product-name >}}. +Provide the following: + + - _(Optional)_ [Output format](#output-formats) with the `--format` option + - _(Optional)_ [Show deleted databases](list-deleted-databasese) with the + `--show-deleted` option + - {{< product-name >}} authorization token with the `-t`, `--token` option + + > [!Note] + > While in alpha, {{< product-name >}} does not require an authorization token. + +```sh +influxdb3 show databases +``` + +### Output formats + +The `influxdb3 show databases` command supports output formats: + +- `pretty` _(default)_ +- `json` +- `jsonl` +- `csv` + + +Use the `--format` flag to specify the output format: + +```sh +influxdb3 show databases --format json +``` + +#### Example output + +{{< expand-wrapper >}} +{{% expand "View example pretty-formatted output" %}} +{{% influxdb/custom-timestamps %}} +``` ++---------------+ +| iox::database | ++---------------+ +| home | +| home_actions | +| noaa | ++---------------+ +``` +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} +{{% expand "View example JSON-formatted output" %}} +{{% influxdb/custom-timestamps %}} +```json +[{"iox::database":"home"},{"iox::database":"home_actions"},{"iox::database":"noaa"}] +``` +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} +{{% expand "View example JSON-line-formatted output" %}} +{{% influxdb/custom-timestamps %}} +```json +{"iox::database":"home"} +{"iox::database":"home_actions"} +{"iox::database":"noaa"} +``` +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} +{{% expand "View example CSV-formatted output" %}} +{{% influxdb/custom-timestamps %}} +```csv +iox::database +home +home_actions +noaa +``` +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} +{{< /expand-wrapper >}} + +## List deleted databases + +To list deleted databases, include the `--show-deleted` option with your +`influxdb3 show databases` command: + +```sh +influxdb3 show databases --show-deleted +``` + + diff --git a/layouts/shortcodes/children.html b/layouts/shortcodes/children.html index a4520df88..58a57fd1f 100644 --- a/layouts/shortcodes/children.html +++ b/layouts/shortcodes/children.html @@ -50,7 +50,7 @@ {{- $productRef := index $productAliases $productKey -}} {{- $productData := index .Site.Data.products $productRef -}} {{- $placeholderHost := $productData.placeholder_host }} - {{ .Params.list_code_example | replaceRE `\{\{[<\%] influxdb/host [>%]\}\}` $placeholderHost | markdownify }} + {{ .Params.list_code_example | replaceRE `\{\{[<\%] influxdb/host [>%]\}\}` $placeholderHost | .RenderString }} {{ end }} {{ if .Params.list_query_example }} diff --git a/layouts/shortcodes/influxdb3/limit.html b/layouts/shortcodes/influxdb3/limit.html new file mode 100644 index 000000000..ecbcd35c2 --- /dev/null +++ b/layouts/shortcodes/influxdb3/limit.html @@ -0,0 +1,8 @@ +{{- $productPathData := split .Page.RelPermalink "/" -}} +{{- $product := index $productPathData 2 -}} +{{- $limit := .Get 0 | default "database" -}} +{{- $modifier := .Get 1 | default 0 -}} +{{- $coreLimits := dict "database" 5 "table" 2000 "column" 500 -}} +{{- $enterpriseLimits := dict "database" 100 "table" 4000 "column" 500 -}} +{{- $productLimits := cond (eq $product "core") $coreLimits $enterpriseLimits -}} +{{ add (index $productLimits $limit) $modifier }} \ No newline at end of file