Back to Details

use-existing-viz

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Pre-requisites

前置条件

  • Set up Holistics MCP
  • 配置好 Holistics MCP

Context

背景说明

  • "viz" or "viz blocks" refer to visualization blocks defined in Dashboards (.page.aml files)
  • "viz" 或 "viz blocks" 指的是在 Dashboards（.page.aml 文件）中定义的可视化块

Search for existing viz

搜索现有viz

When to search

何时搜索

  • When a user asks a data question that requires querying data, call 
    search_viz_blocks
    first to find reusable viz blocks before generating new AQL.
  • 当用户提出需要查询数据的数据问题时，在生成新的AQL之前，首先调用
    search_viz_blocks
    查找可复用的viz块。

Search strategy

搜索策略

  • Extract key concepts from the user's question as search keywords (e.g., "sale", "customer", "retention", "product category").
    • Only use keywords, not natural language sentence.
  • Consider synonyms and related business terms (e.g., "revenue" ↔ "sales", "churn" ↔ "retention").
  • If initial search returns no relevant results, try 1-2 additional searches with keyword variations then proceed to generate new AQL.
  • 从用户问题中提取核心概念作为搜索关键词（例如："sale"、"customer"、"retention"、"product category"）。
    • 仅使用关键词，不要用自然语言语句。
  • 考虑同义词和相关业务术语（例如："revenue" ↔ "sales"、"churn" ↔ "retention"）。
  • 如果初次搜索没有返回相关结果，尝试使用变体关键词再搜索1-2次，之后再生成新的AQL。

Evaluate viz blocks

评估viz块

  • Multiple viz blocks may be returned. Scan their semantics to pick the most relevant ones. For example:
    • Metrics and dimensions: Does the AQL contain the measures and breakdowns the user is asking about?
    • Grain: Does the aggregation level match (e.g., daily vs. monthly, per-customer vs. per-region)?
    • Filters: If date filters are visible in the AQL, check for obvious mismatches with the resolved date range.
  • Always inspect the AQL — don't rely on the viz block label and description alone.
  • If no viz blocks returned, proceed to generate AQL.
  • 可能会返回多个viz块。扫描它们的语义，挑选最相关的内容。例如：
    • 指标和维度：AQL是否包含用户查询的度量和拆分维度？
    • 粒度：聚合级别是否匹配（例如：每日vs每月、单客户vs单区域）？
    • 筛选条件：如果AQL中有可见的日期筛选器，检查是否与解析后的日期范围存在明显不匹配。
  • 始终检查AQL——不要只依赖viz块的标签和描述。
  • 如果没有返回viz块，直接生成AQL。

Validate and execute

验证与执行

  • If a viz block looks relevant, MUST use tool 
    validate_viz_block_relevance
    to check whether if it's truly relevant.
If validation passes: call tool 
execute_viz_block
to show to result to user. If validation fails: proceed to generate AQL (don't need to ask user for confirmation).
  • 如果某个viz块看起来相关，必须使用
    validate_viz_block_relevance
    工具检查它是否真的相关。
如果验证通过：调用
execute_viz_block
工具向用户展示结果。 如果验证不通过：直接生成AQL（无需询问用户确认）。

Decision flow

决策流程

  1. Search for viz blocks.
  2. Evaluate viz blocks by metadata/AQL.
  3. Evaluate promising viz blocks relevance.
  4. If valid → present to user.
  5. If partially valid -> proceed with generate AQL with the viz block as a reference resource.
  6. If invalid → proceed with generate AQL.
  1. 搜索viz块。
  2. 通过元数据/AQL评估viz块。
  3. 评估有潜力的viz块的相关性。
  4. 如果有效 → 展示给用户。
  5. 如果部分有效 -> 以该viz块作为参考资源生成AQL。
  6. 如果无效 → 直接生成AQL。