cadence sql

好的！关于 Cadence SQL（用于查询 Uber Cadence 工作流执行历史），以下是用中文进行的详细解释：

核心概念

目的与用途：
- Cadence SQL 主要用于查询 工作流（Workflow） 和 活动（Activity） 的执行历史记录信息。
- 它允许你根据各种条件（如工作流ID、类型、状态、开始/结束时间、自定义搜索属性等）搜索和筛选工作流执行。
- 常用于：
  - 监控工作流执行状态（如找出所有失败的工作流）。
  - 调试问题（如查找特定时间段内未完成的工作流）。
  - 生成报告（如统计不同类型工作流的执行耗时）。
  - 基于自定义属性（如客户ID、订单号）查找相关执行。
数据来源（可见性存储 - Visibility Store）：
- Cadence SQL 查询的数据存储在 Cadence 的 可见性存储 中。
- 可见性存储是一个独立的数据库（通常是 Elasticsearch, Cassandra, SQL/MySQL/PostgreSQL），专门设计用于高效地索引和查询工作流执行的摘要信息（元数据），而不是完整的执行历史事件。
- 注意： 它不是直接查询 Cadence 的持久化历史存储（History Store），后者存储了完整的、不可变的执行事件序列，用于执行引擎的重放。
与标准 SQL 的关系：
- Cadence SQL 不是标准的 ANSI SQL。它是一套特定于 Cadence 的查询语法和语义。
- 其语法结构与标准 SQL 的 SELECT ... FROM ... WHERE ... 非常相似，便于学习和使用。
- 但它只支持查询（SELECT），不支持数据操作（INSERT, UPDATE, DELETE, CREATE TABLE 等）。
- 查询的目标是“虚拟”的表视图（executions），代表工作流执行记录集合。

关键组成部分（语法结构）

一个典型的 Cadence SQL 查询如下：

SELECT <字段列表> FROM executions
WHERE <过滤条件>
ORDER BY <排序字段> [ASC|DESC]
LIMIT <最大结果数>;

SELECT <字段列表>：
- 指定要返回哪些列的信息。
- 常用字段：
  - Execution: 工作流执行的标识符（Workflow ID + Run ID）。
  - WorkflowID: 工作流实例的唯一标识符。
  - RunID: 工作流某次运行的唯一标识符（一个 WorkflowID 可以有多个 RunID）。
  - WorkflowType: 工作流类型的名称。
  - StartTime: 工作流开始执行的时间戳。
  - CloseTime: 工作流完成（成功、失败、取消、超时或终止）的时间戳。
  - Status: 工作流的最终状态（Completed, Failed, Canceled, Terminated, TimedOut, ContinuedAsNew, Running）。
  - HistoryLength: 历史事件的总数。
  - ExecutionTime: 工作流首次调度的实际时间。
  - Memo: 启动工作流时附加的任意键值对信息（通常是序列化的 JSON）。
  - TaskQueue: 工作流任务队列的名称。
  - Search Attributes： 这是关键！自定义搜索属性（如 CustomIntField, CustomKeywordField, CustomTextField, CustomDatetimeField, CustomDoubleField）。你可以在工作流代码中设置这些属性，然后基于它们高效过滤。
  - IsCron: 是否是 Cron（定时）工作流。
  - ParentExecution: 父工作流执行的标识符（如果存在）。
FROM executions：
- 固定写法。这表示查询的是工作流执行记录的视图。你不需要也不能更改这个表名。
WHERE <过滤条件>：（最重要！）
- 使用逻辑运算符（AND, OR, NOT）和比较运算符（=, !=, >, <, >=, <=, IN (...), LIKE, BETWEEN ... AND ... ）构建查询条件。
- 过滤状态和时间是最常见的：
```
WHERE Status = 'Failed'
WHERE CloseTime BETWEEN '2023-10-01T00:00:00Z' AND '2023-10-31T23:59:59Z'
WHERE StartTime > NOW() - INTERVAL '1 HOUR' AND Status = 'Running' -- 查找过去1小时启动且仍在运行的
```
- 基于 Workflow ID/Run ID/Type:
```
WHERE WorkflowID = 'my-order-processing-12345'
WHERE RunID = 'd1e6a5c0-1234-5678-9012-abcdef123456'
WHERE WorkflowType = 'OrderProcessingWorkflow'
```
- 基于自定义搜索属性 (Search Attributes)： 这是 Cadence SQL 强大之处。确保属性已定义并在工作流代码中设置。
  - CustomKeywordField (用于精确匹配，如订单号、用户ID):
```
WHERE CustomKeywordField = 'ORD-98765'
WHERE CustomKeywordField IN ('USER123', 'USER456')
```
  - CustomIntField / CustomDoubleField (用于数值范围):
```
WHERE CustomIntField >= 100 AND CustomIntField < 200
```
  - CustomDatetimeField (用于时间范围):
```
WHERE CustomDatetimeField BETWEEN '2023-10-15T00:00:00Z' AND '2023-10-15T23:59:59Z'
```
  - CustomTextField (用于全文搜索关键词，效率低于 Keyword，支持 LIKE 或 ES/KW 的全文索引):
