sqlrutils (pacote de R nos Serviços de Machine Learning do SQL Server)

Aplica-se a: SQL Server 2016 (13.x) e versões posteriores

O sqlrutils é um pacote de R da Microsoft que fornece um mecanismo para que os usuários de R coloquem seus scripts de R em um procedimento armazenado T-SQL, registrem esse procedimento armazenado em um banco de dados e executem o procedimento armazenado em um ambiente de desenvolvimento de R. O pacote está incluído nos Serviços de Machine Learning do SQL Server e no SQL Server 2016 R Services.

Ao converter o código R para executar dentro de um único procedimento armazenado, você pode fazer um uso mais eficaz dos serviços de R do SQL Server, o que exige que o script de R seja inserido como um parâmetro de sp_execute_external_script. O pacote sqlrutils ajuda a criar esse script de R incorporado e definir os parâmetros relacionados de maneira apropriada.

O pacote sqlrutils executa essas tarefas:

• Salva o script T-SQL gerado como uma cadeia de caracteres dentro de uma estrutura de dados de R
• Opcionalmente, gere um arquivo .sql para o script T-SQL, que você pode editar ou executar para criar um procedimento armazenado
• Registra o procedimento armazenado criado recentemente na instância do SQL Server do seu ambiente de desenvolvimento de R

Você também pode executar o procedimento armazenado em um ambiente de R, transmitindo parâmetros bem formados e processando os resultados. Ou, você pode usar o procedimento armazenado do SQL Server para oferecer suporte a cenários comuns de integração de banco de dados, como ETL, treinamento de modelo e pontuação de alto volume.

Documentação de referência completa

O pacote sqlrutils é distribuído em vários produtos da Microsoft, mas o uso é o mesmo com o pacote no SQL Server ou em outro produto. Se existirem comportamentos específicos do produto, as discrepâncias serão indicadas na página de ajuda da função.

Lista de funções

A seção a seguir fornece uma visão geral das funções que você pode chamar do pacote sqlrutils para desenvolver um procedimento armazenado contendo o código R inserido. Para obter detalhes sobre os parâmetros para cada função ou método, confira a Ajuda do R para o pacote: help(package="sqlrutils")

Como usar o sqlrutils

As funções do pacote sqlrutils devem ser executadas em um computador que tenha o SQL Server Machine Learning com R. Se você estiver trabalhando em uma estação de trabalho cliente, defina um contexto de computação remota para alternar a execução para o SQL Server. O fluxo de trabalho para usar esse pacote inclui as seguintes etapas:

• Definir parâmetros de procedimento armazenado (entradas, saídas ou ambos)
• Gerar e registrar o procedimento armazenado
• Executar o procedimento armazenado

Em uma sessão de R, carregue sqlrutils da linha de comando digitando library(sqlrutils).

Definir parâmetros e entradas de procedimento armazenado

StoredProcedure é o construtor principal usado para criar o procedimento armazenado. Este construtor gera um Objeto de procedimento armazenado do SQL Server e, opcionalmente, cria um arquivo de texto que contém uma consulta que pode ser usada para gerar o procedimento armazenado usando um comando T-SQL.

Opcionalmente, a função StoredProcedure também pode registrar o procedimento armazenado com a instância e o banco de dados especificado.

• Use o argumento func para especificar uma função de R válida. Todas as variáveis que a função usa devem ser definidas dentro da função ou ser fornecidas como parâmetros de entrada. Esses parâmetros podem incluir no máximo um quadros de dados.

• A função R deve retornar um quadro de dados, uma lista nomeada ou um valor NULO. Se a função retorna uma lista, a lista pode conter no máximo um data.frame.

• Use o argumento spName para especificar o nome do procedimento armazenado que você deseja criar.

• Você pode transmitir parâmetros opcionais de entrada e de saída, usando os objetos criados por essas funções auxiliares: setInputData, setInputParametere setOutputParameter.

• Opcionalmente, use filePath para fornecer o caminho e o nome de um arquivo .sql a ser criado. Você pode executar esse arquivo na instância do SQL Server para gerar o procedimento armazenado usando a T-SQL.

• Para definir o servidor e o banco de dados em que o procedimento armazenado será salvo, use os argumentos dbName e connectionString.

• Para obter uma lista dos objetos InputData e InputParameter que foram usados para criar um objeto específico StoredProcedure , chame getInputParameters.

• Para registrar o procedimento armazenado com o banco de dados especificado, use registerStoredProcedure.

O objeto de procedimento armazenado normalmente não tem quaisquer dados ou valores associados a ele, a menos que um valor padrão foi especificado. Os dados não serão recuperados até que o procedimento armazenado seja executado.

Especificar entradas e executar

• Use setInputDataQuery para atribuir uma consulta a um objeto InputParameter . Por exemplo, se você tiver criado um objeto de procedimento armazenado em R, você pode usar setInputDataQuery para transmitir argumentos para a função StoredProcedure a fim de executar o procedimento armazenado com as entradas desejadas.

• Use setInputValue para atribuir valores específicos para um parâmetro armazenado como um objeto InputParameter . Em seguida, transmita o objeto de parâmetro e sua atribuição de valor para a função StoredProcedure a fim de executar o procedimento armazenado com os valores definidos.

• Use executeStoredProcedure para executar um procedimento armazenado definido como um objeto StoredProcedure . Chame essa função apenas ao executar um procedimento armazenado de código R. Não use esta opção quando executar o procedimento armazenado do SQL Server usando a T-SQL.

Confira também

Como criar um procedimento armazenado usando sqlrutils