fix(influxdb3): Update API reference and fix processing engine documentation for 3.2 release

jstirnaman · claude · jstirnaman · commit 1db855046229 · 2025-06-30T13:33:52.000-05:00
Resolves issue #6161 with InfluxDB 3.2 API reference updates. ## API Reference Updates - Add `hard_delete_at` parameter to database and table deletion endpoints for scheduled hard deletion - Add update database and update table endpoints with retention period configuration - Add license endpoint response schema - Fix request trigger specification format from `path:` to `request:` in Core API - Fix OpenAPI schema validation error in Enterprise API by removing conflicting type declaration ## Processing Engine Documentation Fixes - Standardize terminology across documentation: - "Data write" (not "WAL flush" or "On WAL flush") - "Scheduled" (not "On Schedule") - "HTTP request" (not "On Request") - Fix placeholder inconsistencies: use REQUEST_PATH instead of ENDPOINT_PATH - Add Enterprise-specific warnings about request trigger format differences - Update trigger specification format in Enterprise API to use JSON object format - Add proper table of contents with consistent structure - Improve distributed cluster configuration documentation ## Enterprise Request Trigger Bug Documentation Due to a bug in InfluxDB 3 Enterprise, the request trigger specification format differs between CLI and API: - CLI: `request:<REQUEST_PATH>` (same as Core CLI and API) - Enterprise API: `{"request_path": {"path": "<REQUEST_PATH>"}}` This difference is now properly documented with warnings in all relevant sections. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/api-docs/influxdb3/core/v3/ref.yml b/api-docs/influxdb3/core/v3/ref.yml
@@ -922,9 +922,25 @@ paths:
       summary: Delete a database
       description: |
         Soft deletes a database.
-        The database is scheduled for deletion and unavailable for querying.  
+        The database is scheduled for deletion and unavailable for querying.
+        Use the `hard_delete_at` parameter to schedule a hard deletion.
       parameters:
         - $ref: '#/components/parameters/db'
+        - name: hard_delete_at
+          in: query
+          required: false
+          schema:
+            type: string
+            format: date-time
+          description: |
+            Schedule the database for hard deletion at the specified time.
+            If not provided, the database will be soft deleted.
+            Use ISO 8601 date-time format (for example, "2025-12-31T23:59:59Z").
+
+            #### 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.
       responses:
         '200':
           description: Success. Database deleted.
@@ -961,14 +977,30 @@ paths:
       summary: Delete a table
       description: |
         Soft deletes a table.
-        The table is scheduled for deletion and unavailable for querying.  
+        The table is scheduled for deletion and unavailable for querying.
+        Use the `hard_delete_at` parameter to schedule a hard deletion.
+
+        #### 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.
       parameters:
         - $ref: '#/components/parameters/db'
         - name: table
           in: query
           required: true
           schema:
             type: string
+        - name: hard_delete_at
+          in: query
+          required: false
+          schema:
+            type: string
+            format: date-time
+          description: |
+            Schedule the table for hard deletion at the specified time.
+            If not provided, the table will be soft deleted.
+            Use ISO 8601 format (for example, "2025-12-31T23:59:59Z").
       responses:
         '200':
           description: Success (no content). The table has been deleted.
@@ -1078,7 +1110,7 @@ paths:
                   In `"cron:CRON_EXPRESSION"`, `CRON_EXPRESSION` uses extended 6-field cron format.
                   The cron expression `0 0 6 * * 1-5` means the trigger will run at 6:00 AM every weekday (Monday to Friday).
                 value:
-                  db: DATABASE_NAME
+                  db: mydb
                   plugin_filename: schedule.py
                   trigger_name: schedule_cron_trigger
                   trigger_specification: cron:0 0 6 * * 1-5
@@ -1136,7 +1168,7 @@ paths:
                   db: mydb
                   plugin_filename: request.py
                   trigger_name: hello_world_trigger
-                  trigger_specification: path:hello-world
+                  trigger_specification: request:hello-world
               cron_friday_afternoon:
                 summary: Cron trigger for Friday afternoons
                 description: |
