Instalar pacotes do R com o sqlmlutils

Artigo
05/30/2023

Aplica-se a: SQL Server 2019 (15.x) Instância Gerenciada de SQL do Azure

Este artigo descreve como usar funções no pacote sqlmlutils para instalar pacotes do R em uma instância dos Serviços de Machine Learning no SQL Server e em Clusters de Big Data. Os pacotes que você instalar poderão ser usados em scripts R em execução no banco de dados usando a instrução T-SQL sp_execute_external_script.

Observação

O pacote sqlmlutils descrito neste artigo é usado para adicionar pacotes do R ao SQL Server 2019 ou posterior. Para o SQL Server 2017 e anterior, confira Instalar pacotes com ferramentas do R.

Este artigo descreve como usar funções no pacote sqlmlutils para instalar pacotes do R em uma instância dos Serviços de Machine Learning da Instância Gerenciada de SQL do Azure. Os pacotes que você instalar poderão ser usados em scripts R em execução no banco de dados usando a instrução T-SQL sp_execute_external_script.

Observação

Você não pode atualizar ou desinstalar pacotes que foram pré-instalados em uma instância dos Serviços de Machine Learning de Instância Gerenciada de SQL. Para exibir uma lista de pacotes instalados no momento, confira Listar todos os pacotes R instalados.

Pré-requisitos

Instale o R e o RStudio Desktop no computador cliente que você usa para conectar-se ao SQL Server. Você pode usar qualquer IDE do R para executar scripts, mas este artigo pressupõe o RStudio.

A versão do R no computador cliente precisa corresponder à versão do R no servidor, e os pacotes instalados precisam estar em conformidade com a versão existente do R. Para obter mais informações sobre qual versão do R está incluída em cada versão do SQL Server, confira as versões de Python e R.

Para verificar a versão do R em determinado SQL Server, use o comando T-SQL a seguir.
```
EXECUTE sp_execute_external_script @language = N'R'
, @script = N'print(R.version)'
```
Instale o Azure Data Studio no computador cliente que você usa para se conectar ao SQL Server. Você pode usar outras ferramentas de consulta ou gerenciamento de banco de dados, mas este artigo pressupõe o uso do Azure Data Studio.

Outras considerações

A instalação do pacote é específica da instância SQL, banco de dados e usuários especificados por você nas informações de conexão fornecidas para sqlmlutils. Se quiser usar o pacote em várias instâncias ou bancos de dados SQL ou para diferentes usuários, você precisará instalá-lo para cada um. Com uma exceção: se o pacote for instalado por um membro de dbo, ele será público e compartilhado com todos os usuários. Se um usuário instalar uma versão mais recente de um pacote público, este não será afetado, mas o usuário terá acesso à versão mais recente.
O script R em execução no SQL Server pode usar apenas os pacotes instalados na biblioteca de instâncias padrão. O SQL Server não pode carregar pacotes de bibliotecas externas, mesmo que a biblioteca esteja no mesmo computador. Isso inclui bibliotecas do R instaladas com outros produtos da Microsoft.
Em um ambiente do SQL Server protegido, talvez você queira evitar o seguinte:
- Pacotes que exigem acesso à rede
- Pacotes que exigem acesso elevado ao sistema de arquivos
- Pacotes usados para desenvolvimento Web ou outras tarefas que não se beneficiam da execução dentro do SQL Server

Instalar sqlmlutils no computador cliente

Para usar sqlmlutils, primeiro você precisa instalá-lo no computador cliente que usa para se conectar ao SQL Server.

O pacote sqlmlutils depende do pacote odbc, e o odbc depende de vários outros pacotes. Os procedimentos a seguir instalam todos esses pacotes na ordem correta.

Instalar o sqlmlutils online

Se o computador cliente tiver acesso à Internet, você poderá baixar e instalar o sqlmlutils e seus pacotes dependentes online.

Baixe o arquivo mais recente do sqlmlutils (.zip para Windows, .tar.gz para Linux) de https://github.com/microsoft/sqlmlutils/releases para o computador cliente. Não expanda o arquivo.
Abra um prompt de comando e execute os comandos a seguir para instalar os pacotes odbc e sqlmlutils. Substitua o caminho para o arquivo de sqlmlutils que você baixou. O pacote odbc é encontrado online e está instalado.
```
R.exe -e "install.packages('odbc', type='binary')"
R.exe CMD INSTALL sqlmlutils_1.0.0.zip
```
```
R.exe -e "install.packages('odbc')"
R.exe CMD INSTALL sqlmlutils_1.0.0.tar.gz
```

