Add admin > database docs to Core and Enterprise (#5813)

* add influxdb3 database admin docs

* Apply suggestions from code review

Co-authored-by: Jason Stirnaman <jstirnaman@influxdata.com>

---------

Co-authored-by: Jason Stirnaman <jstirnaman@influxdata.com>
pull/5815/head^2
Scott Anderson 2025-02-03 09:25:41 -07:00 committed by GitHub
parent d73e99dd41
commit ebf9b1bfd3
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
19 changed files with 571 additions and 3 deletions

View File

@ -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
---
<!--
The content of this file is located at content/shared/influxdb3-admin/_index.md
-->

View File

@ -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
---
<!--
The content of this file is located at content/shared/influxdb3-admin/databases/_index.md
-->

View File

@ -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: |
<!--pytest.mark.skip-->
{{% 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
---
<!--
The content of this file is located at content/shared/influxdb3-admin/databases/create.md
-->

View File

@ -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
---
<!--
The content of this file is located at content/shared/influxdb3-admin/databases/delete.md
-->

View File

@ -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
---
<!--
The content of this file is located at content/shared/influxdb3-admin/databases/list.md
-->

View File

@ -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/
---

View File

@ -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
---
<!--
The content of this file is located at content/shared/influxdb3-admin/_index.md
-->

View File

@ -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
---
<!--
The content of this file is located at content/shared/influxdb3-admin/databases/_index.md
-->

View File

@ -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: |
<!--pytest.mark.skip-->
{{% 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
---
<!--
The content of this file is located at content/shared/influxdb3-admin/databases/create.md
-->

View File

@ -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
---
<!--
The content of this file is located at content/shared/influxdb3-admin/databases/delete.md
-->

View File

@ -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
---
<!--
The content of this file is located at content/shared/influxdb3-admin/databases/list.md
-->

View File

@ -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/
---

View File

@ -0,0 +1,5 @@
The following articles provide information about managing your
{{< product-name >}} resources:
{{< children >}}

View File

@ -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.
<!--
## Retention periods
A database **retention period** is the maximum age of data stored in the database.
The age of data is determined by the timestamp associated with each point.
When a point's timestamp is beyond the retention period (relative to now), the
point is marked for deletion and is removed from the database the next time the
retention enforcement service runs.
The _minimum_ retention period for an InfluxDB database is 1 hour.
The _maximum_ retention period is infinite meaning data does not expire and will
never be removed by the retention enforcement service.
-->
## 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** <em style='opacity:.5;font-weight:normal;'>View more info</em>" %}}
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** <em style='opacity:.5;font-weight:normal;'>View more info</em>" %}}
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)_ <em style='opacity:.5;font-weight:normal;'>View more info</em>" %}}
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 >}}

View File

@ -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.
<!--Allow fail for database create and delete: namespaces aren't reusable-->
<!--pytest.mark.skip-->
{{% 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)
<!--
## Retention period syntax
Use the `--retention-period` flag to define a specific
[retention period](/influxdb3/version/admin/databases/#retention-periods)
for the database.
The retention period value is a time duration value made up of a numeric value
plus a duration unit.
For example, `30d` means 30 days.
A zero duration (`0d`) retention period is infinite and data won't expire.
The retention period value cannot be negative or contain whitespace.
{{< flex >}}
{{% flex-content "half" %}}
##### Valid durations units include
- **m**: minute
- **h**: hour
- **d**: day
- **w**: week
- **mo**: month
- **y**: year
{{% /flex-content %}}
{{% flex-content "half" %}}
##### Example retention period values
- `0d`: infinite/none
- `3d`: 3 days
- `6w`: 6 weeks
- `1mo`: 1 month (30 days)
- `1y`: 1 year
- `30d30d`: 60 days
- `2.5d`: 60 hours
{{% /flex-content %}}
{{< /flex >}}
-->
## 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)._

View File

@ -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.

View File

@ -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`
<!-- - `parquet` _(must [output to a file](#output-to-a-parquet-file))_ -->
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
```
<!-- ### Output to a Parquet file
To output your list of databases to a Parquet file, provide the following
options with the `influxdb3 show databases` command:
- `--format`: `parquet`
- `-o`, `--output`: the filepath to the Parquet file to output to
```sh
influxdb3 query \
--format parquet \
--output path/to/databases.parquet
``` -->

View File

@ -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 }}

View File

@ -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 }}