@@ -1365,16 +1397,16 @@ paths:
           description: Plugin not enabled.
       tags:
         - Processing engine
-  /api/v3/engine/{plugin_path}:
+  /api/v3/engine/{request_path}:
     parameters:
-      - name: plugin_path
+      - name: request_path
         description: |
-          The path configured in the request trigger specification "path:<plugin_path>"` for the plugin.
+          The path configured in the request trigger specification for the plugin.
 
           For example, if you define a trigger with the following:
 
           ```json
-          trigger-spec: "path:hello-world"
+          trigger_specification: "request:hello-world"
           ```
 
           then, the HTTP API exposes the following plugin endpoint:
@@ -1390,7 +1422,7 @@ paths:
       operationId: GetProcessingEnginePluginRequest
       summary: On Request processing engine plugin request
       description: |
-        Executes the On Request processing engine plugin specified in `<plugin_path>`.
+        Executes the On Request processing engine plugin specified in the trigger's `plugin_filename`.
         The request can include request headers, query string parameters, and a request body, which InfluxDB passes to the plugin.
 
         An On Request plugin implements the following signature:
@@ -1417,7 +1449,7 @@ paths:
       operationId: PostProcessingEnginePluginRequest
       summary: On Request processing engine plugin request
       description: |
-        Executes the On Request processing engine plugin specified in `<plugin_path>`.
+        Executes the On Request processing engine plugin specified in the trigger's `plugin_filename`.
         The request can include request headers, query string parameters, and a request body, which InfluxDB passes to the plugin.
 
         An On Request plugin implements the following signature:
@@ -1868,7 +1900,7 @@ components:
             `schedule.py` or `endpoints/report.py`.
             The path can be absolute or relative to the `--plugins-dir` directory configured when starting InfluxDB 3.
 
-            The plugin file must implement the trigger interface associated with the trigger's specification (`trigger_spec`).
+            The plugin file must implement the trigger interface associated with the trigger's specification.
         trigger_name:
           type: string
         trigger_specification:
@@ -1911,12 +1943,12 @@ components:
             - `table:TABLE_NAME` - Triggers on write events to a specific table
 
             ### On-demand triggers
-            Format: `path:ENDPOINT_NAME`
+            Format: `request:REQUEST_PATH`
 
-            Creates an HTTP endpoint `/api/v3/engine/ENDPOINT_NAME` for manual invocation:
-            - `path:hello-world` - Creates endpoint `/api/v3/engine/hello-world`
-            - `path:data-export` - Creates endpoint `/api/v3/engine/data-export`
-          pattern: ^(cron:[0-9 *,/-]+|every:[0-9]+[smhd]|all_tables|table:[a-zA-Z_][a-zA-Z0-9_]*|path:[a-zA-Z0-9_-]+)$
+            Creates an HTTP endpoint `/api/v3/engine/REQUEST_PATH` for manual invocation:
+            - `request:hello-world` - Creates endpoint `/api/v3/engine/hello-world`
+            - `request:data-export` - Creates endpoint `/api/v3/engine/data-export`
+          pattern: ^(cron:[0-9 *,/-]+|every:[0-9]+[smhd]|all_tables|table:[a-zA-Z_][a-zA-Z0-9_]*|request:[a-zA-Z0-9_-]+)$
           example: cron:0 0 6 * * 1-5
         trigger_arguments:
           type: object
@@ -2013,6 +2045,65 @@ components:
         - m
         - h
       type: string
+    UpdateDatabaseRequest:
+      type: object
+      properties:
+        retention_period:
+          type: string
+          description: |
+            The retention period for the database. Specifies how long data should be retained.
+            Use duration format (for example, "1d", "1h", "30m", "7d").
+          example: "7d"
+      description: Request schema for updating database configuration.
+    UpdateTableRequest:
+      type: object
+      properties:
+        db:
+          type: string
+          description: The name of the database containing the table.
+        table:
+          type: string
+          description: The name of the table to update.
+        retention_period:
+          type: string
+          description: |
+            The retention period for the table. Specifies how long data in this table should be retained.
+            Use duration format (for example, "1d", "1h", "30m", "7d").
+          example: "30d"
+      required:
+        - db
+        - table
+      description: Request schema for updating table configuration.
+    LicenseResponse:
+      type: object
+      properties:
+        license_type:
+          type: string
+          description: The type of license (for example, "enterprise", "trial").
+          example: "enterprise"
+        expires_at:
+          type: string
+          format: date-time
+          description: The expiration date of the license in ISO 8601 format.
+          example: "2025-12-31T23:59:59Z"
+        features:
+          type: array
+          items:
+            type: string
+          description: List of features enabled by the license.
+          example:
+            - "clustering"
+            - "processing_engine"
+            - "advanced_auth"
+        status:
+          type: string
+          enum:
+            - "active"
+            - "expired"
+            - "invalid"
+          description: The current status of the license.
+          example: "active"
+      description: Response schema for license information.
   responses:
     Unauthorized:
       description: Unauthorized access.
diff --git a/api-docs/influxdb3/enterprise/v3/ref.yml b/api-docs/influxdb3/enterprise/v3/ref.yml
@@ -1240,7 +1240,7 @@ paths:
                   plugin_filename: request.py
                   trigger_name: hello_world_trigger
                   # trigger_specification: "request:hello-world" - For 3.2.1 (issue#6171)
-                  trigger_specification: '{"request_path": {"path": "hello-world"}}'
+                  trigger_specification: {"request_path": {"path": "hello-world"}}
               cron_friday_afternoon:
                 summary: Cron trigger for Friday afternoons
                 description: |
@@ -2056,7 +2056,6 @@ components:
         trigger_name:
           type: string
         trigger_specification:
-          type: string
           description: |
             Specifies when and how the processing engine trigger should be invoked.
 
diff --git a/content/shared/influxdb3-cli/create/trigger.md b/content/shared/influxdb3-cli/create/trigger.md
@@ -27,7 +27,7 @@ influxdb3 create trigger [OPTIONS] \
 | `-d`   | `--database`        | _({{< req >}})_ Name of the database to operate on                                                       |
 |        | `--token`           | _({{< req >}})_ Authentication token                                                                     |
 |        | `--plugin-filename` | _({{< req >}})_ Name of the file, stored in the server's `plugin-dir`, that contains the Python plugin code to run     | 
-|        | `--trigger-spec`    | Trigger specification--for example `table:<TABLE_NAME>` or `all_tables`                                  |
+|        | `--trigger-spec`    | Trigger specification: `table:<TABLE_NAME>`, `all_tables`, `every:<DURATION>`, `cron:<EXPRESSION>`, or `request:<REQUEST_PATH>`                             |
 |        | `--disabled`        | Create the trigger in disabled state                                                                     |
 |        | `--tls-ca`          | Path to a custom TLS certificate authority (for testing or self-signed certificates)                     |
 | `-h`   | `--help`            | Print help information                                                                                   |
@@ -113,3 +113,15 @@ influxdb3 create trigger \
 Creating a trigger in a disabled state prevents it from running immediately. You can enable it later when you're ready to activate it.
 
 {{% /code-placeholders %}}
+
+{{% show-in "enterprise" %}}
+> [!Warning]
+> #### Request trigger specification format differs between CLI and API
+> 
+> Due to a bug in InfluxDB 3 Enterprise, the request trigger specification format differs:
+> 
+> - **CLI**: `request:<REQUEST_PATH>` (same as Core CLI and API)
+> - **Enterprise API**: `{"request_path": {"path": "<REQUEST_PATH>"}}`
+> 
+> See the [API reference](/influxdb3/enterprise/api/#operation/PostConfigureProcessingEngineTrigger) for examples. Use `influxdb3 show summary` to verify the actual trigger specification.
+{{% /show-in %}}
diff --git a/content/shared/influxdb3-get-started/processing-engine.md b/content/shared/influxdb3-get-started/processing-engine.md
@@ -23,24 +23,36 @@ engine [trigger](#trigger).
 ### Trigger
 
 When you create a trigger, you specify a [plugin](#plugin), a database, optional
-arguments, and a _trigger-spec_, which defines when the plugin is executed and
+arguments, and a trigger specification, which defines when the plugin is executed and
 what data it receives.
 
 #### Trigger types
 
 InfluxDB 3 provides the following types of triggers, each with specific
-trigger-specs:
+specifications:
 
-- **On WAL flush**: Sends a batch of written data (for a specific table or all
-  tables) to a plugin (by default, every second).
-- **On Schedule**: Executes a plugin on a user-configured schedule (using a
+- **Data write** (`table:` or `all_tables`): Sends a batch of written data (for a specific table or all
+  tables) to a plugin when the database flushes data to the Write-Ahead Log (by default, every second).
+- **Scheduled** (`every:` or `cron:`): Executes a plugin on a user-configured schedule (using a
   crontab or a duration). This trigger type is useful for data collection and
   deadman monitoring.
-- **On Request**: Binds a plugin to a custom HTTP API endpoint at
-  `/api/v3/engine/<ENDPOINT_PATH>`.
+- **HTTP request** (`request:`): Binds a plugin to a custom HTTP API endpoint at
+  `/api/v3/engine/<REQUEST_PATH>`.
   The plugin receives the HTTP request headers and content, and can parse,
   process, and send the data into the database or to third-party services.
 
+{{% show-in "enterprise" %}}
+> [!Warning]
+> #### Request trigger specification format differs between CLI and API
+> 
+> Due to a bug in InfluxDB 3 Enterprise, the request trigger specification format differs:
+> 
+> - **CLI**: `request:<REQUEST_PATH>` (same as Core CLI and API)
+> - **Enterprise API**: `{"request_path": {"path": "<REQUEST_PATH>"}}`
+> 
+> See the [API reference](/influxdb3/enterprise/api/#operation/PostConfigureProcessingEngineTrigger) for examples. Use `influxdb3 show summary` to verify the actual trigger specification.
+{{% /show-in %}}
+
 ## Activate the processing engine
 
 To activate the processing engine, include the `--plugin-dir <PLUGIN_DIR>` option
@@ -64,10 +76,10 @@ to the current working directory of the `influxdb3` server.
 ## Create a plugin
 
 To create a plugin, write and store a Python file in your configured `PLUGIN_DIR`.
-The following example is a WAL flush plugin that processes data before it gets
+The following example is a data write plugin that processes data before it gets
 persisted to the object store.
 
-##### Example Python plugin for WAL rows 
+##### Example Python plugin for data writes 
 
 ```python
 # This is the basic structure for Python plugin code that runs in the
