From 1c8a7b8606685a72ed35ebab4f450d03c0a34236 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Thu, 10 Jul 2025 17:07:48 -0500 Subject: [PATCH 1/5] feat(influxdb3): create table guides for core and ent Part of #6215 --- content/influxdb3/core/admin/tables/_index.md | 21 +++ content/influxdb3/core/admin/tables/create.md | 27 +++ .../enterprise/admin/tables/_index.md | 21 +++ .../enterprise/admin/tables/create.md | 28 +++ .../shared/influxdb3-admin/tables/_index.md | 6 + .../shared/influxdb3-admin/tables/create.md | 163 ++++++++++++++++++ 6 files changed, 266 insertions(+) create mode 100644 content/influxdb3/core/admin/tables/_index.md create mode 100644 content/influxdb3/core/admin/tables/create.md create mode 100644 content/influxdb3/enterprise/admin/tables/_index.md create mode 100644 content/influxdb3/enterprise/admin/tables/create.md create mode 100644 content/shared/influxdb3-admin/tables/_index.md create mode 100644 content/shared/influxdb3-admin/tables/create.md diff --git a/content/influxdb3/core/admin/tables/_index.md b/content/influxdb3/core/admin/tables/_index.md new file mode 100644 index 000000000..d9fed7d3e --- /dev/null +++ b/content/influxdb3/core/admin/tables/_index.md @@ -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 +--- + + \ No newline at end of file diff --git a/content/influxdb3/core/admin/tables/create.md b/content/influxdb3/core/admin/tables/create.md new file mode 100644 index 000000000..47d3a7f51 --- /dev/null +++ b/content/influxdb3/core/admin/tables/create.md @@ -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 \ + --token \ + + ``` +related: + - /influxdb3/core/reference/cli/influxdb3/create/table/ + - /influxdb3/core/reference/naming-restrictions/ +source: /shared/influxdb3-admin/tables/create.md +--- + + \ No newline at end of file diff --git a/content/influxdb3/enterprise/admin/tables/_index.md b/content/influxdb3/enterprise/admin/tables/_index.md new file mode 100644 index 000000000..4a61775c4 --- /dev/null +++ b/content/influxdb3/enterprise/admin/tables/_index.md @@ -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 +--- + + \ No newline at end of file diff --git a/content/influxdb3/enterprise/admin/tables/create.md b/content/influxdb3/enterprise/admin/tables/create.md new file mode 100644 index 000000000..339241de6 --- /dev/null +++ b/content/influxdb3/enterprise/admin/tables/create.md @@ -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 \ + --token \ + + ``` +related: + - /influxdb3/enterprise/reference/cli/influxdb3/create/table/ + - /influxdb3/enterprise/reference/naming-restrictions/ + - /influxdb3/enterprise/api/v3/ +source: /shared/influxdb3-admin/tables/create.md +--- + + \ No newline at end of file diff --git a/content/shared/influxdb3-admin/tables/_index.md b/content/shared/influxdb3-admin/tables/_index.md new file mode 100644 index 000000000..8e78e9e23 --- /dev/null +++ b/content/shared/influxdb3-admin/tables/_index.md @@ -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 >}} \ No newline at end of file diff --git a/content/shared/influxdb3-admin/tables/create.md b/content/shared/influxdb3-admin/tables/create.md new file mode 100644 index 000000000..736c69cd5 --- /dev/null +++ b/content/shared/influxdb3-admin/tables/create.md @@ -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. From e14b951a191fc427620dd612ce6def0cb9885914 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Thu, 10 Jul 2025 17:12:31 -0500 Subject: [PATCH 2/5] Update content/shared/influxdb3-admin/tables/_index.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- content/shared/influxdb3-admin/tables/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/shared/influxdb3-admin/tables/_index.md b/content/shared/influxdb3-admin/tables/_index.md index 8e78e9e23..3707bed7b 100644 --- a/content/shared/influxdb3-admin/tables/_index.md +++ b/content/shared/influxdb3-admin/tables/_index.md @@ -1,6 +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 +but you can also manually create them to define custom schemas or apply settings. before writing data. {{< children >}} \ No newline at end of file From a4549ad5ef37eb7e935639c9bd5b8bbbfed90fd1 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Thu, 10 Jul 2025 18:04:44 -0500 Subject: [PATCH 3/5] feat(influxdb3): add admin/tables guides for list and delete: - Add Core and Ent. guides for using the CLI and API to list and delete tables. - Closes #6215 --- content/influxdb3/core/admin/tables/create.md | 10 +- content/influxdb3/core/admin/tables/delete.md | 31 +++++ content/influxdb3/core/admin/tables/list.md | 33 +++++ .../enterprise/admin/tables/create.md | 7 ++ .../enterprise/admin/tables/delete.md | 31 +++++ .../influxdb3/enterprise/admin/tables/list.md | 33 +++++ .../shared/influxdb3-admin/tables/delete.md | 119 ++++++++++++++++++ content/shared/influxdb3-admin/tables/list.md | 118 +++++++++++++++++ 8 files changed, 381 insertions(+), 1 deletion(-) create mode 100644 content/influxdb3/core/admin/tables/delete.md create mode 100644 content/influxdb3/core/admin/tables/list.md create mode 100644 content/influxdb3/enterprise/admin/tables/delete.md create mode 100644 content/influxdb3/enterprise/admin/tables/list.md create mode 100644 content/shared/influxdb3-admin/tables/delete.md create mode 100644 content/shared/influxdb3-admin/tables/list.md diff --git a/content/influxdb3/core/admin/tables/create.md b/content/influxdb3/core/admin/tables/create.md index 47d3a7f51..21b73a9e8 100644 --- a/content/influxdb3/core/admin/tables/create.md +++ b/content/influxdb3/core/admin/tables/create.md @@ -2,7 +2,7 @@ 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. + or the [HTTP API](/influxdb3/core/api/v3/) 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: @@ -10,15 +10,23 @@ menu: weight: 201 list_code_example: | ```sh + # CLI influxdb3 create table \ --tags tag1,tag2,tag3 \ --database \ --token \ + + # HTTP API + curl -X POST "http://localhost:8181/api/v3/configure/table" \ + --header "Authorization: Bearer " \ + --header "Content-Type: application/json" \ + --data '{"db": "", "table": "", "tags": ["tag1", "tag2", "tag3"]}' ``` related: - /influxdb3/core/reference/cli/influxdb3/create/table/ - /influxdb3/core/reference/naming-restrictions/ + - /influxdb3/core/api/v3/ source: /shared/influxdb3-admin/tables/create.md --- diff --git a/content/influxdb3/core/admin/tables/delete.md b/content/influxdb3/core/admin/tables/delete.md new file mode 100644 index 000000000..73e31c377 --- /dev/null +++ b/content/influxdb3/core/admin/tables/delete.md @@ -0,0 +1,31 @@ +--- +title: Delete a table +description: > + Use the [`influxdb3 delete table` command](/influxdb3/version/reference/cli/influxdb3/delete/table/) + or the [HTTP API](/influxdb3/version/api/v3/) to delete a table from a specified database in {{< product-name >}}. + Supports both soft delete and hard delete operations. +menu: + influxdb3_core: + parent: Manage tables +weight: 203 +list_code_example: | + ```sh + # CLI + influxdb3 delete table \ + --database \ + --token \ + + + # HTTP API + curl -X DELETE "http://localhost:8181/api/v3/configure/table?db=&table=" \ + --header "Authorization: Bearer " + ``` +related: + - /influxdb3/core/reference/cli/influxdb3/delete/table/ + - /influxdb3/core/api/v3/ +source: /shared/influxdb3-admin/tables/delete.md +--- + + \ No newline at end of file diff --git a/content/influxdb3/core/admin/tables/list.md b/content/influxdb3/core/admin/tables/list.md new file mode 100644 index 000000000..dc66e30f0 --- /dev/null +++ b/content/influxdb3/core/admin/tables/list.md @@ -0,0 +1,33 @@ +--- +title: List tables +description: > + Use the [`influxdb3 query` command](/influxdb3/version/reference/cli/influxdb3/query/) + or the [HTTP API](/influxdb3/version/api/v3/) to list tables in a specified database in {{< product-name >}}. + Use SQL SHOW TABLES or InfluxQL SHOW MEASUREMENTS statements. +menu: + influxdb3_core: + parent: Manage tables +weight: 202 +list_code_example: | + ```sh + # CLI + influxdb3 query \ + --database \ + --token \ + "SHOW TABLES" + + # HTTP API + curl --get "http://localhost:8181/api/v3/query_sql" \ + --header "Authorization: Bearer " \ + --data-urlencode "db=" \ + --data-urlencode "q=SHOW TABLES" + ``` +related: + - /influxdb3/core/reference/cli/influxdb3/query/ + - /influxdb3/core/api/v3/ +source: /shared/influxdb3-admin/tables/list.md +--- + + \ No newline at end of file diff --git a/content/influxdb3/enterprise/admin/tables/create.md b/content/influxdb3/enterprise/admin/tables/create.md index 339241de6..70f88c530 100644 --- a/content/influxdb3/enterprise/admin/tables/create.md +++ b/content/influxdb3/enterprise/admin/tables/create.md @@ -10,11 +10,18 @@ menu: weight: 201 list_code_example: | ```sh + # CLI influxdb3 create table \ --tags tag1,tag2,tag3 \ --database \ --token \ + + # HTTP API + curl -X POST "http://localhost:8181/api/v3/configure/table" \ + --header "Authorization: Bearer " \ + --header "Content-Type: application/json" \ + --data '{"db": "", "table": "", "tags": ["tag1", "tag2", "tag3"]}' ``` related: - /influxdb3/enterprise/reference/cli/influxdb3/create/table/ diff --git a/content/influxdb3/enterprise/admin/tables/delete.md b/content/influxdb3/enterprise/admin/tables/delete.md new file mode 100644 index 000000000..8314f7cd1 --- /dev/null +++ b/content/influxdb3/enterprise/admin/tables/delete.md @@ -0,0 +1,31 @@ +--- +title: Delete a table +description: > + Use the [`influxdb3 delete table` command](/influxdb3/enterprise/reference/cli/influxdb3/delete/table/) + or the [HTTP API](/influxdb3/enterprise/api/v3/) to delete a table from a specified database in InfluxDB 3 Enterprise. + Supports both soft delete and hard delete operations. +menu: + influxdb3_enterprise: + parent: Manage tables +weight: 203 +list_code_example: | + ```sh + # CLI + influxdb3 delete table \ + --database \ + --token \ + + + # HTTP API + curl -X DELETE "http://localhost:8181/api/v3/configure/table?db=&table=" \ + --header "Authorization: Bearer " + ``` +related: + - /influxdb3/enterprise/reference/cli/influxdb3/delete/table/ + - /influxdb3/enterprise/api/v3/ +source: /shared/influxdb3-admin/tables/delete.md +--- + + \ No newline at end of file diff --git a/content/influxdb3/enterprise/admin/tables/list.md b/content/influxdb3/enterprise/admin/tables/list.md new file mode 100644 index 000000000..cb224724c --- /dev/null +++ b/content/influxdb3/enterprise/admin/tables/list.md @@ -0,0 +1,33 @@ +--- +title: List tables +description: > + Use the [`influxdb3 query` command](/influxdb3/version/reference/cli/influxdb3/query/) + or the [HTTP API](/influxdb3/version/api/v3/) to list tables in a specified database in {{% product-name %}}. + Use SQL SHOW TABLES or InfluxQL SHOW MEASUREMENTS statements. +menu: + influxdb3_enterprise: + parent: Manage tables +weight: 202 +list_code_example: | + ```sh + # CLI + influxdb3 query \ + --database \ + --token \ + "SHOW TABLES" + + # HTTP API + curl --get "http://localhost:8181/api/v3/query_sql" \ + --header "Authorization: Bearer " \ + --data-urlencode "db=" \ + --data-urlencode "q=SHOW TABLES" + ``` +related: + - /influxdb3/enterprise/reference/cli/influxdb3/query/ + - /influxdb3/enterprise/api/v3/ +source: /shared/influxdb3-admin/tables/list.md +--- + + \ No newline at end of file diff --git a/content/shared/influxdb3-admin/tables/delete.md b/content/shared/influxdb3-admin/tables/delete.md new file mode 100644 index 000000000..1e4f1247e --- /dev/null +++ b/content/shared/influxdb3-admin/tables/delete.md @@ -0,0 +1,119 @@ +Use the [`influxdb3 delete table` command](/influxdb3/version/reference/cli/influxdb3/delete/table/) +or the [HTTP API](/influxdb3/version/api/v3/) to delete a table from a specified database in {{< product-name >}}. + +With {{< product-name >}}, tables and measurements are synonymous. +By default, {{< product-name >}} performs a soft delete, which schedules the table for deletion and makes it unavailable for querying. +You can also schedule a hard deletion to permanently remove the table and its data. + +> [!Caution] +> #### Deleting a table cannot be undone +> +> Deleting a table is a destructive action. +> Once a table is deleted, data stored in that table cannot be recovered. + +- [Delete a table using the influxdb3 CLI](#delete-a-table-using-the-influxdb3-cli) +- [Delete a table using the HTTP API](#delete-a-table-using-the-http-api) + +## Delete 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. Use the `influxdb3 delete table` command to delete a table: + +{{% code-placeholders "DATABASE_NAME|TABLE_NAME|AUTH_TOKEN" %}} +```sh +influxdb3 delete table \ + --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 containing the table +- {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}}: the name of the table to delete +- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "admin" %}} + +### Hard delete a table immediately + +To permanently delete a table and its data immediately, use the `--hard-delete now` flag: + +{{% code-placeholders "DATABASE_NAME|TABLE_NAME|AUTH_TOKEN" %}} +```sh +influxdb3 delete table \ + --database DATABASE_NAME \ + --token AUTH_TOKEN \ + --hard-delete now \ + TABLE_NAME +``` +{{% /code-placeholders %}} + +### Schedule a hard deletion + +To schedule a table for hard deletion at a specific time, use the `--hard-delete` flag with a timestamp: + +{{% code-placeholders "DATABASE_NAME|TABLE_NAME|AUTH_TOKEN" %}} +```sh +influxdb3 delete table \ + --database DATABASE_NAME \ + --token AUTH_TOKEN \ + --hard-delete "2025-12-31T23:59:59Z" \ + TABLE_NAME +``` +{{% /code-placeholders %}} + +## Delete a table using the HTTP API + +To delete a table using the HTTP API, send a `DELETE` request to the `/api/v3/configure/table` endpoint: + +{{% api-endpoint method="DELETE" endpoint="{{< influxdb/host >}}/api/v3/configure/table" %}} + +Include the following in your request: + +- **Query parameters**: + - `db`: Database name + - `table`: Table name to delete + - `hard_delete_at`: _(Optional)_ Timestamp for hard deletion +- **Headers**: + - `Authorization: Bearer` with your authentication token + +### Soft delete a table + +{{% code-placeholders "DATABASE_NAME|TABLE_NAME|AUTH_TOKEN" %}} +```bash +curl -X DELETE "{{< influxdb/host >}}/api/v3/configure/table?db=DATABASE_NAME&table=TABLE_NAME" \ + --header "Authorization: Bearer AUTH_TOKEN" +``` +{{% /code-placeholders %}} + +Replace the following: + +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database containing the table +- {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}}: the name of the table to delete +- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "admin" %}} + +### Schedule a hard deletion + +To schedule a hard deletion at a specific time, include the `hard_delete_at` parameter with an ISO 8601 timestamp: + +{{% code-placeholders "DATABASE_NAME|TABLE_NAME|AUTH_TOKEN" %}} +```bash +curl -X DELETE "{{< influxdb/host >}}/api/v3/configure/table?db=DATABASE_NAME&table=TABLE_NAME&hard_delete_at=2025-12-31T23:59:59Z" \ + --header "Authorization: Bearer AUTH_TOKEN" +``` +{{% /code-placeholders %}} + +### Response + +A successful deletion returns HTTP status `200` with no content body. + +#### Example error response + +If the table doesn't exist, the API returns HTTP status `404`: + +```json +{ + "error": "Table not found" +} +``` \ No newline at end of file diff --git a/content/shared/influxdb3-admin/tables/list.md b/content/shared/influxdb3-admin/tables/list.md new file mode 100644 index 000000000..3d2a7a198 --- /dev/null +++ b/content/shared/influxdb3-admin/tables/list.md @@ -0,0 +1,118 @@ +Use the [`influxdb3 query` command](/influxdb3/version/reference/cli/influxdb3/query/) +or the [HTTP API](/influxdb3/version/api/v3/) to list tables in a specified database in {{< product-name >}}. + +With {{< product-name >}}, tables and measurements are synonymous. +This guide shows how to retrieve a list of all tables (measurements) in a database. + +- [List tables using the influxdb3 CLI](#list-tables-using-the-influxdb3-cli) +- [List tables using the HTTP API](#list-tables-using-the-http-api) + +## List tables 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. Use the `influxdb3 query` command with the `SHOW TABLES` SQL statement: + +{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}} +```sh +influxdb3 query \ + --database DATABASE_NAME \ + --token AUTH_TOKEN \ + "SHOW TABLES" +``` +{{% /code-placeholders %}} + +Replace the following: + +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to list tables from +- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "admin" %}} + +### Example output + +``` ++---------------+---------------+------------+------------+ +| table_catalog | table_schema | table_name | table_type | ++---------------+---------------+------------+------------+ +| public | iox | home | BASE TABLE | +| public | iox | sensors | BASE TABLE | ++---------------+---------------+------------+------------+ +``` + +### Alternative: List tables using InfluxQL + +You can also use InfluxQL syntax to list measurements (tables): + +{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}} +```sh +influxdb3 query \ + --language influxql \ + --database DATABASE_NAME \ + --token AUTH_TOKEN \ + "SHOW MEASUREMENTS" +``` +{{% /code-placeholders %}} + +## List tables using the HTTP API + +To list tables using the HTTP API, send a `GET` request to the `/api/v3/query_sql` endpoint with a `SHOW TABLES` query: + +{{% api-endpoint method="GET" endpoint="{{< influxdb/host >}}/api/v3/query_sql" %}} + +Include the following in your request: + +- **Query parameters**: + - `db`: Database name + - `q`: The SQL query (`SHOW TABLES`) + - `format`: Response format (optional, defaults to `json`) +- **Headers**: + - `Authorization: Bearer` with your authentication token + +{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}} +```bash +curl --get "{{< influxdb/host >}}/api/v3/query_sql" \ + --header "Authorization: Bearer AUTH_TOKEN" \ + --data-urlencode "db=DATABASE_NAME" \ + --data-urlencode "q=SHOW TABLES" \ + --data-urlencode "format=json" +``` +{{% /code-placeholders %}} + +Replace the following: + +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to list tables from +- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "admin" %}} + +### Example response + +```json +{ + "results": [ + { + "series": [ + { + "name": "tables", + "columns": ["table_catalog", "table_schema", "table_name", "table_type"], + "values": [ + ["public", "iox", "home", "BASE TABLE"], + ["public", "iox", "sensors", "BASE TABLE"] + ] + } + ] + } + ] +} +``` + +### Get response in CSV format + +To get the response in CSV format, set the `format` parameter to `csv`: + +{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}} +```bash +curl --get "{{< influxdb/host >}}/api/v3/query_sql" \ + --header "Authorization: Bearer AUTH_TOKEN" \ + --data-urlencode "db=DATABASE_NAME" \ + --data-urlencode "q=SHOW TABLES" \ + --data-urlencode "format=csv" +``` +{{% /code-placeholders %}} \ No newline at end of file From 3f8b84e4e1568e48b5381f493bc166ff1129378d Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Fri, 11 Jul 2025 08:12:40 -0500 Subject: [PATCH 4/5] Apply suggestions from code review Co-authored-by: Scott Anderson --- content/influxdb3/core/admin/tables/delete.md | 4 ++-- content/influxdb3/core/admin/tables/list.md | 4 ++-- content/influxdb3/enterprise/admin/tables/list.md | 4 ++-- content/shared/influxdb3-admin/tables/create.md | 2 +- 4 files changed, 7 insertions(+), 7 deletions(-) diff --git a/content/influxdb3/core/admin/tables/delete.md b/content/influxdb3/core/admin/tables/delete.md index 73e31c377..4a1ee11f6 100644 --- a/content/influxdb3/core/admin/tables/delete.md +++ b/content/influxdb3/core/admin/tables/delete.md @@ -1,8 +1,8 @@ --- title: Delete a table description: > - Use the [`influxdb3 delete table` command](/influxdb3/version/reference/cli/influxdb3/delete/table/) - or the [HTTP API](/influxdb3/version/api/v3/) to delete a table from a specified database in {{< product-name >}}. + Use the [`influxdb3 delete table` command](/influxdb3/core/reference/cli/influxdb3/delete/table/) + or the [HTTP API](/influxdb3/core/api/v3/) to delete a table from a specified database in {{< product-name >}}. Supports both soft delete and hard delete operations. menu: influxdb3_core: diff --git a/content/influxdb3/core/admin/tables/list.md b/content/influxdb3/core/admin/tables/list.md index dc66e30f0..3cc4ab7ac 100644 --- a/content/influxdb3/core/admin/tables/list.md +++ b/content/influxdb3/core/admin/tables/list.md @@ -1,8 +1,8 @@ --- title: List tables description: > - Use the [`influxdb3 query` command](/influxdb3/version/reference/cli/influxdb3/query/) - or the [HTTP API](/influxdb3/version/api/v3/) to list tables in a specified database in {{< product-name >}}. + Use the [`influxdb3 query` command](/influxdb3/core/reference/cli/influxdb3/query/) + or the [HTTP API](/influxdb3/core/api/v3/) to list tables in a specified database in {{< product-name >}}. Use SQL SHOW TABLES or InfluxQL SHOW MEASUREMENTS statements. menu: influxdb3_core: diff --git a/content/influxdb3/enterprise/admin/tables/list.md b/content/influxdb3/enterprise/admin/tables/list.md index cb224724c..e76a17a01 100644 --- a/content/influxdb3/enterprise/admin/tables/list.md +++ b/content/influxdb3/enterprise/admin/tables/list.md @@ -1,8 +1,8 @@ --- title: List tables description: > - Use the [`influxdb3 query` command](/influxdb3/version/reference/cli/influxdb3/query/) - or the [HTTP API](/influxdb3/version/api/v3/) to list tables in a specified database in {{% product-name %}}. + Use the [`influxdb3 query` command](/influxdb3/enterprise/reference/cli/influxdb3/query/) + or the [HTTP API](/influxdb3/enterprise/api/v3/) to list tables in a specified database in {{% product-name %}}. Use SQL SHOW TABLES or InfluxQL SHOW MEASUREMENTS statements. menu: influxdb3_enterprise: diff --git a/content/shared/influxdb3-admin/tables/create.md b/content/shared/influxdb3-admin/tables/create.md index 736c69cd5..4d8298e27 100644 --- a/content/shared/influxdb3-admin/tables/create.md +++ b/content/shared/influxdb3-admin/tables/create.md @@ -2,7 +2,7 @@ Use the [`influxdb3 create table` command](/influxdb3/version/reference/cli/infl 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 +Typically, tables are created automatically on write using the table 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. From 9c14bddb3acb51c680b5076b36fcf7d07928d834 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Fri, 11 Jul 2025 08:24:46 -0500 Subject: [PATCH 5/5] fix(influxdb3): add tag priority guidance --- content/shared/influxdb3-admin/tables/create.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/content/shared/influxdb3-admin/tables/create.md b/content/shared/influxdb3-admin/tables/create.md index 4d8298e27..a79c44a85 100644 --- a/content/shared/influxdb3-admin/tables/create.md +++ b/content/shared/influxdb3-admin/tables/create.md @@ -18,7 +18,7 @@ However, you can manually create tables to define a custom schema or apply custo - _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 + - _Required_: Tag columns to include in the table (must have at least one tag column) - _Optional_: Field columns and their data types to include in the table {{% show-in "enterprise" %}} - _Optional_: A retention period for the table @@ -27,6 +27,14 @@ However, you can manually create tables to define a custom schema or apply custo > [!Note] > Tables must include at least one tag column. > Field columns are optional and can be added later when you write data. + + > [!Important] + > #### Tag order affects query performance + > When considering your schema and creating your table, order your tags by query priority. + > Place the most commonly queried tags first. + > Columns that appear earlier are typically faster to filter and access during query execution. + > + > For more information, see [Optimize writes](/influxdb3/version/write-data/best-practices/optimize-writes/#sort-tags-by-query-priority). {{% code-placeholders "DATABASE_NAME|TABLE_NAME|AUTH_TOKEN" %}} ```bash