write-aql

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Pre-requisites

前置条件

Set up Holistics MCP

完成Holistics MCP的设置

Writing AQL

编写AQL

Always use
```
generate_aql
```
tool to write AQLs instead of writing yourself. It can understand the question well and write accurate queries.
In your natural language query:
- Provide all relevant data context (e.g. sample data, past errors) to improve the tool's accuracy and relevance.
- Quote filter values if (and only if) you know the exact values to filter (e.g. "Vietnam", "VN",
```
England
```
  ).
Always leverage previous tool call results as reference resources:
- This enables reuse of existing metric/measure definitions rather than regenerating them from scratch.
- Even partially relevant AQLs are valuable — they may contain reusable measures, metrics, or filters that apply to the new query.
When working with unknown data structures (such as structs, JSONs, or ambiguous fields like "settings", "configs"), you CANNOT simply ask
```
generate_aql
```
to query them, and NEVER assume or guess their properties and structures. Otherwise,
```
generate_aql
```
may use INACCURATE or NON-EXISTING properties. In this case, run one query to preview and inspect the data structure first, then write another query for the actual answer.
Example recommended workflow:
- User question: List users who have spell check enabled
- Step 1:
```
generate_aql
```
  : List 10 latest users with their settings
- Step 2:
```
execute_aql
```
  and check the result for data shape of user settings
- Step 3:
```
generate_aql
```
  : List users who have spell check enabled (by checking their settings). Example of
```
users.settings
```
  :
```
{"enable_spell_check": true, "theme": 3}
```
  - NOTE: ALWAYS provide the data schema or example if it's not already available in dataset. It is MORE USEFUL than only providing the json path.
- Step 4:
```
execute_aql
```
  and provide answer

始终使用
```
generate_aql
```
工具编写AQL，不要自行编写。它可以很好地理解问题并生成准确的查询。
编写自然语言查询时：
- 提供所有相关数据上下文（例如示例数据、过往错误）以提升工具的准确性和相关性。
- 当且仅当你明确知道要过滤的精确值时，才给过滤值加引号（例如"Vietnam"、"VN"、
```
England
```
  ）。
始终利用过往的工具调用结果作为参考资源：
- 这样可以复用现有指标/度量定义，无需从零开始重新生成。
- 即使是部分相关的AQL也很有价值——它们可能包含适用于新查询的可复用度量、指标或过滤器。
处理未知数据结构（比如结构体、JSON，或者像"settings"、"configs"这类含义模糊的字段）时，不能直接要求
```
generate_aql
```
查询它们，绝对不要假设或猜测其属性和结构。否则
```
generate_aql
```
可能会使用不准确或不存在的属性。这种情况下，先运行一次查询预览并检查数据结构，再编写另一个查询获取实际答案。
推荐的工作流示例：
- 用户问题：列出开启了拼写检查的用户
- 步骤1：调用
```
generate_aql
```
  ：列出10个最新用户及其设置信息
- 步骤2：调用
```
execute_aql
```
  ，查看结果中用户设置的数据结构
- 步骤3：调用
```
generate_aql
```
  ：列出开启了拼写检查的用户（通过检查用户设置实现）。
```
users.settings
```
  示例：
```
{"enable_spell_check": true, "theme": 3}
```
  - 注意：如果数据集中尚未提供数据 schema 或示例，请务必提供相关内容，这比仅提供JSON路径有用得多。
- 步骤4：调用
```
execute_aql
```
  并给出答案

Tool:

generate_aql

工具：

generate_aql

In your natural language query, do NOT put filter values in quotes unless you are absolutely certain the filter values are exactly accurate. If you quote uncertain filter values, it can result in wrong filtering due to case sensitivity and typos.
AQL does NOT have visualization features such as "highlight", "% format", "color", "column chart", but Viz AML DOES. => You MUST OMIT the visual stuff (like "highlight" or "color") from the
```
query
```
for
```
execute_aql
```
, and provide them to
```
generate_viz
```
INSTEAD.

编写自然语言查询时，除非你完全确定过滤值完全准确，否则不要给过滤值加引号。如果给不确定的过滤值加引号，可能会因为大小写敏感和拼写错误导致过滤结果出错。
AQL没有「高亮」、「百分比格式」、「颜色」、「柱状图」等可视化功能，这类功能属于Viz AML。=> 你必须在
```
execute_aql
```
的
```
query
```
中省略可视化相关内容（比如「高亮」或「颜色」），转而将这类内容提供给
```
generate_viz
```
。

Tool:

execute_aql

工具：

execute_aql

IMPORTANT: Prefer visualizations (using
```
generate_viz
```
+
```
execute_viz
```
) to plain tables (using
```
execute_aql
```
) whenever appropriate. E.g. always use
```
generate_viz
```
+
```
execute_viz
```
for Cohort Retention because otherwise it would be very hard for the user to read the plain data table.
Always try to provide a summary with highlightable data/numbers (or even short insights) for the result. But do NOT repeat the result in your answer.
Remember that
```
execute_aql
```
tool shows the AQL and its result directly to the user. You should not repeat the AQL in your answer.
If the AQL comes from past conversations, ALWAYS mention the past conversations in your final answer.

重要提示：只要场景合适，优先使用可视化方案（
```
generate_viz
```
+
```
execute_viz
```
）而非纯表格方案（
```
execute_aql
```
）。例如查询群组留存时始终使用
```
generate_viz
```
+
```
execute_viz
```
，否则用户很难读懂纯数据表格。
始终尝试为结果提供带有可高亮数据/数字的总结（甚至是简短洞察），但不要在回答中重复罗列结果内容。
请记住
```
execute_aql
```
工具会直接向用户展示AQL及其结果，你无需在回答中重复AQL内容。
如果AQL来自过往对话，请务必在最终回答中提及对应的过往对话。

write-aql

Original

Translation

Pre-requisites

前置条件

Writing AQL

编写AQL

Tool:
`generate_aql`

工具：
`generate_aql`

Tool:
`execute_aql`

工具：
`execute_aql`

Related skills

相关技能

write-aql

Original

Translation

Pre-requisites

前置条件

Writing AQL

编写AQL

Tool: generate_aql

工具：generate_aql

Tool: execute_aql

工具：execute_aql

Related skills

相关技能

Tool:
`generate_aql`

工具：
`generate_aql`

Tool:
`execute_aql`

工具：
`execute_aql`