Cortex Analyst REST API

Use esta API para responder perguntas sobre seus dados com consultas em linguagem natural.

Envio de mensagem

POST /api/v2/cortex/analyst/message

Gera uma consulta SQL para a pergunta fornecida usando um modelo semântico ou uma exibição semântica fornecida na solicitação. Um ou mais modelos podem ser especificados; quando vários modelos são especificados, o Cortex Analyst escolhe o mais adequado. É possível ter conversas com várias interações, nas quais pode-se fazer perguntas de acompanhamento que se baseiam em perguntas anteriores. Para obter mais informações, consulte Conversas com múltiplas interações no Cortex Analyst.

A solicitação inclui uma pergunta do usuário; a resposta inclui a pergunta do usuário e a resposta do analista. Cada mensagem em uma resposta pode ter vários blocos de conteúdo de diferentes tipos. Três valores atualmente suportados para o campo type do objeto de conteúdo são: text, suggestions e sql.

As respostas podem ser enviadas de uma só vez, após a conclusão do processamento, ou de forma incremental, à medida que são geradas.

Cabeçalhos de solicitação

Cabeçalho

Descrição

Authorization

Token de autorização (obrigatório). Para obter mais informações, consulte Autenticação no servidor.

Content-Type

Aplicativo/json (obrigatório)

X-Snowflake-Authorization-Token-Type

(Opcional) Tipo de token de autorização. O padrão é OAuth. Para obter mais informações, consulte Autenticação no servidor.

Corpo da solicitação

No corpo da solicitação:

  • Defina o último campo messages[].role como a função de quem fala, que deve ser user.

  • Inclua a pergunta do usuário no objeto content. Neste objeto:

    • Defina type como text.

    • Defina text para a pergunta do usuário.

  • Inclua um dos seguintes itens:

    • A especificação do modelo semântico em YAML.

    • O caminho para o arquivo YAML que contém a especificação do modelo semântico. Esse arquivo deve estar em um estágio.

    • O nome da exibição semântica.

A tabela a seguir descreve os campos que você pode definir no corpo da solicitação:

Campo

Descrição

messages[].role

A função da entidade que está criando a mensagem (obrigatório). Atualmente só oferece suporte a user.

Tipo: string:enum

Exemplo: user

messages[].content[]

O objeto de conteúdo que faz parte de uma mensagem (obrigatório).

Tipo: objeto

Exemplo:

{
  "type": "text",
  "text":  "Which company had the most revenue?"
}
Copy

messages[].content[].type

O tipo de conteúdo (obrigatório). Atualmente, somente text é compatível.

Tipo: string:enum

Exemplo: text

messages[].content[].text

A pergunta do usuário (obrigatório).

Tipo: cadeia de caracteres

Exemplo: Which company had the most revenue?

semantic_model_file

Caminho para o arquivo YAML do modelo semântico. Deve ser um URL do estágio totalmente qualificado, incluindo o banco de dados e o esquema.

Para especificar vários modelos semânticos, use o campo semantic_models.

Se, em vez disso, você quiser fornecer a especificação YAML diretamente na solicitação, defina o campo semantic_model como a especificação YAML para o modelo semântico.

Tipo: cadeia de caracteres

Exemplo: @my_db.my_schema.my_stage/my_semantic_model.yaml

semantic_model

Uma cadeia de caracteres contendo todo o YAML do modelo semântico.

Para especificar vários modelos semânticos, use o campo semantic_models em vez disso.

Se, em vez disso, você quiser apontar para uma especificação YAML em um arquivo, carregue o arquivo em um estágio e defina o campo semantic_model_file como o caminho do arquivo.

Tipo: cadeia de caracteres

semantic_models

Uma matriz contendo objetos JSON, cada um dos quais contém um campo semantic_model_file ou semantic_view.

Esses campos têm a mesma semântica que os campos de nível superior semantic_model_file e semantic_view:

  • semantic_model_file especifica um arquivo YAML, armazenado em um estágio, que contém uma definição de modelo semântico. (Você não pode especificar o YAML para o modelo semântico diretamente na solicitação com esse formulário)

  • semantic_view especifica o nome totalmente qualificado de uma exibição semântica. Por exemplo:

    {
  /* ... */
  "semantic_models": [
    {"semantic_view": "my_db.my_sch.my_sem_view_1" },
    {"semantic_view": "my_db.my_sch.my_sem_view_2" }
  ]
  /* ... */
}
    Copy

Para cada consulta, o Cortex Analyst escolhe o modelo ou a exibição mais adequada da lista.

Esse recurso simplifica as interações de usuário com o Cortex Analyst. Você não precisa escolher uma fonte de dados para consultar e não precisa controlar qual modelo semântico ou exibição semântica usar para cada um. Basta especificar todos os seus modelos ou exibições em cada consulta e deixar que o Cortex Analyst descubra qual deles usar.

Tipo: matriz

Dica

O Cortex Analyst não exige que você especifique mais de um modelo ou exibição. Se você especificar um único modelo ou exibição, a solicitação será funcionalmente equivalente a uma solicitação que contenha um campo de nível superior semantic_model_file ou semantic_view.

A vantagem de usar semantic_models para solicitações de modelo único é que você pode usar o mesmo código de cliente, independentemente do número de modelos ou exibições.

semantic_view

Nome totalmente qualificado da exibição semântica. Por exemplo:

{
  /* ... */
  "semantic_view": "MY_DB.MY_SCHEMA.SEMANTIC_VIEW"
  /* ... */
}
Copy

Se o nome diferenciar maiúsculas de minúsculas ou contiver caracteres que não são permitidos em um identificador sem aspa, você deverá colocar o nome entre aspas duplas com o caractere de escape de barra invertida. Por exemplo, se o nome do banco de dados, nome do esquema e nome da exibição incluírem hífens (my-database.my-schema.my-semantic-view):

{
  /* ... */
  "semantic_view": "\"my-database\".\"my-schema\".\"\"my-semantic-view\"\""
  /* ... */
}
Copy

Para especificar várias exibições semânticas, use o campo semantic_models.

Tipo: cadeia de caracteres

stream

(Opcional) Se definido como true, a resposta é transmitida ao cliente usando os eventos enviados pelo servidor à medida que é gerada (consulte Resposta de streaming). Caso contrário, a resposta completa será retornada depois que o Cortex Analyst tiver processado totalmente a pergunta do usuário.

Tipo: booliano

Importante

Você deve especificar um dos seguintes campos no corpo da solicitação:

  • semantic_model_file

  • semantic_model

  • semantic_models

  • semantic_view

Exemplo de especificação de um modelo semântico em um arquivo em um estágio

{
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "which company had the most revenue?"
                }
            ]
        }
    ],
    "semantic_model_file": "@my_db.my_schema.my_stage/my_semantic_model.yaml"
}
Copy

Exemplo de especificação de uma exibição semântica

{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "which company had the most revenue?"
        }
      ]
    }
  ],
  "semantic_view": "MY_DB.MY_SCH.MY_SEMANTIC_VIEW"
}
Copy

Resposta sem streaming

Essa operação pode retornar os códigos de resposta listados abaixo. A resposta sempre tem a seguinte estrutura. Atualmente, três tipos de conteúdo são suportados para a resposta, text, suggestion e sql. Os tipos de conteúdo suggestion e sql são mutuamente exclusivos, de modo que, se a resposta contiver um tipo de conteúdo sql, ela não conterá um tipo de conteúdo suggestion e vice-versa. O tipo de conteúdo suggestion só é incluído em uma resposta se a pergunta do usuário for ambígua e Cortex Analyst não puder retornar uma instrução para essa consulta SQL.

Quando a solicitação contém um campo semantic_models, a resposta inclui um campo semantic_model_selection que indica qual modelo semântico foi escolhido para a solicitação.

Para garantir a compatibilidade futura, certifique-se de que sua implementação leve em conta o tipo de conteúdo e trate os tipos.

Código

Descrição

200

A instrução foi executada com sucesso.