Instalar o sqlmlutils offline

Se o computador cliente não tiver uma conexão com a Internet, você precisará baixar os pacotes odbc e sqlmlutils com antecedência usando um computador que tenha acesso à Internet. Em seguida, você pode copiar os arquivos para uma pasta no computador cliente e instalar os pacotes offline.

O pacote odbc tem vários pacotes dependentes, o que complica a identificação de todas as dependências de um pacote. Recomendamos usar miniCRAN para criar uma pasta de repositório local para o pacote que inclua todos os pacotes dependentes. Para mais informações, confira Criar um repositório de pacotes do R local usando o miniCRAN.

O pacote sqlmlutils consiste em um único arquivo que você pode copiar para o computador cliente e instalar.

Em um computador com acesso à Internet:

Instalar o miniCRAN. Confira Instalar o miniCRAN para obter detalhes.

No RStudio, execute o script R a seguir para criar um repositório local do pacote odbc. Este exemplo supõe que o repositório será criado na pasta odbc.

library("miniCRAN")
CRAN_mirror <- c(CRAN = "https://cran.microsoft.com")
local_repo <- "odbc"
pkgs_needed <- "odbc"
pkgs_expanded <- pkgDep(pkgs_needed, repos = CRAN_mirror);

makeRepo(pkgs_expanded, path = local_repo, repos = CRAN_mirror, type = "win.binary", Rversion = "3.5");

library("miniCRAN")
CRAN_mirror <- c(CRAN = "https://cran.microsoft.com")
local_repo <- "odbc"
pkgs_needed <- "odbc"
pkgs_expanded <- pkgDep(pkgs_needed, repos = CRAN_mirror);

makeRepo(pkgs_expanded, path = local_repo, repos = CRAN_mirror, type = "source", Rversion = "3.5");

Para o valor Rversion, use a versão do R instalada no SQL Server. Para verificar a versão instalada, use o comando T-SQL a seguir.

EXECUTE sp_execute_external_script @language = N'R'
 , @script = N'print(R.version)'

Baixe o arquivo de sqlmlutils mais recente (.zip para Windows, .tar.gz para Linux) de https://github.com/microsoft/sqlmlutils/releases. Não expanda o arquivo.
Copie toda a pasta do repositório odbc e o arquivo sqlmlutils para o computador cliente.

No computador cliente que você usa para se conectar ao SQL Server:

Abra um prompt de comando.
Execute os comandos a seguir para instalar o odbc e, depois, o sqlmlutils. Substitua os caminhos completos para a pasta do repositório odbc e para o arquivo sqlmlutils que você copiou neste computador.
```
R.exe -e "install.packages('odbc', repos='odbc')"
R.exe CMD INSTALL sqlmlutils_1.0.0.zip
```
```
R.exe -e "install.packages('odbc', repos='odbc')"
R.exe CMD INSTALL sqlmlutils_1.0.0.tar.gz
```

Adicionar um pacote do R no SQL Server

No exemplo a seguir, você adicionará o pacote glue ao SQL Server.

Adicionar o pacote online

Se o computador cliente que você usa para se conectar ao SQL Server tiver acesso à Internet, você poderá usar sqlmlutils para localizar o pacote glue e qualquer dependência pela Internet e, em seguida, instalar o pacote em uma instância do SQL Server remotamente.

No computador cliente, abra o RStudio e crie um novo arquivo de Script R.
Use o script R a seguir para instalar o pacote glue usando sqlmlutils. Substitua suas informações de conexão de banco de dados do SQL Server.
```
library(sqlmlutils)
connection <- connectionInfo(
  server   = "server",
  database = "database",
  uid      = "username",
  pwd      = "password")

sql_install.packages(connectionString = connection, pkgs = "glue", verbose = TRUE, scope = "PUBLIC")
```
Dica

O escopo pode ser PÚBLICO ou PRIVADO. O escopo público é útil para o administrador de banco de dados instalar pacotes que todos os usuários podem usar. O escopo privado disponibiliza o pacote apenas para o usuário que o instala. Se você não especificar o escopo, o escopo padrão será PRIVADO.

Adicionar o pacote offline

