O que é o Cortex Analyst?
O Cortex Analyst é o serviço totalmente gerenciado de text-to-SQL do Snowflake, que permite que usuários de negócio façam perguntas em linguagem natural e obtenham respostas em SQL sem escrever uma única query. Dá para interagir com ele de duas formas: pelo Snowflake Intelligence (a interface de agente de IA nativa do Snowflake) ou via API REST, integrando-o a aplicações próprias (pense em apps Streamlit, bots no Slack, no Microsoft Teams, interfaces de chat web personalizadas ou qualquer outra ferramenta de negócio que sua equipe já usa). Ele é movido por large language models, tendo Claude Sonnet, Mistral Large e Llama como modelos principais, e usa modelos semânticos para entender o contexto do seu negócio.
Este guia traz uma visão geral de alto nível sobre o uso do Cortex Analyst e, na sequência, mostra como monitorar e controlar seus custos.
Como o Cortex Analyst funciona?
O Cortex Analyst converte perguntas em linguagem natural em queries SQL precisas, combinando large language models e modelos semânticos. O modelo semântico faz a ponte entre a terminologia de negócio e os schemas do banco de dados, fornecendo o contexto que ajuda o LLM a gerar o SQL correto.
Criando modelos semânticos
Você tem duas opções para criar modelos semânticos:
- Usar o assistente do Snowsight: acesse AI & ML " Cortex Analyst no Snowsight e use a configuração guiada para criar uma visão semântica. O assistente conduz você pela seleção das tabelas, definição de dimensões e métricas e inclusão de perguntas de exemplo. É a forma mais fácil de começar.
- Fazer upload de um arquivo YAML para um stage: se preferir definir o modelo semântico como código, crie um arquivo YAML seguindo a especificação do modelo semântico e envie-o para um stage do Snowflake.
As duas abordagens funcionam com o Cortex Analyst. O assistente cria uma visão semântica (um objeto no nível do schema), enquanto a abordagem YAML armazena o arquivo do modelo em um stage.
Usando o Cortex Analyst
Quando seu modelo semântico estiver pronto, libere o acesso aos usuários:
-- Conceda a role CORTEX_USER aos usuários que precisam de acesso
GRANT DATABASE ROLE SNOWFLAKE.CORTEX_USER TO ROLE analyst_role;
Depois, na sua aplicação, basta chamar a API do Cortex Analyst com uma pergunta em linguagem natural:
1import requests
2import json
3
4response = requests.post(
5 f"https://{account}.snowflakecomputing.com/api/v2/cortex/analyst/message",
6 headers={
7 "Authorization": f"Bearer {token}",
8 "Content-Type": "application/json"
9 },
10 json={
11 "messages": [{\
\
12 "role": "user",\
\
13 "content": [{\
\
14 "type": "text",\
\
15 "text": "Quais foram nossos 5 principais produtos por receita no último trimestre?"\
```\
\
Expandir código\
\
O Cortex Analyst suporta conversas com múltiplos turnos, permitindo que os usuários façam perguntas de acompanhamento que se baseiam em consultas anteriores.\
\
Se quiser usar o Cortex Analyst no Snowflake Intelligence, também vai precisar criar um agente. Falamos sobre isso [aqui](/blog/snowflake-intelligence-overview-pricing-cost-monitoring).\
\
Como funciona o preço do Cortex Analyst?\
O Cortex Analyst usa precificação por mensagem, não por token. Apenas respostas HTTP 200 bem-sucedidas são cobradas, e o custo é o mesmo independentemente da quantidade de tokens em cada mensagem. Segundo a tabela de consumo de serviços do Snowflake, cada mensagem tem um custo fixo em créditos. Atualmente, são 6,7 créditos a cada 100 mensagens.
Os dois principais geradores de custo:
\
- Cada consulta em linguagem natural = 1 mensagem: pergunte "Qual é minha receita?" e pronto, é uma mensagem cobrada.\
- A US$ 3 por crédito, 10 perguntas custariam US$ 2. Parece que isso pode escalar rápido, mas é preciso pesar o valor de negócio gerado. O objetivo nem sempre é minimizar o gasto com Snowflake, e sim maximizar o valor de negócio.\
- Custos de warehouse para execução do SQL: o custo da mensagem cobre apenas a geração de text-to-SQL pela IA. Custos adicionais de compute do warehouse se aplicam quando o SQL gerado é executado.
\
Como monitorar o uso do Cortex Analyst\
O Snowflake oferece uma visão principal para acompanhar os custos do Cortex Analyst:
CORTEX_ANALYST_USAGE_HISTORY: os dados são agregados em incrementos de uma hora e, por isso, não contêm o ID da query.
Essa visão mostra o consumo de créditos do Cortex Analyst, agregado em janelas de uma hora. Inclui o número de mensagens e os créditos consumidos por usuário.
\
1-- Veja o uso diário do Cortex Analyst por usuário nos últimos 30 dias\
\
2SELECT\
\
3 DATE_TRUNC('day', START_TIME) AS usage_date,\
\
4 USERNAME,\
\
5 SUM(REQUEST_COUNT) AS total_messages,\
\
6 SUM(CREDITS) AS total_credits\
\
7FROM SNOWFLAKE.ACCOUNT_USAGE.CORTEX_ANALYST_USAGE_HISTORY\
\
8WHERE START_TIME >= DATEADD('day', -30, CURRENT_TIMESTAMP())\
\
9GROUP BY 1, 2\
\
10ORDER BY total_credits DESC;\
```\
\
A visão inclui START\_TIME, END\_TIME, REQUEST\_COUNT (número de mensagens), CREDITS consumidos e USERNAME. Isso te dá visibilidade por usuário sobre quem está puxando os custos do Cortex Analyst. A visão METERING\_HISTORY pode ser filtrada com `WHERE SERVICE_TYPE = 'AI_SERVICES'`, mas você pode acabar capturando mais do que apenas o custo do Cortex Analyst por ali.\
\
### Monitore os custos de warehouse da execução do SQL\
\
Aqui você tem algumas opções: pode usar um warehouse, usuário ou role dedicado, ou marcar as queries iniciadas pelo seu app Cortex Analyst. A ideia é seguir a mesma abordagem que você já usa para atribuição de queries, o que fizer mais sentido para a sua organização.\
\
Boas práticas e recomendações ao usar o Cortex Analyst\
\
Configure alertas, não só dashboards\
As queries de monitoramento acima não servem para nada se ninguém as executar. Para qualquer coisa que você queira monitorar no Snowflake, é possível encapsular o SQL em uma task agendada com uma Notification Integration e criar um monitor personalizado que envia alertas para o Slack ou para o Teams. Se quiser um monitoramento extremamente fácil de usar, dê uma olhada nos monitors do SELECT.
\
Controle o acesso com roles\
Por padrão, a role CORTEX_USER é concedida à role PUBLIC, o que significa que todos os usuários têm acesso. Se você não quer acesso universal, revogue da PUBLIC e conceda apenas a roles específicas:
-- Restringir o Cortex Analyst a equipes específicas
USE ROLE ACCOUNTADMIN;
REVOKE DATABASE ROLE SNOWFLAKE.CORTEX_USER FROM ROLE PUBLIC;
GRANT DATABASE ROLE SNOWFLAKE.CORTEX_USER TO ROLE data_analysts;
GRANT DATABASE ROLE SNOWFLAKE.CORTEX_USER TO ROLE finance_team;
Essa mudança simples evita o espalhamento descontrolado por toda a organização.
\
Otimize os modelos semânticos\
Um modelo semântico bem construído reduz o número de retentativas e de queries que falham. Foque em uma área de assunto específica em vez de expor bancos de dados inteiros. Inclua queries verificadas para perguntas comuns para melhorar a precisão. Isso reduz chamadas de API desperdiçadas e melhora a experiência do usuário.
Adicione repositórios de queries verificadas. São perguntas de exemplo com SQL validado que melhoram drasticamente a precisão. Quando os usuários fazem perguntas parecidas, o Cortex Analyst pode usar esses exemplos como referência:
\
1verified_queries:\
\
2 - name: "receita total no último trimestre"\
\
3 question: "Qual foi a receita total no Q4?"\
\
4 sql: |\
\
5 SELECT SUM(revenue_amount)\
\
6 FROM fact_sales\
\
7 WHERE sale_date >= '2024-10-01'\
\
8 AND sale_date < '2025-01-01'\
\
9 verified_result: 1250000.00\
```\
\
**Use nomes descritivos e adicione sinônimos**. Se sua tabela se chama `dim_product_category_master`, defina-a com nomes amigáveis para o negócio:\
\
```yaml\
1dimensions:\
\
2 - name: product_category\
\
3 synonyms: ["categoria", "tipo de produto", "classe de produto"]\
\
4 description: "Agrupamento de produtos em alto nível (Eletrônicos, Vestuário etc.)"\
```\
\
### Defina seu método de atribuição de custo do warehouse\
\
Como mencionamos antes, você precisa decidir como vai atribuir os custos do SQL gerado pelo Cortex Analyst. Alguns clientes optam por um warehouse dedicado, outros preferem atribuir o custo por role.\
\
### Use o menor tamanho de warehouse padrão possível\
\
A maioria das queries do Cortex Analyst são agregações relativamente simples. Provavelmente, você não precisa de um warehouse XL para isso.\
\
### Eduque seus usuários\
\
A maior alavanca de custo é o comportamento do usuário. Quando os usuários entendem que:\
\
- 10 perguntas custam alguns dólares\
- perguntas complexas podem exigir várias tentativas\
- perguntas mais amplas disparam queries maiores no warehouse\
\
...eles naturalmente passam a usar a ferramenta com mais critério. Crie documentação interna com exemplos de custo e boas práticas para formular perguntas.\
\
Para fechar\
O Cortex Analyst é uma ferramenta poderosa para democratizar o acesso a dados, mas, como todos os serviços de IA, os custos podem surpreender quando não são monitorados.
Use CORTEX_ANALYST_USAGE_HISTORY para acompanhamento granular, implemente controles de acesso baseados em roles e oriente seus usuários sobre padrões de uso econômicos. Com essas práticas em prática, dá para implantar o Cortex Analyst em toda a organização com tranquilidade, sem dor de cabeça com o orçamento.
Lembre-se: o verdadeiro ROI do Cortex Analyst não está só em deixar de escrever SQL — está em entregar respostas mais rápidas aos usuários de negócio para que tomem decisões melhores. Gastar alguns créditos a mais para empoderar o time costuma compensar bastante diante do custo de insights atrasados ou recursos de analytics mal alocados.
Divirta-se conversando com seus dados. E, como sempre, fale com a gente para contar suas conquistas usando o Cortex Analyst!
Jeff é Consultor de Dados e Analytics com mais de 15 anos de experiência em automatizar insights e usar dados para controlar processos de negócio. Do ponto de vista tecnológico, é especialista em Snowflake + dbt + Tableau. Do lado de negócios, tem experiência em Serviços Públicos, Ensaios Clínicos, Publicação, CPG e Manufatura. Entre em contato quando quiser: [email protected].\