在 Snowflake Intelligence 中自定义图表¶

概述¶

自定义在两个级别上进行：

• 代理级别：应用于附加到代理的每个语义视图的所有图表。用于全局默认值，例如品牌颜色和字体。

• 语义视图级别：仅应用于从该特定语义视图生成的图表。用于特定于列的规则和特定于域的图表类型首选项。

每个级别都有两种机制可用：

• vega_template：部分 Vega-Lite (https://vega.github.io/vega-lite/) JSON 规范，确定性地合并到每个生成的图表中。用于任何必须始终应用的内容。

• 自由文本说明：自然语言指导，注入到图表生成提示中。LLM 会尽力遵循，但无法完全保证。

代理级别自定义¶

在代理配置中的 instructions.orchestration 内添加 <chart_customization> 块。您可以将字体主题和全局默认色板结合使用：

<chart_customization>
Prefer horizontal bar charts for ranked data.
vega_template:
{
  "background": "antiquewhite",
  "config": {
    "title":  { "font": "monospace", "fontStyle": "italic", "fontSize": 20, "fontWeight": "lighter" },
    "axis":   { "labelFont": "monospace", "titleFont": "monospace", "titleFontSize": 15, "labelFontSize": 10 },
    "header": { "labelFont": "monospace", "titleFont": "monospace", "labelFontSize": 10 },
    "legend": { "labelFont": "monospace", "titleFont": "monospace", "titleFontSize": 18, "labelFontSize": 15 },
    "mark":   { "font": "monospace" }
  }
}
</chart_customization>

代理级别适用于：

• 品牌色板

• 默认视觉主题（字体、背景）

• 跨域样式首选项

• 数字或货币格式的默认值

避免在代理级别进行特定于列的颜色映射。列名在不同的语义视图之间各不相同，如果找不到对应的列名，设置将被静默忽略。

语义视图级别自定义¶

在您的语义视图 YAML 的 module_custom_instructions.sql_generation 字段内添加 <chart_customization> 块。当两个字段同时设置时，该字段的优先级高于旧有的 custom_instructions 字段。

CREATE OR REPLACE SEMANTIC VIEW my_db.my_schema.my_view
  FROM @my_stage/semantic_view.yaml;

# semantic_view.yaml
name: my_view
module_custom_instructions:
  sql_generation: |
    <chart_customization>
    Always use a line chart for time series data.
    vega_template:
    {
      "transform": [
        {
          "calculate": "datum.CATEGORY === 'Furniture' ? '#4e79a7' : datum.CATEGORY === 'Technology' ? '#f28e2b' : datum.CATEGORY === 'Office Supplies' ? '#e15759' : ''",
          "as": "_color"
        }
      ],
      "encoding": {
        "color": { "field": "CATEGORY", "type": "nominal", "scale": { "range": { "field": "_color" } } }
      }
    }
    </chart_customization>
tables:
  ...

语义视图级别适用于：

• 针对特定列的颜色映射

• 特定于域的图表类型规则

• 特定于指标的格式

• 替换代理级别的默认值

谨慎使用：模板会影响每个图表¶

vega_template 合并到该级别生成的 每个图表。不存在基于单个问题或单个图表类型的筛选机制。如果您在代理级别添加了 encoding.y 替换，它将同样应用于条形图、折线图、散点图和饼图。

在添加模板之前，请考虑：

• 范围：代理级别的模板会影响所有语义视图中的所有图表。当规则特定于一个域或数据集时，优先选择语义视图级别。

• 通配符编码：省略了 field 的模板编码（例如，"y": {"axis": {"format": "..."}}）会应用于每个图表的 y 轴，无论绘制的是哪一列。当语义视图已知时，使用 field 将其固定到特定列。

• 标记替换：在代理级别设置 "mark": "line" 会强制每个图表变为折线图，即使 LLM 本来会正确选择条形图或饼图。仅在您对数据拥有领域知识的语义视图级别替换 mark。

• 转换数组：模板中的 calculate 转换（例如 _color）被注入到每个图表的 transform 数组。如果数据不包含引用的列，Vega-Lite 会静默地生成该计算字段的 null 值。

如有疑问，请从语义视图级别开始，只有在确认规则对所有图表都是安全的后，才提升到代理级别。

要在部署模板之前对其进行验证，请将具有代表性的图表规范（已合并您的 vega_template）粘贴到 Vega Editor (https://vega.github.io/editor) 中。编辑器在控制台中显示实时警告和错误。有效的模板不应产生警告。通过这种方式可以捕获的常见问题包括：属性名称无效、类型不匹配、无法访问的 calculate 表达式和比例配置错误。

字体¶

字体设置通过 vega_template 中的 config 块控制。所有字体属性都全局应用于图表，会影响生成的每个图表，无论数据为何。

{
  "config": {
    "title":  { "font": "serif", "fontSize": 20, "fontWeight": "bold", "fontStyle": "italic" },
    "axis":   { "labelFont": "monospace", "titleFont": "monospace", "labelFontSize": 11, "titleFontSize": 13 },
    "header": { "labelFont": "serif", "titleFont": "serif", "labelFontSize": 11 },
    "legend": { "labelFont": "serif", "titleFont": "serif", "labelFontSize": 12, "titleFontSize": 13 },
    "mark":   { "font": "serif" }
  }
}

常见的 config 字体属性：

您还可以与字体一起设置全局 background 颜色：

{
  "background": "#f9f9f9",
  "config": {
    "title":  { "font": "monospace", "fontStyle": "italic", "fontSize": 20, "fontWeight": "lighter" },
    "axis":   { "labelFont": "monospace", "titleFont": "monospace", "titleFontSize": 15, "labelFontSize": 10 },
    "header": { "labelFont": "monospace", "titleFont": "monospace", "labelFontSize": 10 },
    "legend": { "labelFont": "monospace", "titleFont": "monospace", "titleFontSize": 18, "labelFontSize": 15 },
    "mark":   { "font": "monospace" }
  }
}

颜色¶

<chart_customization>
Color Active status green, Inactive status red, and Pending status yellow.
</chart_customization>

{
  "transform": [
    {
      "calculate": "datum.STATUS === 'Active' ? '#22c55e' : datum.STATUS === 'Inactive' ? '#ef4444' : datum.STATUS === 'Pending' ? '#eab308' : ''",
      "as": "_color"
    }
  ],
  "encoding": {
    "color": {
      "field": "STATUS",
      "type": "nominal",
      "scale": { "range": { "field": "_color" } }
    }
  }
}

{
  "encoding": {
    "color": {
      "scale": {
        "domain": ["Furniture", "Technology", "Office Supplies"],
        "range":  ["#4e79a7", "#f28e2b", "#e15759"],
        "scheme": "tableau10"
      }
    }
  },
  "usermeta": { "merge": "extend" }
}

禁用 Snowsight 样式¶

默认情况下，Snowflake Intelligence 会在生成的图表之上应用 Snowsight UI 主题调整。要选择退出并完全按照 vega_template 中指定的方式渲染图表，请在 usermeta 中将 ui-merge 设置为 "none"。

{
  "usermeta": { "ui-merge": "none" }
}

当您希望完全控制视觉输出时（例如，应用自定义品牌主题且不希望 Snowsight 替换颜色、字体或背景时），这非常有用。

数字和货币格式化（实验性）¶

坐标轴和图例标签可以通过 vega_template 使用 D3 格式字符串 (https://d3js.org/d3-format) 进行格式化。这对于在所有图表中强制执行统一的货币符号、小数位数或 SI 后缀非常有用。

为定量轴（x 、y）设置 axis.format，为颜色/尺寸图例设置 legend.format：

{
  "encoding": {
    "y": { "axis": { "format": "$,.0f" } }
  }
}

{
  "encoding": {
    "y": { "type": "quantitative", "axis": { "format": "$,.0f" } }
  }
}

常见的 D3 格式字符串：

要在代理级别将格式化应用于所有定量通道（无需知道具体的列名），请执行以下操作：

{
  "encoding": {
    "y": { "axis": { "format": "$,.0f" } },
    "x": { "axis": { "format": "$,.0f" } },
    "color": { "legend": { "format": "$,.0f" } }
  },
  "usermeta": { "merge": "extend" }
}

使用 "merge": "extend"，这样格式化只会添加到 LLM 已经填充的通道中，而不会覆盖它们的 field 或 type 设置。

合并模式¶

通过在模板内部设置 "usermeta": {"merge": "<mode>"}，控制 vega_template 与 LLM 生成图表的交互方式。

适用于两种模式的规则：

• data 块永远不会被覆盖。

• 仅当模板的 field 与图表的 field 匹配，或者模板省略了 field 时，编码替换才生效。

• 合并后，实际数据中不存在的域条目会自动移除。

示例：强制使用折线图

{
  "mark": "line",
  "usermeta": { "merge": "override" }
}