@@ -77,9 +89,9 @@ persisted to the object store.
 # allowing you to write generic code that uses variables such as monitoring
 # thresholds, environment variables, and host names.
 #
-# Use the following exact signature to define a function for the WAL flush
+# Use the following exact signature to define a function for the data write
 # trigger.
-# When you create a trigger for a WAL flush plugin, you specify the database
+# When you create a trigger for a data write plugin, you specify the database
 # and tables that the plugin receives written data from on every WAL flush
 # (default is once per second).
 def process_writes(influxdb3_local, table_batches, args=None):
@@ -98,9 +110,8 @@ def process_writes(influxdb3_local, table_batches, args=None):
     # value.
     influxdb3_local.info("query result: " + str(query_result))
 
-    # this is the data that is sent when the WAL is flushed of writes the server 
-    # received for the DB or table of interest. One batch for each table (will 
-    # only be one if triggered on a single table)
+    # this is the data that is sent when data is written to the database and flushed to the WAL. 
+    # One batch for each table (will only be one if triggered on a single table)
     for table_batch in table_batches:
         # here you can see that the table_name is available.
         influxdb3_local.info("table: " + table_batch["table_name"])
diff --git a/content/shared/v3-core-plugins/_index.md b/content/shared/v3-core-plugins/_index.md
diff --git a/test/influxdb3/engine.test.sh b/test/influxdb3/engine.test.sh
