Uso de tradutores de solicitação e resposta com dados para um serviço remoto¶

Atribuição de uma função de tradutor a uma função externa¶

Para especificar qual função definida pelo usuário usar como tradutor, inclua cláusulas REQUEST_TRANSLATOR e RESPONSE_TRANSLATOR na instrução CREATE EXTERNAL FUNCTION. Cada uma leva o nome da função do tradutor para usar durante a execução.

Por exemplo:

CREATE EXTERNAL FUNCTION f(...)
    RETURNS OBJECT
    ...
    REQUEST_TRANSLATOR = my_request_translator_udf
    RESPONSE_TRANSLATOR = my_response_translator_udf
    ...
    AS <url_of_proxy_and_resource>;

Copy

A sintaxe para especificar tradutores como parte de uma instrução CREATE EXTERNAL FUNCTION é mostrada abaixo:

CREATE EXTERNAL FUNCTION f(...)
    RETURNS OBJECT
    ...
    [ REQUEST_TRANSLATOR = <request_translator_udf_name> ]
    [ RESPONSE_TRANSLATOR = <response_translator_udf_name> ]
    ...

Copy

onde:

request_translator_udf_name

O nome da função do tradutor de solicitação.

response_translator_udf_name

O nome da função do tradutor de resposta.

Cada um dos parâmetros REQUEST_TRANSLATOR e RESPONSE_TRANSLATOR toma um parâmetro do tipo OBJECT.

Você também pode especificar um tradutor de solicitação ou resposta em um comando ALTER FUNCTION. Você pode:

• Adicionar um tradutor se a função externa ainda não tiver um.

• Substituir um tradutor existente.

• Remover um tradutor.

Use a palavra-chave SET para adicionar um novo tradutor ou para substituir um tradutor existente.

Para adicionar ou substituir um tradutor:

ALTER FUNCTION ...
    SET [REQUEST_TRANSLATOR | RESPONSE_TRANSLATOR] = <udf_name>;

Copy

onde

udf_name

O nome de uma JavaScript UDF previamente criada.

Para remover um tradutor:

ALTER FUNCTION ...
    UNSET [REQUEST_TRANSLATOR | RESPONSE_TRANSLATOR];

Copy

Requisitos para o SQL¶

• O nome da função do tradutor na instrução CREATE EXTERNAL FUNCTION ou ALTER FUNCTION deve ser uma das seguintes opções:

  • Um nome qualificado (por exemplo, MyDatabase.MySchema.MyJavaScriptUDF).

  • Definido no mesmo banco de dados e esquema que a função externa que o utiliza.

• Quando o tradutor é especificado em uma instrução CREATE EXTERNAL FUNCTION ou ALTER FUNCTION, a UDF do tradutor já deve existir. Você não pode especificar o nome primeiro e criar a UDF depois, mesmo se você não chamar a função externa antes de criar a UDF.

• Uma UDF usada como tradutor não deve ser descartada sem antes removê-la de todas as funções externas que a utilizam. (No momento em que a função externa é chamada, o Snowflake apresenta falha com um erro se o tradutor não existir).

• Se a UDF do tradutor for modificada (via ALTER FUNCTION), ela deve manter os mesmos requisitos de interface. Se ela não mantiver os requisitos de interface, uma exceção é apresentada antes de executar a função externa.

Implementação de um tradutor de solicitação¶

Implementação de um tradutor de resposta¶

Requisitos para a função de tradutor¶

Cada UDF de tradutor deve atender aos seguintes requisitos:

• Deve ser uma JavaScript UDF.

• Deve tomar exatamente um parâmetro do tipo OBJECT, que representa um lote de linhas.

• Deve retornar um valor do tipo OBJECT, que também representa um lote de linhas.

• Deve ser uma UDF escalar (retornando uma linha para cada linha (OBJECT) passada).

  Nota

  Embora o tradutor seja escalar, o OBJECT passado para o tradutor pode ter (e normalmente tem) várias linhas embutidas dentro do JSON no OBJECT.

• O número e a ordem das linhas (dentro do OBJECT) retornadas pela UDF do tradutor de resposta devem ser os mesmos que o número e a ordem das linhas passadas para a UDF do tradutor de solicitação (dentro do OBJECT).

Configuração¶

Configure um banco de dados para armazenar dados de demonstração.

Escolha uma função que tenha permissão para criar funções externas:

USE ROLE ACCOUNTADMIN;

Especifique qual warehouse, banco de dados e esquema usar:

USE WAREHOUSE w;
USE DATABASE a;
USE SCHEMA b;

Crie uma tabela para armazenar suas frases de teste:

CREATE TABLE demo(vc varchar);
INSERT INTO demo VALUES('Today is a good day'),('I am feeling mopey');

Solicitação do corpo antes da tradução¶

Esta função externa não tem um tradutor de solicitação ou de resposta:

CREATE OR REPLACE EXTERNAL FUNCTION ComprehendSentiment(thought varchar)
RETURNS VARIANT
API_INTEGRATION = aws_comprehend_gateway
AS 'https://<MY_GATEWAY>.execute-api.us-east-1.amazonaws.com/test/comprehend_proxy';

Você pode chamar a função externa com seus dados de teste a partir da tabela de demonstração:

SELECT ComprehendSentiment(vc), vc FROM demo;

O corpo de solicitação gerado usa o formato de dados da função externa do Snowflake:

{"body":{"data:" [[0, "Today is a good day"],[1,"I am feeling mopey"]]}}

Entretanto, o serviço de análise de sentimento externo espera um formato diferente que especifique o idioma e uma matriz de cadeias de caracteres:

{"body": { Language: "en", TextList: [ "Today is a good day", "I am feeling mopey"]}}

A próxima seção descreve como você pode adicionar um tradutor de solicitação para mudar o corpo de solicitação para o formato exigido.

Converter o corpo de solicitação¶

Ao usar um tradutor de solicitação, você pode converter a entrada padrão descrita acima (no formato de dados do Snowflake) para o formato que o serviço externo exige.

O seguinte SQL cria uma função de tradutor awscomprehendrequest_translator.

CREATE OR REPLACE FUNCTION AWSComprehendrequest_translator(EVENT OBJECT)
RETURNS OBJECT
LANGUAGE JAVASCRIPT AS
'
var textlist = []
for(i = 0; i < EVENT.body.data.length; i++) {
   let row = EVENT.body.data[i];
   // row[0] is the row number and row[1] is the input text.
   textlist.push(row[1]); //put text into the textlist
}
// create the request for the service. Also pass the input request as part of the output.
return { "body": { "LanguageCode": "en", "TextList" : textlist }, "translatorData": EVENT.body }
';

Na função do tradutor de solicitação, o código:

• Executa loops por cada uma das linhas de entrada. Para cada linha, adiciona a cadeia de caracteres, que está em row[1], à matriz textlist. O valor em row[0] é o número da linha e pode ser ignorado.

• Retorna um corpo JSON que possui o código do idioma e a lista de texto que corresponde aos requisitos do serviço externo.

• Retorna os dados pelo campo translatorData. Isso é usado pelo tradutor de resposta. Neste exemplo, você está enviando os dados de entrada originais. Você usará o comprimento dos dados de entrada no tradutor de resposta para saber quantas solicitações de entrada foram feitas.

Você pode testar o tradutor de solicitação chamando-o diretamente.

SELECT AWSComprehendrequest_translator(parse_json('{"body":{"data": [[0, "I am so happy we got a sunny day for my birthday."], [1, "$$$$$."], [2, "Today is my last day in the old house."]]}}'));

O tradutor de solicitação coloca o corpo na forma esperada pelo serviço externo.

{"body":{
   "LanguageCode": "en",
   "TextList": [
      "I am so happy we got a sunny day for my birthday.",
      "$$$$$.",
      "Today is my last day in the old house."
               ]
         },
   "translatorData": {
      "data": [[0, "I am so happy we got a sunny day for my birthday."],
               [1, "$$$$$."],
               [2, "Today is my last day in the old house."]]
                     }
}

Corpo de resposta antes de adicionar um tradutor de resposta¶

Um corpo de resposta do serviço externo é semelhante a isto.

{"body":{
   "ErrorList": [ { "ErrorCode": 57, "ErrorMessage": "Language unknown", "Index": 1} ],
   "ResultList":[ { "Index": 0, "Sentiment": "POSITIVE",
                    "SentimentScore": { "Mixed": 25, "Negative": 5, "Neutral": 1, "Positive": 90 }},
                  { "Index": 2, "Sentiment": "NEGATIVE",
                    "SentimentScore": { "Mixed": 25, "Negative": 75, "Neutral": 30, "Positive": 20 }}
                ]
         }
}

Conversão do corpo de resposta¶

O tradutor de resposta processa os resultados que você recebe de volta do serviço externo. Os resultados contêm uma combinação de erros na ErrorList e resulta na ResultList.

O código do tradutor de resposta combina esses resultados para fazer um conjunto completo que corresponde à ordem das linhas que foram passadas para o serviço externo. O tradutor de resposta retorna os resultados no formato do Snowflake.

O seguinte SQL cria uma função de tradutor awscomprehendresponse_translator.

