Personalizar gráficos no Snowflake Intelligence¶

Visão geral¶

A personalização funciona em dois níveis:

• Nível do agente: Aplica-se a todos os gráficos em todas as exibições semânticas associadas ao agente. Use este para padrões globais, como cores e fontes da marca.

• Nível da exibição semântica: Aplica-se somente aos gráficos gerados a partir dessa exibição semântica específica. Use este para regras específicas de coluna e preferências de tipo de gráfico específicas do domínio.

Em cada nível, dois mecanismos estão disponíveis:

• vega_template: Uma especificação JSON do`Vega-Lite <https://vega.github.io/vega-lite/>`_ parcial que é mesclada deterministicamente em todos os gráficos gerados. Use isso para tudo o que deve sempre ser aplicado.

• Instruções em texto livre: Orientações em linguagem natural inseridas no prompt de geração do gráfico. OLLM se esforça ao máximo para segui-las, mas não há garantia de que elas serão seguidas.

Personalização no nível do agente¶

Adicione um bloco <chart_customization> dentro de instructions.orchestration na configuração do seu agente. Você pode combinar temas de fonte e uma paleta padrão global:

<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>

Use o nível do agente para:

• Paleta de cores da marca

• Tema visual padrão (fontes, plano de fundo)

• Preferências de estilo entre domínios

• Padrões de formatação de números ou moedas

Evite mapeamentos de cores específicos de coluna no nível do agente. Os nomes das colunas diferem entre as exibições semânticas e são ignorados silenciosamente quando não encontrados.

Personalização no nível da exibição semântica¶

Adicione um bloco <chart_customization> dentro do campo module_custom_instructions.sql_generation do seu arquivo YAML de exibição semântica. Esse campo tem precedência sobre o campo custom_instructions legado quando ambos estão definidos.

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:
  ...

Use o nível da exibição semântica para:

• Mapeamentos de cores por coluna

• Regras de tipo de gráfico específicas do domínio

• Formatação específica da métrica

• Substituição de padrões no nível do agente

Use com cautela: os modelos afetam todos os gráficos¶

vega_template é mesclado em todos os gráficos gerados nesse nível. Não há filtragem por pergunta ou por tipo de gráfico. Se você adicionar uma substituição encoding.y no nível do agente, ela se aplicará a gráficos de barras, gráficos de linhas, gráficos de dispersão e gráficos de pizza.

Antes de adicionar um modelo, considere:

• Escopo: Os modelos no nível do agente afetam todos os gráficos em todas as exibições semânticas. Prefira o nível de exibição semântica quando uma regra for específica para um domínio ou conjunto de dados.

• Codificações curinga: Uma codificação de modelo que omite field (por exemplo, "y": {"axis": {"format": "..."}}) se aplica ao eixo y de todos os gráficos, independentemente da coluna plotada. Use field para fixá-lo a uma coluna específica quando a exibição semântica for conhecida.

• Substituições de marca: Definir "mark": "line" no nível do agente força todos os gráficos a serem uma linha, incluindo aqueles em que o LLM escolheria corretamente um gráfico de barras ou de pizza. Substitua mark apenas no nível da exibição semântica em que você tem conhecimento de domínio sobre os dados.

• Matrizes de transformação: Uma transformação calculate no modelo (por exemplo, _color) é injetada na matriz transform de cada gráfico. Se os dados não contiverem a coluna referenciada, o Vega-Lite produz silenciosamente valores null para o campo calculado.

Em caso de dúvida, comece no nível da exibição semântica e promova para o nível do agente somente após confirmar que a regra é segura para todos os gráficos.

Para validar um modelo antes de implantá-lo, cole uma especificação de gráfico representativa (com seu vega_template já mesclado) no Vega Editor. O editor exibe avisos e erros em tempo real no console. Um modelo válido não deve gerar avisos. Problemas comuns detectados dessa forma: nomes de propriedades inválidos, incompatibilidades de tipo, expressões calculate inacessíveis e erros de configuração de escala.

Fontes¶

As configurações de fonte são controladas pelo bloco config em vega_template. Todas as propriedades de fonte são aplicadas globalmente ao gráfico e afetam todos os gráficos gerados, independentemente dos dados.

{
  "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" }
  }
}

Propriedades comuns da fonte config:

Você também pode definir uma cor background global ​​junto com as fontes:

{
  "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" }
  }
}

Cores¶

<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" }
}

Desativando o estilo do Snowsight¶

Por padrão, o Snowflake Intelligence aplica ajustes de tema da UI do Snowsight sobre o gráfico gerado. Para desativar e renderizar o gráfico exatamente como especificado em vega_template, defina ui-merge como "none" em usermeta:

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

Isso é útil quando você deseja controle completo sobre a saída visual, por exemplo, ao aplicar um tema de marca personalizado, e não deseja que o Snowsight substitua cores, fontes ou planos de fundo.

Formatação de números e moedas (experimental)¶

É possível formatar os rótulos dos eixos e das legendas usando ` cadeias de caracteres de formato D3 <https://d3js.org/d3-format>`_ por meio de vega_template. Isso é útil para garantir a consistência dos símbolos de moeda, casas decimais ou sufixos SI em todos os gráficos.

Defina axis.format para eixos quantitativos (x, y) e legend.format para legendas de cor/tamanho:

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

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

Cadeias de caracteres de formato D3 comuns:

Para aplicar a formatação a todos os canais quantitativos no nível do agente (sem saber o nome específico da coluna):

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

Use "merge": "extend" para que o formato seja adicionado apenas aos canais que o LLM já preencheu, sem sobrescrever as configurações de field ou type.

Modos de mesclagem¶

Controle como o vega_template interage com o gráfico gerado pelo LLM definindo "usermeta": {"merge": "<mode>"} dentro do modelo.

Regras que se aplicam a ambos os modos:

• O bloco data nunca é sobrescrito.

• As substituições de codificação se aplicam somente quando o field do modelo corresponde ao field do gráfico ou o modelo omite o field.

• Após a mesclagem, as entradas de domínio não presentes nos dados reais são removidas automaticamente.

Exemplo: forçar um gráfico de linhas

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