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

feat(influxdb3): create table guides for core and ent 

Part of #6215
pull/6216/head
Jason Stirnaman 2025-07-10 17:07:48 -05:00
parent d88438723d
commit 1c8a7b8606
6 changed files with 266 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
content/influxdb3/core/admin/tables/_index.md Normal file
View File

@ -0,0 +1,21 @@
---
title: Manage tables
seotitle: Manage tables in {{< product-name >}}
description: >
Tables in {{< product-name >}} are synonymous with measurements and contain
time series data. Each table has a defined schema with tag and field columns.
menu:
influxdb3_core:
parent: Administer InfluxDB
weight: 102
influxdb3/core/tags: [tables]
related:
- /influxdb3/core/write-data/best-practices/schema-design/
- /influxdb3/core/reference/cli/influxdb3/
- /influxdb3/core/reference/naming-restrictions/
source: /shared/influxdb3-admin/tables/_index.md
---
<!--
//SOURCE content/shared/influxdb3-admin/tables/_index.md
-->

27
content/influxdb3/core/admin/tables/create.md Normal file
View File

@ -0,0 +1,27 @@
---
title: Create a table
description: >
Use the [`influxdb3 create table` command](/influxdb3/core/reference/cli/influxdb3/create/table/)
to create a new table in a specified database in InfluxDB 3 Core.
Provide the database name, table name, and tag columns.
menu:
influxdb3_core:
parent: Manage tables
weight: 201
list_code_example: |
```sh
influxdb3 create table \
--tags tag1,tag2,tag3 \
--database <DATABASE_NAME> \
--token <AUTH_TOKEN> \
<TABLE_NAME>
```
related:
- /influxdb3/core/reference/cli/influxdb3/create/table/
- /influxdb3/core/reference/naming-restrictions/
source: /shared/influxdb3-admin/tables/create.md
---
<!--
//SOURCE content/shared/influxdb3-admin/tables/create.md
-->

21
content/influxdb3/enterprise/admin/tables/_index.md Normal file
View File

@ -0,0 +1,21 @@
---
title: Manage tables
seotitle: Manage tables in {{< product-name >}}
description: >
Tables in {{< product-name >}} are synonymous with measurements and contain
time series data. Each table has a defined schema with tag and field columns.
menu:
influxdb3_enterprise:
parent: Administer InfluxDB
weight: 102
influxdb3/enterprise/tags: [tables]
related:
- /influxdb3/enterprise/write-data/best-practices/schema-design/
- /influxdb3/enterprise/reference/cli/influxdb3/
- /influxdb3/enterprise/reference/naming-restrictions/
source: /shared/influxdb3-admin/tables/_index.md
---
<!--
//SOURCE content/shared/influxdb3-admin/tables/_index.md
-->

28
content/influxdb3/enterprise/admin/tables/create.md Normal file
View File

@ -0,0 +1,28 @@
---
title: Create a table
description: >
Use the [`influxdb3 create table` command](/influxdb3/enterprise/reference/cli/influxdb3/create/table/)
or the [HTTP API](/influxdb3/enterprise/api/v3/) to create a new table in a specified database
in InfluxDB 3 Enterprise. Provide the database name, table name, and tag columns.
menu:
influxdb3_enterprise:
parent: Manage tables
weight: 201
list_code_example: |
```sh
influxdb3 create table \
--tags tag1,tag2,tag3 \
--database <DATABASE_NAME> \
--token <AUTH_TOKEN> \
<TABLE_NAME>
```
related:
- /influxdb3/enterprise/reference/cli/influxdb3/create/table/
- /influxdb3/enterprise/reference/naming-restrictions/
- /influxdb3/enterprise/api/v3/
source: /shared/influxdb3-admin/tables/create.md
---
<!--
//SOURCE content/shared/influxdb3-admin/tables/create.md
-->

6
content/shared/influxdb3-admin/tables/_index.md Normal file
View File

@ -0,0 +1,6 @@
Tables are synonymous with measurements in {{< product-name >}}.
They are typically created automatically when you write line protocol data,
but you can also manually create them to define custom schemas or apply settings
before writing data.
{{< children >}}

163
content/shared/influxdb3-admin/tables/create.md Normal file
View File