O corpo da resposta contém um objeto de mensagem que contém os seguintes campos:

  • message: mensagens da conversa entre o usuário e o analista.

  • message (objeto): representa uma mensagem dentro de um bate-papo.

  • message.role (cadeia de caracteres:enum): a entidade que produziu a mensagem. user ou analyst.

  • message.content[] (objeto): o objeto de conteúdo que faz parte de uma mensagem.

  • message.content[].type (string:enum): o tipo de conteúdo da mensagem. text, suggestion ou sql.

  • message.content[].text (string): o texto do conteúdo. Retornado somente para o tipo de conteúdo text.

  • message.content[].statement (string): uma instrução SQL. Retornado somente para o tipo de conteúdo sql.

  • message.content[].confidence (objeto): contém informações relacionadas à confiança. Retornado somente para o tipo de conteúdo sql.

  • message.content[].confidence.verified_query_used (objeto): representa a consulta verificada do repositório de consultas verificadas usado na geração de respostas SQL. Se nenhuma consulta verificada for usada, o valor do campo será null.

  • message.content[].confidence.verified_query_used.name (string): o nome da consulta verificada usada, extraída do repositório de consultas verificadas.

  • message.content[].confidence.verified_query_used.question (string): a pergunta que é respondida pela consulta verificada, extraída do repositório de consultas verificadas.

  • message.content[].confidence.verified_query_used.sql (string): a instrução SQL da consulta verificada usada, extraída do repositório de consultas verificadas.

  • message.content[].confidence.verified_query_used.verified_at (inteiro): a representação numérica do carimbo de data/hora quando a consulta é verificada, extraída do repositório de consultas verificadas.

  • message.content[].confidence.verified_query_used.verified_by (string): a pessoa que verificou a consulta, extraída do repositório de consultas verificadas.

  • message.content[].suggestions (string): se SQL não puder ser gerado, uma lista de perguntas que o modelo semântico pode gerar SQL. Retornado somente para o tipo de conteúdo suggestion.

  • warnings: lista de avisos do analista sobre a solicitação do usuário.

  • warnings[].message (string): contém uma descrição detalhada de um aviso individual.

  • response_metadata (objeto): metadados que contêm detalhes de geração de resposta.

  • response_metadata.model_names: lista de modelos usados para gerar a resposta.

  • response_metadata.cortex_search_retrieval (objeto): entidades resolvidas com a pesquisa do Cortex.

  • response_metadata.question_category (string): como a pergunta na solicitação é categorizada.

Por padrão, a resposta é retornada de uma só vez depois que o Cortex Analyst tiver processado totalmente a pergunta do usuário. Consulte Resposta de streaming para saber o formato das respostas do modo de streaming.

{
    "request_id": "75d343ee-699c-483f-83a1-e314609fb563",
    "message": {
        "role": "analyst",
        "content": [
            {
                "type": "text",
                "text": "We interpreted your question as ..."
            },
            {
                "type": "sql",
                "statement": "SELECT * FROM table",
                "confidence": {
                    "verified_query_used": {
                        "name": "My verified query",
                        "question": "What was the total revenue?",
                        "sql": "SELECT * FROM table2",
                        "verified_at": 1714497970,
                        "verified_by": "Jane Doe"
                    }
                }
            }
        ]
    },
    "warnings": [
        {
            "message": "Table table1 has (30) columns, which exceeds the recommended maximum of 10"
        },
        {
            "message": "Table table2 has (40) columns, which exceeds the recommended maximum of 10"
        }
    ],
    "response_metadata": {
        "model_names": [
            "claude-3-5-sonnet"
        ],
        "cortex_search_retrieval": [
            {
                "service": "my_db.my_schema.my_search_service",
                "response_body": {
                    "results": [
                        {
                            "CUST_NAME": "customer1"
                        }
                    ],
                    "request_id": "request1"
                },
                "query": "'customer1'"
            }
        ],
        "question_category": "CLEAR_SQL"
    }
}
Copy

Resposta de streaming

