sqlrutils (pacote R em SQL Server Machine Learning Services)

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

sqlrutils é um pacote R da Microsoft que fornece um mecanismo para os utilizadores R colocarem os seus scripts R num procedimento armazenado T-SQL, registarem esse procedimento armazenado numa base de dados e executarem o procedimento armazenado a partir de um ambiente de desenvolvimento R. O pacote está incluído no SQL Server Machine Learning Services e no SQL Server 2016 R Services.

Ao converter o seu código R para ser executado dentro de um único procedimento armazenado, pode fazer uma utilização mais eficaz do R Services do SQL Server, o que exige que o script R seja incorporado como parâmetro de sp_execute_external_script. O pacote sqlrutils ajuda-te a construir este script R embutido e a definir parâmetros relacionados de forma adequada.

O pacote sqlrutils realiza estas tarefas:

  • Guarda o script T-SQL gerado como uma cadeia dentro de uma estrutura de dados R
  • Opcionalmente, gera um ficheiro .sql para o script T-SQL, que podes editar ou executar para criar um procedimento armazenado
  • Regista o procedimento armazenado recém-criado com a instância do SQL Server a partir do seu ambiente de desenvolvimento R

Também pode executar o procedimento armazenado a partir de um ambiente R, passando parâmetros bem formados e processando os resultados. Ou pode utilizar o procedimento armazenado do SQL Server para dar suporte a cenários comuns de integração de bases de dados, como ETL, treino de modelos e classificação em grande volume.

Note

Se pretende executar o procedimento armazenado a partir de um ambiente R chamando a função executeStoredProcedure, deve usar um fornecedor ODBC 3.8, como o ODBC Driver 13 para SQL Server.

Documentação de referência completa

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

Lista de funções

A secção seguinte fornece uma visão geral das funções que pode chamar do pacote sqlrutils para desenvolver um procedimento armazenado contendo código R incorporado. Para detalhes dos parâmetros de cada método ou função, consulte a ajuda em R para o pacote: help(package="sqlrutils")

Função Description
executeStored Procedure Executar um procedimento SQL armazenado.
getInputParameters Obtenha uma lista de parâmetros de entrada para o procedimento armazenado.
InputData Define a fonte dos dados no SQL Server que serão usados no quadro de dados R. Especificas o nome do data.frame onde armazenar os dados de entrada, e uma consulta para obter os dados, ou um valor predefinido. Apenas consultas simples SELECT são suportadas.
InputParameter Define um único parâmetro de entrada que será incorporado no script T-SQL. Deve fornecer o nome do parâmetro e o seu tipo de dado R.
OutputData Gera um objeto de dados intermédio que é necessário se a sua função R devolver uma lista que contenha um data.frame. O objeto OutputData é usado para armazenar o nome de um único data.frame obtido da lista.
Parâmetro de Saída Gera um objeto de dados intermédio que é necessário se a sua função R devolver uma lista. O objeto OutputParameter armazena o nome e o tipo de dado de um único membro da lista, assumindo que esse membro não é um quadro de dados.
registerStoredProcedure Registar o procedimento armazenado numa base de dados.
setInputDataQuery Atribuir uma consulta a um parâmetro de dados de entrada do procedimento armazenado.
setInputParameterValue Atribuir um valor a um parâmetro de entrada do procedimento armazenado.
StoredProcedure Um objeto de procedimento armazenado.

Como usar o sqlrutils

As funções do pacote sqlrutils devem correr num computador que tenha SQL Server Machine Learning com R. Se estiver a trabalhar numa estação de trabalho cliente, defina um contexto de computação remota para transferir a execução para o SQL Server. O fluxo de trabalho para usar este pacote inclui os seguintes passos:

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

Numa sessão R, carregue sqlrutils a partir da linha de comandos escrevendo library(sqlrutils).

Note

Podes carregar este pacote num computador que não tenha SQL Server (por exemplo, numa instância R Client) se mudares o contexto de computação para SQL Server e executares o código nesse contexto de computação.

Definir parâmetros e entradas de procedimentos armazenados

StoredProcedure é o principal construtor utilizado para criar o procedimento armazenado. Este construtor gera um objeto SQL Server Stored Procedure e, opcionalmente, cria um ficheiro de texto contendo uma consulta que pode ser usada para gerar o procedimento armazenado usando um comando T-SQL.

Opcionalmente, a função Stored Procedure pode também registar o procedimento armazenado com a instância e base de dados especificadas.

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

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

  • Use o argumento spName para especificar o nome do procedimento armazenado que pretende criar.

  • Pode passar parâmetros opcionais de entrada e saída, usando os objetos criados por estas funções auxiliares: setInputData, setInputParameter, e setOutputParameter.

  • Opcionalmente, use filePath para fornecer o caminho e o nome de um ficheiro .sql a criar. Pode executar este ficheiro na instância do SQL Server para gerar o procedimento armazenado usando T-SQL.

  • Para definir o servidor e a base de dados onde o procedimento armazenado será guardado, use os argumentos dbName e connectionString.

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

  • Para registar o procedimento armazenado na base de dados especificada, use registerStoredProcedure.

O objeto de procedimento armazenado normalmente não tem quaisquer dados ou valores associados, a menos que tenha sido especificado um valor padrão. Os dados não sã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 criou um objeto de procedimento armazenado em R, pode usar setInputDataQuery para passar argumentos à função Stored Procedure para executar o procedimento armazenado com as entradas desejadas.

  • Use setInputValue para atribuir valores específicos a um parâmetro armazenado como objeto InputParameter . Depois passa o objeto parâmetro e a sua atribuição de valor à função Stored Procedure para executar o procedimento armazenado com os valores do conjunto.

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

Note

A função executeStoredProcedure requer um fornecedor ODBC 3.8, como o ODBC Driver 13 para SQL Server.

Conteúdo relacionado

  • Last updated on