From a4549ad5ef37eb7e935639c9bd5b8bbbfed90fd1 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Thu, 10 Jul 2025 18:04:44 -0500 Subject: [PATCH] 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