O modo streaming permite que o cliente receba respostas à medida que são geradas pelo Cortex Analyst, em vez de esperar que toda a resposta seja gerada. Isso melhora a percepção da capacidade de resposta de seu aplicativo, especialmente para consultas de longa duração, porque os usuários começam a ver a saída muito antes. As respostas de streaming também fornecem informações de status que podem ajudá-lo a entender onde o Cortex Analyst está no processo de geração de uma resposta e avisos que podem ajudar a entender o que deu errado quando o Cortex Analyst não funciona como o esperado.

Para receber uma resposta de streaming, defina o campo stream no corpo da solicitação como true. As respostas de streaming usam os eventos enviados pelo servidor.

O Cortex Analyst envia cinco tipos distintos de eventos em uma resposta de streaming:

  • status: transmite atualizações de status sobre o processo de geração SQL.

  • message.content.delta: contém uma parte da resposta. Esse evento é enviado várias vezes.

  • error: indica que o Cortex Analyst encontrou um erro e não pode continuar processando a solicitação. Nenhum outro evento message.content.delta será enviado.

  • warnings: contém todos os avisos encontrados durante o processamento. Os avisos não interrompem o processamento.

  • response_metadata: enviado no final de uma resposta para exibir dados sobre o processamento da solicitação.

  • done: enviado para indicar que o processamento foi concluído e que nenhum outro evento message.content.delta será enviado.

Desses, os eventos message.content.delta são os mais importantes para entender, pois contêm o conteúdo real da resposta. Cada delta contém tokens de algum campo da resposta completa. É possível que cada evento delta contenha desde um único caractere até a resposta completa, e eles podem ter comprimentos diferentes. Você recebe esses tokens à medida que eles são gerados; cabe a ele reuni-los na resposta final.

Importante

Os eventos de diferentes respostas (mesmo as extremamente semelhantes) podem variar. Não há garantia de que os eventos serão enviados na mesma ordem ou com o mesmo conteúdo.

Exemplo simples

A seguir, uma amostra de resposta sem streaming para uma consulta simples:

{
    "message": {
        "role": "analyst",
        "content": [
            {
                "type": "text",
                "text": "This is how we interpreted your question and this is how the sql is generated"
            },
            {
                "type": "sql",
                "statement": "SELECT * FROM table"
            }
        ]
    }
}
Copy

E essa é uma série possível de eventos de streaming para essa resposta (uma série diferente de eventos também é possível):

event: status
data: { status: "interpreting_question" }

event: message.content.delta
data: {
  index: 0,
  type: "text",
  text_delta: "This is how we interpreted your question"
}

event: status
data: { status: "generating_sql" }

event: status
data: { status: "validating_sql" }

event: message.content.delta
data: {
  index: 0,
  type: "text",
  text_delta: " and this is how the sql is generated"
}

event: message.content.delta
data: {
  index: 1,
  type: "sql",
  statement_delta: "SELECT * FROM table"
}

event: status
data: { status: "done" }

Use o campo index nas respostas message.content.delta para determinar de qual campo da resposta completa o evento faz parte. Por exemplo, aqui os dois primeiros eventos delta usam o índice 0, o que significa que eles fazem parte do primeiro campo (elemento 0) na matriz content da resposta sem fluxo. Da mesma forma, o evento delta que contém a resposta SQL usa o índice 1.

Exemplo com sugestões

Este exemplo contém perguntas sugeridas para uma pergunta ambígua. A seguir, a resposta sem streaming:

{
    "message": {
        "role": "analyst",
        "content": [
            {
                "type": "text",
                "text": "Your question is ambigous, here are some alternatives:"
            },
            {
                "type": "suggestions",
                "suggestions": [
                    "which company had the most revenue?",
                    "which company placed the most orders?"
                ]
            }
        ]
    }
}
Copy

E aqui está uma possível série de eventos de fluxo contínuo que constituem essa resposta:

event: status
data: { status: "interpreting_question" }

event: message.content.delta
data: {
  index: 0,
  type: "text",
  text_delta: "Your question is ambigous,"
}

event: status
data: { status: "generating_suggestions" }

event: message.content.delta
data: {
  index: 0,
  type: "text",
  text_delta: " here are some alternatives:"
}

event: message.content.delta
data: {
  index: 1,
  type: "suggestions",
  suggestions_delta: {
    index: 0,
    suggestion_delta: "which company had",
  }
}

event: message.content.delta
data: {
  index: 1,
  type: "suggestions",
  suggestions_delta: {
    index: 0,
    suggestion_delta: " the most revenue?",
  }
}

event: message.content.delta
data: {
  index: 1,
  type: "suggestions",
  suggestions_delta: {
    index: 1,
    suggestion_delta: "which company placed",
  }
}

event: message.content.delta
data: {
  index: 1,
  type: "suggestions",
  suggestions_delta: {
    index: 1,
    suggestion_delta: " the most orders?",
  }
}

event: status
data: { status: "done" }

Neste exemplo, o campo de content da resposta sem fluxo é uma matriz. Um dos elementos de content é a matriz suggestions. Portanto, o significado dos campos index para os eventos delta text e suggestions refere-se ao local dos elementos nessas duas matrizes diferentes. Você precisará acompanhar esses índices separadamente ao montar a resposta completa.

Nota

Atualmente, a instrução SQL gerada é sempre enviada em um único evento. Isso pode não ser o caso no futuro. Seu cliente deve estar preparado para receber a instrução SQL em vários eventos.

Outros exemplos

Você pode encontrar um cliente de streaming Streamlit para Cortex Analyst no repositório |cortex-analyst| do GitHub. Essa demonstração deve ser executada localmente; o SiS não oferece suporte a streaming no momento.

Consulte o playground do Cortex Analyst no AI/ML Studio (no Snowsight) para obter uma demonstração interativa da resposta de streaming.

Esquemas de eventos de streaming

A seguir, os esquemas OpenAPI/Swagger dos eventos enviados pelo Cortex Analyst em uma resposta de streaming.

status
message.content.delta
erro
StreamingError:
type: object
properties:
  message:
    type: string
    description: A description of the error
  code:
    type: string
    description: The Snowflake error code categorizing the error
  request_id:
    type: string
    description: Unique request ID
Copy
warnings
Warnings:
type: object
description: Warnings found while processing the request
properties:
  warnings:
    type: array
    items:
      $ref: "#/components/schemas/Warning"
Warning:
type: object
title: The warning object
description: Represents a warning within a chat.
properties:
  message:
    type: string
    description: A human-readable message describing the warning
Copy
response_metadata
ResponseMetadata:
type: object
description: Details about request processing
Copy

Envie feedback

POST /api/v2/cortex/analyst/feedback

Fornece feedback qualitativo ao usuário final. No Snowsight, o feedback é mostrado em Semantic Model Admins em Monitoring.

Cabeçalhos de solicitação

Cabeçalho

Descrição

Authorization

Token de autorização (obrigatório). Para obter mais informações, consulte Autenticação no servidor.

Content-Type

Aplicativo/json (obrigatório)

Corpo da solicitação

Campo

Descrição

request_id

(Obrigatório) O ID da solicitação que você fez para enviar uma mensagem. Retornado no campo request_id de /api/v2/cortex/analyst/message. Para obter mais informações, consulte Resposta sem streaming.

Tipo: cadeia de caracteres

Exemplo: 75d343ee-699c-483f-83a1-e314609fb563

positive

(Obrigatório) Se o feedback é positivo ou negativo. true para positivo ou «curtir», false para negativo ou «não curtir».

Tipo: booliano

Exemplo:

true

feedback_message

(Opcional) A mensagem de feedback do usuário.

Exemplo: This is the best answer I've ever seen!

Resposta

Corpo de resposta vazio com código de status 200.

Requisitos de controle de acesso

Para obter informações sobre os privilégios necessários, consulte Requisitos de controle de acesso.

Para obter detalhes sobre a autenticação na API, consulte Autenticando o Snowflake REST APIs com Snowflake.

Linguagem: Português