```
WHERE CustomTextField LIKE '%error%' -- 谨慎使用，可能慢
```
- 基于 Memo (需要反序列化 JSON 字段，性能较差，尽量避免在 WHERE 中深度查询 Memo):
  - Cadence CLI/TUI 可能提供辅助函数（如 json_extract），但在原始 SQL 中通常通过 LIKE 进行粗略匹配：
```
WHERE Memo LIKE '%"customerId":"CUST789"%'
```

ORDER BY <字段> [ASC|DESC]：

对结果集进行排序。

常用于按时间排序：

ORDER BY StartTime DESC -- 最近开始的排前面
ORDER BY CloseTime ASC -- 最早结束的排前面

LIMIT <N>：
- 限制返回结果的最大数量。非常重要！ 避免查询返回海量数据导致性能问题或 UI/命令行卡死。通常加上 LIMIT 100 或 LIMIT 1000。

使用方式

Cadence CLI (命令行工具)：

最常用的方式。使用 cadence-cli 的 --query 参数：

cadence-cli workflow list --query "SELECT WorkflowID, RunID, StartTime, CloseTime, Status FROM executions WHERE WorkflowType = 'MyWorkflow' AND Status = 'Failed' AND StartTime > '2023-10-20T00:00:00Z' ORDER BY StartTime DESC LIMIT 100"

使用 cadence-cli 的交互式模式 (cadence-cli --do <domain_name> workflow query)。

Cadence Web UI (如果部署并启用)：
- 通常提供一个查询输入框，允许你直接输入 Cadence SQL 进行搜索和过滤工作流列表。
Cadence TUI (Terminal UI)：
- 类似 Cadence Web UI，但在终端中运行，也提供查询输入功能。
通过 Cadence Client SDK (高级)：
- 可以使用 Cadence 客户端库（如 Go, Java）中的 ListWorkflow 或 ScanWorkflow API，传入 Cadence SQL 字符串作为查询条件来编程获取结果。

重要提示与最佳实践

性能影响： 复杂的查询，尤其是涉及全文搜索 (LIKE)、大范围时间扫描或未利用索引的过滤条件，可能会很慢且对可见性存储造成压力。尽量使用高效的搜索属性（特别是 Keyword, Int, Double, Datetime）。
定义搜索属性 (Search Attributes): 要在查询中高效使用自定义属性，必须在 Cadence 集群中预先定义该属性的名称和类型（通过 cadence-cli adm 或运维 API），并在启动工作流时在代码中设置该属性值。
善用 LIMIT: 总是尽量加上 LIMIT，尤其是在命令行或不确定结果集大小时。
理解状态： Status='Running' 表示工作流仍在执行中，没有 CloseTime。查询运行中的工作流通常使用 StartTime 和其他条件。
时间格式： 时间戳通常使用 ISO 8601 格式 (YYYY-MM-DDThh:mm:ssZ)。NOW() 是一个有用的函数，表示当前时间。
可见性存储配置： 查询能力取决于后端可见性存储的类型（ES/Cass/SQL）及其配置（索引、schema）。确保存储正确设置和维护。
权限： 执行查询需要相应的域（Domain）访问权限。
JSON 查询限制： 直接查询 Memo 或自定义属性中的复杂 JSON 结构通常效率低下且功能有限。尽量将需要查询的关键信息提取出来作为独立的搜索属性。

示例查询

查找过去 24 小时内失败的所有工作流：

SELECT WorkflowID, RunID, WorkflowType, StartTime, CloseTime FROM executions
WHERE Status = 'Failed'
AND StartTime > NOW() - INTERVAL '24 HOUR'
ORDER BY StartTime DESC
LIMIT 1000;

查找特定客户 (CustomerID=cust-abc123) 的所有 OrderProcessingWorkflow（假设 CustomerID 被定义为 CustomKeywordField）：

SELECT WorkflowID, RunID, StartTime, Status FROM executions
WHERE WorkflowType = 'OrderProcessingWorkflow'
AND CustomKeywordField = 'cust-abc123'
ORDER BY StartTime DESC;

查找所有超过 1 小时仍在运行的 ReportGenerationWorkflow：

SELECT WorkflowID, RunID, StartTime FROM executions
WHERE WorkflowType = 'ReportGenerationWorkflow'
AND Status = 'Running'
AND StartTime < NOW() - INTERVAL '1 HOUR'
LIMIT 50;

查找特定日期范围 (2023-10-01 到 2023-10-15) 内完成的、处理金额大于 1000 的订单工作流（假设 OrderAmount 是 CustomDoubleField）：

SELECT WorkflowID, RunID, StartTime, CloseTime, CustomDoubleField AS OrderAmount FROM executions
WHERE WorkflowType = 'OrderWorkflow'
AND Status = 'Completed'
AND CloseTime BETWEEN '2023-10-01T00:00:00Z' AND '2023-10-15T23:59:59Z'
AND CustomDoubleField > 1000.0
ORDER BY CustomDoubleField DESC
LIMIT 200;

希望这份详细的中文解释能帮助你理解和使用 Cadence SQL！如果你有具体的查询场景或遇到问题，可以提出来讨论。