openapi: add investigation target purpose and optional datasource_id

api-reference/monitors.openapi.en.json

@@ -9021,6 +9021,11 @@
             ],
             "description": "Entry kind: `dashboard` opens a dashboard panel, `query` opens an Explore query. It decides whether `dashboard` or `query` must be supplied; supplying the other one is rejected."
           },
+          "purpose": {
+            "type": "string",
+            "maxLength": 512,
+            "description": "One-sentence plain text explaining what this entry helps confirm during investigation. Literal text, not a template, and not part of the alert identity. At most 512 bytes; control characters are rejected."
+          },
           "time_range": {
             "$ref": "#/components/schemas/InvestigationTimeRange",
             "description": "Window around the event time, required on every saved entry. A zero-length window is rejected; defaults belong to the editor."
@@ -9095,17 +9100,16 @@
           "datasource_id": {
             "type": "integer",
             "format": "int64",
-            "minimum": 1,
+            "minimum": 0,
             "maximum": 9007199254740991,
-            "description": "Data source the query runs against."
+            "description": "Data source the query runs against. Omit (or set 0) to run on the alert event's own datasource."
           },
           "query": {
             "$ref": "#/components/schemas/DashboardQuery",
             "description": "Query payload."
           }
         },
         "required": [
-          "datasource_id",
           "query"
         ]
       },

api-reference/monitors.openapi.zh.json

@@ -9021,6 +9021,11 @@
             ],
             "description": "入口类型：`dashboard` 打开仪表盘面板，`query` 打开 Explore 查询。它决定必须提供 `dashboard` 还是 `query`，提供另一个会被拒绝。"
           },
+          "purpose": {
+            "type": "string",
+            "maxLength": 512,
+            "description": "一句话纯文本，说明该入口帮助确认什么排查意图。不是模板，也不参与告警身份计算。不超过 512 字节；不允许包含控制字符。"
+          },
           "time_range": {
             "$ref": "#/components/schemas/InvestigationTimeRange",
             "description": "事件时间前后的取数窗口，每个已保存的入口都必填。长度为 0 的窗口会被拒绝；默认值由前端编辑器提供。"
@@ -9095,17 +9100,16 @@
           "datasource_id": {
             "type": "integer",
             "format": "int64",
-            "minimum": 1,
+            "minimum": 0,
             "maximum": 9007199254740991,
-            "description": "查询所用的数据源。"
+            "description": "查询所用的数据源。省略（或填 0）表示使用告警事件自身的数据源。"
           },
           "query": {
             "$ref": "#/components/schemas/DashboardQuery",
             "description": "查询内容。"
           }
         },
         "required": [
-          "datasource_id",
           "query"
         ]
       },

api-reference/openapi.en.json

@@ -29257,6 +29257,11 @@
             ],
             "description": "Entry kind: `dashboard` opens a dashboard panel, `query` opens an Explore query. It decides whether `dashboard` or `query` must be supplied; supplying the other one is rejected."
           },
+          "purpose": {
+            "type": "string",
+            "maxLength": 512,
+            "description": "One-sentence plain text explaining what this entry helps confirm during investigation. Literal text, not a template, and not part of the alert identity. At most 512 bytes; control characters are rejected."
+          },
           "time_range": {
             "$ref": "#/components/schemas/InvestigationTimeRange",
             "description": "Window around the event time, required on every saved entry. A zero-length window is rejected; defaults belong to the editor."
@@ -29331,17 +29336,16 @@
           "datasource_id": {
             "type": "integer",
             "format": "int64",
-            "minimum": 1,
+            "minimum": 0,
             "maximum": 9007199254740991,
-            "description": "Data source the query runs against."
+            "description": "Data source the query runs against. Omit (or set 0) to run on the alert event's own datasource."
           },
           "query": {
             "$ref": "#/components/schemas/DashboardQuery",
             "description": "Query payload."
           }
         },
         "required": [
-          "datasource_id",
           "query"
         ]
       },

api-reference/openapi.zh.json

@@ -29257,6 +29257,11 @@
             ],
             "description": "入口类型：`dashboard` 打开仪表盘面板，`query` 打开 Explore 查询。它决定必须提供 `dashboard` 还是 `query`，提供另一个会被拒绝。"
           },
+          "purpose": {
+            "type": "string",
+            "maxLength": 512,
+            "description": "一句话纯文本，说明该入口帮助确认什么排查意图。不是模板，也不参与告警身份计算。不超过 512 字节；不允许包含控制字符。"
+          },
           "time_range": {
             "$ref": "#/components/schemas/InvestigationTimeRange",
             "description": "事件时间前后的取数窗口，每个已保存的入口都必填。长度为 0 的窗口会被拒绝；默认值由前端编辑器提供。"
@@ -29331,17 +29336,16 @@
           "datasource_id": {
             "type": "integer",
             "format": "int64",
-            "minimum": 1,
+            "minimum": 0,
             "maximum": 9007199254740991,
-            "description": "查询所用的数据源。"
+            "description": "查询所用的数据源。省略（或填 0）表示使用告警事件自身的数据源。"
           },
           "query": {
             "$ref": "#/components/schemas/DashboardQuery",
             "description": "查询内容。"
           }
         },
         "required": [
-          "datasource_id",
           "query"
         ]
       },

en/developer/go-sdk.mdx