CREATE OR REPLACE FUNCTION AWSComprehendresponse_translator(EVENT OBJECT)
RETURNS OBJECT
LANGUAGE JAVASCRIPT AS
'
// Combine the scored results and the errors into a single list.
var responses = new Array(EVENT.translatorData.data.length);
// output format: array of {
// "Sentiment": (POSITIVE, NEUTRAL, MIXED, NEGATIVE, or ERROR),
// "SentimentScore": <score>, "ErrorMessage": ErrorMessage }.
// If error, set ErrorMessage; otherwise, set SentimentScore.
// Insert good results into proper position.
for(i = 0; i < EVENT.body.ResultList.length; i++) {
   let row = EVENT.body.ResultList[i];
   let result = [row.Index, {"Sentiment": row.Sentiment, "SentimentScore": row.SentimentScore}]
   responses[row.Index] = result
}
// Insert errors.
for(i = 0; i < EVENT.body.ErrorList.length; i++) {
   let row = EVENT.body.ErrorList[i];
   let result = [row.Index, {"Sentiment": "Error", "ErrorMessage": row.ErrorMessage}]
   responses[row.Index] = result
}
return { "body": { "data" : responses } };
';

Na função do tradutor de resposta, o código:

• Inicializa uma matriz chamada responses com o tamanho da entrada a partir do comprimento da matriz translatorData. Você enviou translatorData do tradutor de solicitação para o tradutor de resposta para passar a lista original das cadeias de caracteres de teste.

• Executa loops por cada um dos resultados sem erro e os coloca na lista de resultados.

• Executa loops pelos resultados de erros e os coloca na lista de resultados. A lista de resultados tem uma posição de índice que informa cada registro. A ordem dos resultados produzidos deve corresponder à ordem de entrada. A lista de resultados também contém as informações sobre sentimentos.

Após todas as respostas terem sido coletadas, elas são retornadas em um corpo JSON no formato esperado pelo Snowflake.

O seguinte teste direto retornará um corpo JSON com o formato correto.

SELECT AWSComprehendresponse_translator(
    parse_json('{
        "translatorData": {
            "data": [[0, "I am so happy we got a sunny day for my birthday."],
                    [1, "$$$$$."],
                    [2, "Today is my last day in the old house."]]
                          }
        "body": {
            "ErrorList":  [ { "ErrorCode": 57,  "ErrorMessage": "Language unknown",  "Index": 1 } ],
            "ResultList": [
                            { "Index": 0,  "Sentiment": "POSITIVE",
                              "SentimentScore": { "Mixed": 25,  "Negative": 5,  "Neutral": 1,  "Positive": 90 }
                            },
                            { "Index": 2, "Sentiment": "NEGATIVE",
                              "SentimentScore": { "Mixed": 25,  "Negative": 75,  "Neutral": 30,  "Positive": 20 }
                            }
                          ]
            },
        }'
    )
);

Atribuição de tradutores à função externa¶

À função externa, adicione as funções de tradutor de solicitação e resposta, atribuindo os nomes das funções como valores aos parâmetros request_translator e response_translator. Dessa forma, eles serão chamados automaticamente quando a função externa for executada.

CREATE OR REPLACE EXTERNAL FUNCTION ComprehendSentiment(thought varchar)
RETURNS VARIANT
API_INTEGRATION = aws_comprehend_gateway
request_translator = db_name.schema_name.AWSComprehendrequest_translator
response_translator = db_name.schema_name.AWSComprehendresponse_translator
AS 'https://<MY_GATEWAY>.execute-api.us-east-1.amazonaws.com/test/comprehend_proxy';

Você pode descrever a função para obter informações sobre ela.

DESCRIBE FUNCTION ComprehendSentiment(VARCHAR);

Chamada da função externa¶

Teste a função externa chamando-a com uma única frase.

SELECT ComprehendSentiment('Today is a good day');

Você vê os resultados da análise de sentimento.

{"Sentiment": "POSITIVE",
 "SentimentScore":{"Mixed":0.002436627633869648,
                   "Negative":0.0014803812373429537,
                   "Neutral":0.015923455357551575,
                   "Positive": 0.9801595211029053}}

Teste a função externa chamando-a com múltiplas frases. Use a mesma tabela demo que você criou anteriormente.

SELECT ComprehendSentiment(vc), vc FROM demo;

Os resultados da análise de sentimento são exibidos.

Quando a função externa foi chamada, o tradutor de solicitação converteu automaticamente os dados no formato exigido pelo serviço externo. Então, o tradutor de resposta converteu automaticamente a resposta do serviço externo no formato exigido pelo Snowflake.