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. Observe que a API não tem estado, portanto, apenas conversas de turno único são suportadas.

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[].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": {
        "role": "analyst",
        "content": [
            {
                "type": "text",
                "text": "We interpreted your question as ..."
            },
            {
                "type": "sql",
                "statement": "SELECT * FROM table"
            }
        ]
    }
}
Copy
Linguagem: Português