Se o computador cliente não tiver uma conexão com a Internet, você poderá usar miniCRAN para baixar o pacote do Glue usando um computador que tenha acesso à Internet. Em seguida, copie o pacote para o computador cliente no qual você pode instalar o pacote offline. Confira Instalar o miniCRAN para obter informações sobre como instalar o miniCRAN.

Em um computador com acesso à Internet:

Execute o script R a seguir para criar um repositório local para glue. Este exemplo cria a pasta do repositório em c:\downloads\glue.

library("miniCRAN")
CRAN_mirror <- c(CRAN = "https://cran.microsoft.com")
local_repo <- "c:/downloads/glue"
pkgs_needed <- "glue"
pkgs_expanded <- pkgDep(pkgs_needed, repos = CRAN_mirror);

makeRepo(pkgs_expanded, path = local_repo, repos = CRAN_mirror, type = "win.binary", Rversion = "3.5");

library("miniCRAN")
CRAN_mirror <- c(CRAN = "https://cran.microsoft.com")
local_repo <- "c:/downloads/glue"
pkgs_needed <- "glue"
pkgs_expanded <- pkgDep(pkgs_needed, repos = CRAN_mirror);

makeRepo(pkgs_expanded, path = local_repo, repos = CRAN_mirror, type = "source", Rversion = "3.5");

Para o valor Rversion, use a versão do R instalada no SQL Server. Para verificar a versão instalada, use o comando T-SQL a seguir.

EXECUTE sp_execute_external_script @language = N'R'
 , @script = N'print(R.version)'

Copie toda a pasta do repositório glue (c:\downloads\glue) para o computador cliente. Por exemplo, copie-a para a pasta c:\temp\packages\glue.

No computador cliente:

Abra RStudio e crie um arquivo R Script.
Use o script R a seguir para instalar o pacote glue usando sqlmlutils. Substitua suas informações de conexão de banco de dados SQL Server (se você não usar a autenticação do Windows, adicione os parâmetros uid e pwd).
```
library(sqlmlutils)
connection <- connectionInfo(
  server= "yourserver",
  database = "yourdatabase")
localRepo = "c:/temp/packages/glue"

sql_install.packages(connectionString = connection, pkgs = "glue", verbose = TRUE, scope = "PUBLIC", repos=paste0("file:///",localRepo))
```
Dica

O escopo pode ser PÚBLICO ou PRIVADO. O escopo público é útil para o administrador de banco de dados instalar pacotes que todos os usuários podem usar. O escopo privado disponibiliza o pacote apenas para o usuário que o instala. Se você não especificar o escopo, o escopo padrão será PRIVADO.

Usar o pacote

Depois da instalação do pacote glue, você pode usá-lo em um script R no SQL Server com o comando sp_execute_external_script do T-SQL.

Abra o Azure Data Studio e conecte-se ao seu banco de dados do SQL Server.

Execute o comando a seguir:

EXECUTE sp_execute_external_script @language = N'R'
    , @script = N'
library(glue)

name <- "Fred"
birthday <- as.Date("2020-06-14")
text <- glue(''My name is {name} '',
''and my birthday is {format(birthday, "%A, %B %d, %Y")}.'')

print(text)
      ';

Resultados

My name is Fred and my birthday is Sunday, June 14, 2020.

Remover o pacote

Se você quiser remover o pacote glue, execute o script R a seguir. Use a mesma variável de conexão definida anteriormente.

sql_remove.packages(connectionString = connection, pkgs = "glue", scope = "PUBLIC")

Mais funções do sqlmlutils

O pacote sqlmlutils contém várias funções para gerenciar pacotes do R e para criar, gerenciar e executar procedimentos armazenados e consultas em um SQL Server. Para obter detalhes, confira o arquivo LEIAME sqlmlutils do R.

Para obter informações sobre qualquer função do sqlmlutils, use a função help ou o operador ? do R. Por exemplo:

library(sqlmlutils)
help("sql_install.packages")

Próximas etapas

Para obter informações sobre pacotes R instalados, confira Obter informações do pacote R
Para obter ajuda para trabalhar com pacotes do R, confira Dicas para usar pacotes do R
Para obter informações sobre como instalar pacotes do Python, confira Instalar pacotes do Python com pip
Para obter mais informações sobre os Serviços de Machine Learning do SQL Server, confira O que é Serviços de Machine Learning do SQL Server (Python e R)?