@@ -276,11 +276,11 @@ zero := inc.StartTime.IsZero()        // whether it's the unset sentinel
 <Note>
 `AlertRuleV2`'s `investigation_targets` (the same return type of `AlertRules.ReadInfoV2` / `WriteCreateV2` / `WriteUpdateV2`) changed shape as well, so callers still sending the old fields have to migrate:
 
-- The field itself is `[]InvestigationTarget`, at most 20 entries with no duplicates; on the update endpoint it is presence-based — omitting it keeps the saved configuration, sending `[]` clears it.
+- The field itself is `[]InvestigationTarget`, at most 20 entries with no duplicates; on the update endpoint it is presence-based — omitting it keeps the saved configuration, sending `[]` clears it. Each entry may carry an optional `purpose`: one-sentence plain text saying what the entry helps confirm (≤512 bytes; literal text, not a template, and not part of alert identity).
 - Each entry is a **closed tagged union**, and `Kind` decides which sub-object you supply. `dashboard` (opens a dashboard panel) requires `Dashboard`, and `query` (opens an Explore query) requires `Query`. Supplying the other one, or an unknown field, is rejected.
 - `TimeRange` (`InvestigationTimeRange`: `BeforeSeconds` and `AfterSeconds`) is required on **every** saved entry — both directions are non-negative and at least one is greater than zero.
 - The `Dashboard` entry (`DashboardInvestigationTarget`) replaces the old `VariableBindings` (keyed by dashboard variable name, with values of `{source: event_label, key: label name}`) with `Variables`: a `map[string]string` keyed by variable name whose values are literal, and may reference event labels through `{{ }}` templates (the old `InvestigationVariableBinding` type is gone). `DashboardID` and `Variables` are required and `TargetID` is optional; `DashboardID` and `TargetID` must both be canonical UUIDv7 values.
-- The `Query` entry uses `QueryInvestigationTarget`: both `DatasourceID` (the data source ID) and `Query` are required, and `Query` is a `DashboardQuery` — `Mode` is `instant`, `range`, or `window`, `Expr` is an expression in the target data source's own language that may use `{{ }}` templates, `Args` are named parameters passed through verbatim and must not contain templates, and `MinStepSeconds` is only accepted when `Mode` is `range`.
+- The `Query` entry uses `QueryInvestigationTarget`: `Query` is required and is a `DashboardQuery` — `Mode` is `instant`, `range`, or `window`, `Expr` is an expression in the target data source's own language that may use `{{ }}` templates, `Args` are named parameters passed through verbatim and must not contain templates, and `MinStepSeconds` is only accepted when `Mode` is `range`. `DatasourceID` may be omitted (or set to 0), which runs the query on the alert event's own datasource.
 </Note>
 
 ## Pagination

zh/developer/go-sdk.mdx

@@ -276,11 +276,11 @@ zero := inc.StartTime.IsZero()        // 是否为未设置哨兵
 <Note>
 同样属于 `AlertRuleV2`（`AlertRules.ReadInfoV2` / `WriteCreateV2` / `WriteUpdateV2` 的返回类型）的 `investigation_targets` 也换了形状，仍在发送旧字段的调用方需要一并改：
 
-- 字段本身是 `[]InvestigationTarget`，最多 20 项且不允许重复；更新接口按 presence 处理——省略保留原配置，传 `[]` 清空。
+- 字段本身是 `[]InvestigationTarget`，最多 20 项且不允许重复；更新接口按 presence 处理——省略保留原配置，传 `[]` 清空。每个入口可带可选的 `purpose`：一句话纯文本，说明该入口帮助确认什么排查意图（≤512 字节，不是模板，不参与告警身份）。
 - 每个入口是**封闭的 tagged union**，`Kind` 决定必须提供哪个子对象：`dashboard`（打开仪表盘面板）必须给 `Dashboard`，`query`（打开 Explore 查询）必须给 `Query`，提供另一个会被拒绝，入口内出现未知字段同样会被拒绝。
 - `TimeRange`（`InvestigationTimeRange`：`BeforeSeconds` 与 `AfterSeconds`）在**每个**已保存的入口上都必填——两个方向都非负，且至少一个大于 0。
 - `Dashboard` 入口（`DashboardInvestigationTarget`）的变量由原来的 `VariableBindings`（键为仪表盘变量名，值为 `{source: event_label, key: 标签名}`）换成 `Variables`：`map[string]string`，键为变量名、值为字面取值，可用 `{{ }}` 模板引用事件标签（旧类型 `InvestigationVariableBinding` 已不存在）。`DashboardID` 与 `Variables` 必填，`TargetID` 可选；`DashboardID` 与 `TargetID` 都必须是规范的 UUIDv7。
-- `Query` 入口用 `QueryInvestigationTarget`：`DatasourceID`（数据源 ID，必填）与 `Query`（必填）都不可省，`Query` 为 `DashboardQuery`——`Mode` 取 `instant` / `range` / `window`，`Expr` 是目标数据源原生语法的表达式且可用 `{{ }}` 模板，`Args` 是原样透传的命名参数、不允许出现模板，`MinStepSeconds` 仅在 `Mode` 为 `range` 时接受。
+- `Query` 入口用 `QueryInvestigationTarget`：`Query`（必填）为 `DashboardQuery`——`Mode` 取 `instant` / `range` / `window`，`Expr` 是目标数据源原生语法的表达式且可用 `{{ }}` 模板，`Args` 是原样透传的命名参数、不允许出现模板，`MinStepSeconds` 仅在 `Mode` 为 `range` 时接受；`DatasourceID` 可省略（或填 0），表示使用告警事件自身的数据源。
 </Note>
 
 ## 分页