@ -0,0 +1,163 @@
Use the [`influxdb3 create table` command](/influxdb3/version/reference/cli/influxdb3/create/table/)
or the [HTTP API](/influxdb3/version/api/v3/) to create a table in a specified database in {{< product-name >}}.
With {{< product-name >}}, tables and measurements are synonymous.
Typically, tables are created automatically on write using the measurement name
specified in line protocol written to InfluxDB.
However, you can manually create tables to define a custom schema or apply custom settings before writing data.
- [Create a table using the influxdb3 CLI](#create-a-table-using-the-influxdb3-cli)
- [Create a table using the HTTP API](#create-a-table-using-the-http-api)
- [Table naming restrictions](#table-naming-restrictions)
## Create a table using the influxdb3 CLI
1. If you haven't already, [download and install the `influxdb3` CLI](/influxdb3/version/reference/cli/influxdb3/#download-and-install-the-influxdb3-cli).
2. Run the `influxdb3 create table` command and provide the following:
- _Required_: The name of the database to create the table in
- _Required_: The name of the table to create (see [Table naming restrictions](#table-naming-restrictions))
- _Required_: Tag columns to include in the table
- _Optional_: Field columns and their data types to include in the table
{{% show-in "enterprise" %}}
- _Optional_: A retention period for the table
{{% /show-in %}}
> [!Note]
> Tables must include at least one tag column.
> Field columns are optional and can be added later when you write data.
{{% code-placeholders "DATABASE_NAME|TABLE_NAME|AUTH_TOKEN" %}}
```bash
influxdb3 create table \
--tags tag1,tag2,tag3 \
--database DATABASE_NAME \
--token AUTH_TOKEN \
TABLE_NAME
```
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to create the table in
- {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}}: the name of the table to create
- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "admin" %}}
### Create a table with field columns
To define specific field columns and their data types when creating the table, use the `--fields` flag:
{{% code-placeholders "DATABASE_NAME|TABLE_NAME|AUTH_TOKEN" %}}
```sh
influxdb3 create table \
--tags room,sensor_id \
--fields temp:float64,hum:float64,co:int64 \
--database DATABASE_NAME \
--token AUTH_TOKEN \
TABLE_NAME
```
{{% /code-placeholders %}}
{{% show-in "enterprise" %}}
### Create a table with a retention period
To set a specific retention period for the table, use the `--retention-period` flag:
{{% code-placeholders "DATABASE_NAME|TABLE_NAME|AUTH_TOKEN" %}}
```sh
influxdb3 create table \
--tags room,sensor_id \
--fields temp:float64,hum:float64 \
--retention-period 7d \
--database DATABASE_NAME \
--token AUTH_TOKEN \
TABLE_NAME
```
{{% /code-placeholders %}}
{{% /show-in %}}
## Create a table using the HTTP API
To create a table using the HTTP API, send a `POST` request to the `/api/v3/configure/table` endpoint:
{{% api-endpoint method="POST" endpoint="{{< influxdb/host >}}/api/v3/configure/table" %}}
Include the following in your request:
- **Headers**:
- `Authorization: Bearer` with your authentication token
- `Content-Type: application/json`
- **Request body**: JSON object with table configuration
{{% code-placeholders "DATABASE_NAME|TABLE_NAME|AUTH_TOKEN" %}}
```bash
curl -X POST "http://{{< influxdb/host >}}/api/v3/configure/table" \
--header "Authorization: Bearer AUTH_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"db": "DATABASE_NAME",
"table": "TABLE_NAME",
"tags": ["tag1", "tag2", "tag3"]
}'
```
{{% /code-placeholders %}}
### Create a table with field columns using the API
{{% code-placeholders "DATABASE_NAME|TABLE_NAME|AUTH_TOKEN" %}}
```bash
curl -X POST "{{< influxdb/host >}}/api/v3/configure/table" \
--header "Authorization: Bearer AUTH_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"db": "DATABASE_NAME",
"table": "TABLE_NAME",
"tags": ["room", "sensor_id"],
"fields": [
{"name": "temp", "type": "float64"},
{"name": "hum", "type": "float64"},
{"name": "co", "type": "int64"}
]
}'
```
{{% /code-placeholders %}}
{{% show-in "enterprise" %}}
### Create a table with a retention period using the API
{{% code-placeholders "DATABASE_NAME|TABLE_NAME|AUTH_TOKEN" %}}
```bash
curl -X POST "{{< influxdb/host >}}/api/v3/configure/table" \
--header "Authorization: Bearer AUTH_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"db": "DATABASE_NAME",
"table": "TABLE_NAME",
"tags": ["room", "sensor_id"],
"fields": [
{"name": "temp", "type": "float64"},
{"name": "hum", "type": "float64"}
],
"retention_period": "7d"
}'
```
{{% /code-placeholders %}}
{{% /show-in %}}
## Table naming restrictions
Table names in {{< product-name >}} must adhere to the following naming restrictions:
- **Allowed characters**: Alphanumeric characters (a-z, A-Z, 0-9), underscore (`_`), dash (`-`)
- **Starting character**: Should start with a letter or number and should not start with underscore (`_`)
- **Case sensitivity**: Table names are case-sensitive
- **Quoting**: Use double quotes when names contain special characters or whitespace
> [!Caution]
> #### Underscore prefix reserved for system use
>
> Names starting with an underscore (`_`) may be reserved for InfluxDB system use.
> While {{< product-name >}} might not explicitly reject these names, using them risks
> conflicts with current or future system features and may result in
> unexpected behavior or data loss.