From 87083291f5d58fb678f73aad60d8653f6c01b879 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Tue, 16 Dec 2025 14:31:56 -0500 Subject: [PATCH] fix(influxdb3): add trigger settings and related API parameters (#6630) Add trigger configuration and cluster targeting parameters to API specs: Core: - TriggerSettings schema (run_async, error_behavior) - trigger_settings field in ProcessingEngineTriggerRequest (required) - Updated all trigger creation examples Enterprise: - TriggerSettings schema (run_async, error_behavior) - ApiNodeSpec schema for cluster node targeting - trigger_settings and node_spec fields in ProcessingEngineTriggerRequest - node_spec field in cache creation requests (DistinctCache, LastCache) - force parameter description for trigger deletion - Request body schemas for plugin test/update endpoints: - WALPluginTestRequest - SchedulePluginTestRequest - PluginFileRequest - PluginDirectoryRequest - PluginFileEntry - Updated all trigger creation examples closes #6610 --- api-docs/influxdb3/core/v3/ref.yml | 60 +++++++ api-docs/influxdb3/enterprise/v3/ref.yml | 220 +++++++++++++++++++++++ 2 files changed, 280 insertions(+) diff --git a/api-docs/influxdb3/core/v3/ref.yml b/api-docs/influxdb3/core/v3/ref.yml index d7a3681b2..5b00fa7ae 100644 --- a/api-docs/influxdb3/core/v3/ref.yml +++ b/api-docs/influxdb3/core/v3/ref.yml @@ -1325,6 +1325,9 @@ paths: plugin_filename: schedule.py trigger_name: schedule_cron_trigger trigger_specification: cron:0 0 6 * * 1-5 + trigger_settings: + run_async: false + error_behavior: Log schedule_every: summary: Schedule trigger using interval description: | @@ -1335,6 +1338,9 @@ paths: plugin_filename: schedule.py trigger_name: schedule_every_trigger trigger_specification: every:1h + trigger_settings: + run_async: false + error_behavior: Log schedule_every_seconds: summary: Schedule trigger using seconds interval description: | @@ -1344,6 +1350,9 @@ paths: plugin_filename: schedule.py trigger_name: schedule_every_30s_trigger trigger_specification: every:30s + trigger_settings: + run_async: false + error_behavior: Log schedule_every_minutes: summary: Schedule trigger using minutes interval description: | @@ -1353,6 +1362,9 @@ paths: plugin_filename: schedule.py trigger_name: schedule_every_5m_trigger trigger_specification: every:5m + trigger_settings: + run_async: false + error_behavior: Log all_tables: summary: All tables trigger example description: | @@ -1362,6 +1374,9 @@ paths: plugin_filename: all_tables.py trigger_name: all_tables_trigger trigger_specification: all_tables + trigger_settings: + run_async: false + error_behavior: Log table_specific: summary: Table-specific trigger example description: | @@ -1371,6 +1386,9 @@ paths: plugin_filename: table.py trigger_name: table_trigger trigger_specification: table:sensors + trigger_settings: + run_async: false + error_behavior: Log api_request: summary: On-demand request trigger example description: | @@ -1380,6 +1398,9 @@ paths: plugin_filename: request.py trigger_name: hello_world_trigger trigger_specification: request:hello-world + trigger_settings: + run_async: false + error_behavior: Log cron_friday_afternoon: summary: Cron trigger for Friday afternoons description: | @@ -1389,6 +1410,9 @@ paths: plugin_filename: weekly_report.py trigger_name: friday_report_trigger trigger_specification: cron:0 30 14 * * 5 + trigger_settings: + run_async: false + error_behavior: Log cron_monthly: summary: Cron trigger for monthly execution description: | @@ -1398,6 +1422,9 @@ paths: plugin_filename: monthly_cleanup.py trigger_name: monthly_cleanup_trigger trigger_specification: cron:0 0 0 1 * * + trigger_settings: + run_async: false + error_behavior: Log responses: '200': description: Success. Processing engine trigger created. @@ -2241,6 +2268,11 @@ components: The plugin file must implement the trigger interface associated with the trigger's specification. trigger_name: type: string + trigger_settings: + description: | + Configuration for trigger error handling and execution behavior. + allOf: + - $ref: '#/components/schemas/TriggerSettings' trigger_specification: type: string description: | @@ -2305,7 +2337,35 @@ components: - db - plugin_filename - trigger_name + - trigger_settings - trigger_specification + TriggerSettings: + type: object + description: | + Configuration settings for processing engine trigger error handling and execution behavior. + properties: + run_async: + type: boolean + default: false + description: | + Whether to run the trigger asynchronously. + When `true`, the trigger executes in the background without blocking. + When `false`, the trigger executes synchronously. + error_behavior: + type: string + enum: + - Log + - Retry + - Disable + description: | + Specifies how to handle errors that occur during trigger execution: + - `Log`: Log the error and continue (default) + - `Retry`: Retry the trigger execution + - `Disable`: Disable the trigger after an error + default: Log + required: + - run_async + - error_behavior ShowDatabasesResponse: type: object properties: diff --git a/api-docs/influxdb3/enterprise/v3/ref.yml b/api-docs/influxdb3/enterprise/v3/ref.yml index 4b2122d94..4017af1dd 100644 --- a/api-docs/influxdb3/enterprise/v3/ref.yml +++ b/api-docs/influxdb3/enterprise/v3/ref.yml @@ -1395,6 +1395,9 @@ paths: plugin_filename: schedule.py trigger_name: schedule_cron_trigger trigger_specification: cron:0 0 6 * * 1-5 + trigger_settings: + run_async: false + error_behavior: Log schedule_every: summary: Schedule trigger using interval description: | @@ -1405,6 +1408,9 @@ paths: plugin_filename: schedule.py trigger_name: schedule_every_trigger trigger_specification: every:1h + trigger_settings: + run_async: false + error_behavior: Log schedule_every_seconds: summary: Schedule trigger using seconds interval description: | @@ -1414,6 +1420,9 @@ paths: plugin_filename: schedule.py trigger_name: schedule_every_30s_trigger trigger_specification: every:30s + trigger_settings: + run_async: false + error_behavior: Log schedule_every_minutes: summary: Schedule trigger using minutes interval description: | @@ -1423,6 +1432,9 @@ paths: plugin_filename: schedule.py trigger_name: schedule_every_5m_trigger trigger_specification: every:5m + trigger_settings: + run_async: false + error_behavior: Log all_tables: summary: All tables trigger example description: | @@ -1432,6 +1444,9 @@ paths: plugin_filename: all_tables.py trigger_name: all_tables_trigger trigger_specification: all_tables + trigger_settings: + run_async: false + error_behavior: Log table_specific: summary: Table-specific trigger example description: | @@ -1441,6 +1456,9 @@ paths: plugin_filename: table.py trigger_name: table_trigger trigger_specification: table:sensors + trigger_settings: + run_async: false + error_behavior: Log api_request: summary: On-demand request trigger example description: | @@ -1450,6 +1468,9 @@ paths: plugin_filename: request.py trigger_name: hello_world_trigger trigger_specification: request:hello-world + trigger_settings: + run_async: false + error_behavior: Log cron_friday_afternoon: summary: Cron trigger for Friday afternoons description: | @@ -1459,6 +1480,9 @@ paths: plugin_filename: weekly_report.py trigger_name: friday_report_trigger trigger_specification: cron:0 30 14 * * 5 + trigger_settings: + run_async: false + error_behavior: Log cron_monthly: summary: Cron trigger for monthly execution description: | @@ -1468,6 +1492,9 @@ paths: plugin_filename: monthly_cleanup.py trigger_name: monthly_cleanup_trigger trigger_specification: cron:0 0 0 1 * * + trigger_settings: + run_async: false + error_behavior: Log responses: '200': description: Success. Processing engine trigger created. @@ -1496,6 +1523,9 @@ paths: schema: type: boolean default: false + description: | + Force deletion of the trigger even if it has active executions. + By default, deletion fails if the trigger is currently executing. responses: '200': description: Success. The processing engine trigger has been deleted. @@ -1651,6 +1681,12 @@ paths: operationId: PostTestWALPlugin summary: Test WAL plugin description: Executes a test of a write-ahead logging (WAL) plugin. + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/WALPluginTestRequest' responses: '200': description: Success. The plugin test has been executed. @@ -1667,6 +1703,12 @@ paths: operationId: PostTestSchedulingPlugin summary: Test scheduling plugin description: Executes a test of a scheduling plugin. + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/SchedulePluginTestRequest' responses: '200': description: Success. The plugin test has been executed. @@ -1885,6 +1927,12 @@ paths: description: | Updates a plugin file in the plugin directory. x-security-note: Requires an admin token + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/PluginFileRequest' responses: '204': description: Success. The plugin file has been updated. @@ -1901,6 +1949,12 @@ paths: description: | Updates the plugin directory configuration. x-security-note: Requires an admin token + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/PluginDirectoryRequest' responses: '204': description: Success. The plugin directory has been updated. @@ -2302,6 +2356,8 @@ components: type: string table: type: string + node_spec: + $ref: '#/components/schemas/ApiNodeSpec' name: type: string description: Optional cache name. @@ -2334,6 +2390,8 @@ components: type: string table: type: string + node_spec: + $ref: '#/components/schemas/ApiNodeSpec' name: type: string description: Optional cache name. @@ -2378,8 +2436,15 @@ components: 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. + node_spec: + $ref: '#/components/schemas/ApiNodeSpec' trigger_name: type: string + trigger_settings: + description: | + Configuration for trigger error handling and execution behavior. + allOf: + - $ref: '#/components/schemas/TriggerSettings' trigger_specification: description: | Specifies when and how the processing engine trigger should be invoked. @@ -2443,7 +2508,162 @@ components: - db - plugin_filename - trigger_name + - trigger_settings - trigger_specification + TriggerSettings: + type: object + description: | + Configuration settings for processing engine trigger error handling and execution behavior. + properties: + run_async: + type: boolean + default: false + description: | + Whether to run the trigger asynchronously. + When `true`, the trigger executes in the background without blocking. + When `false`, the trigger executes synchronously. + error_behavior: + type: string + enum: + - Log + - Retry + - Disable + description: | + Specifies how to handle errors that occur during trigger execution: + - `Log`: Log the error and continue (default) + - `Retry`: Retry the trigger execution + - `Disable`: Disable the trigger after an error + default: Log + required: + - run_async + - error_behavior + ApiNodeSpec: + type: object + description: | + Optional specification for targeting specific nodes in a multi-node InfluxDB 3 Enterprise cluster. + Use this to control which node(s) should handle the cache or trigger. + properties: + node_id: + type: string + description: | + The ID of a specific node in the cluster. + If specified, the cache or trigger will only be created on this node. + node_group: + type: string + description: | + The name of a node group in the cluster. + If specified, the cache or trigger will be created on all nodes in this group. + WALPluginTestRequest: + type: object + description: | + Request body for testing a write-ahead logging (WAL) plugin. + properties: + filename: + type: string + description: | + The path and filename of the plugin to test. + database: + type: string + description: | + The database name to use for the test. + input_lp: + type: string + description: | + Line protocol data to use as input for the test. + cache_name: + type: string + description: | + Optional name of the cache to use in the test. + input_arguments: + type: object + additionalProperties: + type: string + description: | + Optional key-value pairs of arguments to pass to the plugin. + required: + - filename + - database + - input_lp + SchedulePluginTestRequest: + type: object + description: | + Request body for testing a scheduling plugin. + properties: + filename: + type: string + description: | + The path and filename of the plugin to test. + database: + type: string + description: | + The database name to use for the test. + schedule: + type: string + description: | + Optional schedule specification in cron or interval format. + cache_name: + type: string + description: | + Optional name of the cache to use in the test. + input_arguments: + type: object + additionalProperties: + type: string + description: | + Optional key-value pairs of arguments to pass to the plugin. + required: + - filename + - database + PluginFileRequest: + type: object + description: | + Request body for updating a plugin file. + properties: + plugin_name: + type: string + description: | + The name of the plugin file to update. + content: + type: string + description: | + The content of the plugin file. + required: + - plugin_name + - content + PluginDirectoryRequest: + type: object + description: | + Request body for updating plugin directory with multiple files. + properties: + plugin_name: + type: string + description: | + The name of the plugin directory to update. + files: + type: array + items: + $ref: '#/components/schemas/PluginFileEntry' + description: | + List of plugin files to include in the directory. + required: + - plugin_name + - files + PluginFileEntry: + type: object + description: | + Represents a single file in a plugin directory. + properties: + filename: + type: string + description: | + The name of the file within the plugin directory. + content: + type: string + description: | + The content of the file. + required: + - filename + - content ShowDatabasesResponse: type: object properties: