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 o modelo semântico fornecido na solicitação. É 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 e 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.

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¶

O corpo da solicitação contém a função do palestrante, que deve ser user, a pergunta do usuário e um caminho para o arquivo YAML do modelo semântico. A pergunta do usuário está contida em um objeto content que possui dois campos, type e text. text também é o único valor permitido do campo type.

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. Em vez disso, você pode fornecer o YAML do modelo semântico completo no campo `semantic_model`. 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. Em vez disso, você pode passar o YAML do modelo semântico como um arquivo preparado, fornecendo seu URL no campo `semantic_model_file`. Tipo: cadeia de caracteres

Importante

Você deve fornecer semantic_model_file ou semantic_model no corpo da solicitação.

Exemplo¶

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

Copy

Resposta¶

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

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`. `message.content[].warnings`: lista de avisos do analista sobre a solicitação do usuário. `message.content[].warnings` (lista): representa uma coleção de avisos sobre solicitações de usuários e modelos semânticos. `message.content[].warnings[].message` (string): contém uma descrição detalhada de um aviso individual. { "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" } ] } Copy

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.
message.content[].warnings: lista de avisos do analista sobre a solicitação do usuário.
message.content[].warnings (lista): representa uma coleção de avisos sobre solicitações de usuários e modelos semânticos.
message.content[].warnings[].message (string): contém uma descrição detalhada de um aviso individual.

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

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. 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: booleano Exemplo: `true`
`feedback_message`	(Opcional) A mensagem de feedback do usuário. Exemplo: `This is the best answer I've ever seen!`

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.

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

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.