Início Rápido: executar scripts simples do Python com o machine learning do SQL

Aplica-se a: SQL Server 2017 (14.x) e versões posteriores Instância Gerenciada de SQL do Azure

Neste início rápido, você executará um conjunto de scripts Python simples usando os Serviços de Machine Learning do SQL Server, os Serviços de Machine Learning da Instância Gerenciada de SQL do Azure ou os Clusters de Big Data do SQL Server. Você aprenderá a usar o procedimento armazenado sp_execute_external_script para executar o script em uma instância do SQL Server.

Pré-requisitos

Para executar este início rápido, você precisará dos pré-requisitos a seguir.

• Um banco de dados SQL em uma destas plataformas:

  • Serviços de Machine Learning do SQL Server. Para instalá-lo, confira o Guia de instalação do Windows ou o Guia de instalação do Linux.
  • Clusters de Big Data do SQL Server 2019. Veja como habilitar os Serviços de Machine Learning em Clusters de Big Data do SQL Server 2019.
  • Serviços de Machine Learning da Instância Gerenciada de SQL do Azure. Para obter informações, confira a Visão geral dos Serviços de Machine Learning da Instância Gerenciada de SQL do Azure.

• Uma ferramenta para executar consultas SQL que contenham scripts Python. Este início rápido usa o Azure Data Studio.

Executar um script simples

Para executar um script Python, você o passará como um argumento para o procedimento armazenado do sistema, sp_execute_external_script. Esse procedimento armazenado do sistema inicia o runtime do Python no contexto do machine learning do SQL, transmite dados para o Python, gerencia as sessões de usuário do Python com segurança e retorna todos os resultados para o cliente.

Nas etapas seguintes, você executará esse script Python de exemplo em seu banco de dados:

a = 1
b = 2
c = a/b
d = a*b
print(c, d)

1. Abra uma nova janela de consulta no Azure Data Studio conectado à sua instância SQL.

2. Passe o script Python completo para o procedimento armazenado sp_execute_external_script.

   O script é passado por meio do argumento @script. Tudo dentro do argumento @script deve ser um código Python válido.

   EXECUTE sp_execute_external_script @language = N'Python'
       , @script = N'
   a = 1
   b = 2
   c = a/b
   d = a*b
   print(c, d)
   '
   

3. O resultado correto é calculado e a função print do Python retorna o resultado para a janela Mensagens.

   O resultado deve ser semelhante ao mostrado a seguir.

   Resultados

   STDOUT message(s) from external script:
   0.5 2
   

Executar um script de Olá, Mundo

Um script de exemplo típico é aquele que apenas gera a cadeia de caracteres "Olá, Mundo". Execute o comando a seguir.

EXECUTE sp_execute_external_script @language = N'Python'
    , @script = N'OutputDataSet = InputDataSet'
    , @input_data_1 = N'SELECT 1 AS hello'
WITH RESULT SETS(([Hello World] INT));
GO

As entradas para o procedimento armazenado sp_execute_external_script incluem:

Entrada	Descrição
@language	define a extensão da linguagem a ser chamada, neste caso, Python
@script	define os comandos passados para o runtime do Python. Todo o script Python deve ser colocado neste argumento como texto Unicode. Você também pode adicionar texto a uma variável do tipo nvarchar e chamar a variável
@input_data_1	dados retornados pela consulta, transmitidos ao runtime do Python, que retorna os dados como uma estrutura de dados
WITH RESULT SETS	cláusula que define o esquema da tabela de dados retornada para o machine learning do SQL, adicionando "Olá, Mundo" com o nome da coluna, int para o tipo de dados

O comando gera o seguinte texto:

Olá, Mundo
1

Use entradas e saídas

Por padrão, sp_execute_external_script aceita um único conjunto de dados como entrada, que normalmente você fornece na forma de uma consulta SQL válida. Em seguida, ele retorna uma única estrutura de dados do Python como saída.

Por enquanto, usaremos as variáveis de entrada e saída padrão de sp_execute_external_script: InputDataSet e OutputDataSet.

1. Crie uma pequena tabela de dados de teste.

   CREATE TABLE PythonTestData (col1 INT NOT NULL)
   
   INSERT INTO PythonTestData
   VALUES (1);
   
   INSERT INTO PythonTestData
   VALUES (10);
   
   INSERT INTO PythonTestData
   VALUES (100);
   GO
   

2. Use a instrução SELECT para consultar a tabela.

   SELECT *
   FROM PythonTestData
   

   Resultados

   

3. Execute o script Python a seguir. Ele recupera os dados da tabela usando a instrução SELECT, passa-os pelo runtime do Python e retorna os dados como uma estrutura de dados. A cláusula WITH RESULT SETS define o esquema da tabela de dados retornada para o SQL, adicionando o nome de coluna NewColName.

   EXECUTE sp_execute_external_script @language = N'Python'
       , @script = N'OutputDataSet = InputDataSet;'
       , @input_data_1 = N'SELECT * FROM PythonTestData;'
   WITH RESULT SETS(([NewColName] INT NOT NULL));
   

   Resultados

   

4. Agora, altere os nomes das variáveis de entrada e de saída. Os nomes padrão das variáveis de entrada e de saída são InputDataSet e OutputDataSet, respectivamente. O script a seguir altera os nomes para SQL_in e SQL_out:

   EXECUTE sp_execute_external_script @language = N'Python'
       , @script = N'SQL_out = SQL_in;'
       , @input_data_1 = N'SELECT 12 as Col;'
       , @input_data_1_name  = N'SQL_in'
       , @output_data_1_name = N'SQL_out'
   WITH RESULT SETS(([NewColName] INT NOT NULL));
   

   Observe que o Python diferencia maiúsculas de minúsculas. As variáveis de entrada e saída usadas no script Python (SQL_out, SQL_in) precisam corresponder aos nomes definidos com @input_data_1_name e @output_data_1_name, incluindo maiúsculas e minúsculas.

   Dica

   Só é possível passar um conjunto de dados de entrada como parâmetro, e você pode retornar apenas um conjunto de dados. No entanto, você pode chamar outros conjuntos de dados no código do Python e retornar saídas de outros tipos, além do conjunto de dados. Você também pode adicionar a palavra-chave OUTPUT a qualquer parâmetro para que ele retorne com os resultados.

5. Você também pode gerar valores usando apenas o script Python sem dados de entrada (@input_data_1 está definido como em branco).

   O script a seguir gera o texto "Olá" e "mundo".

   EXECUTE sp_execute_external_script @language = N'Python'
       , @script = N'
   import pandas as pd
   mytextvariable = pandas.Series(["hello", " ", "world"]);
   OutputDataSet = pd.DataFrame(mytextvariable);
   '
       , @input_data_1 = N''
   WITH RESULT SETS(([Col1] CHAR(20) NOT NULL));
   

   Resultados

   @script como entrada" />

Dica

O Python usa espaços à esquerda para agrupar instruções. Assim, quando o script do Python incorporado abranger várias linhas, como no script anterior, não tente recuar os comandos do Python para colocá-los em linha com os comandos do SQL. Por exemplo, este script produzirá um erro:

EXECUTE sp_execute_external_script @language = N'Python'
      , @script = N'
      import pandas as pd
      mytextvariable = pandas.Series(["hello", " ", "world"]);
      OutputDataSet = pd.DataFrame(mytextvariable);
      '
      , @input_data_1 = N''
WITH RESULT SETS(([Col1] CHAR(20) NOT NULL));

Verificar a versão do Python

Se você quiser ver qual versão do Python está instalada no servidor, execute o script a seguir.

EXECUTE sp_execute_external_script @language = N'Python'
    , @script = N'
import sys
print(sys.version)
'
GO

A função print do Python retorna a versão para a janela Mensagens. Na saída de exemplo abaixo, você pode ver que, nesse caso, a versão 3.5.2 do Python está instalada.

Resultados

STDOUT message(s) from external script:
3.5.2 |Continuum Analytics, Inc.| (default, Jul  5 2016, 11:41:13) [MSC v.1900 64 bit (AMD64)]

Listar pacotes do Python

A Microsoft fornece vários pacotes Python pré-instalados com os Serviços de Machine Learning do SQL Server 2016 (13.x), do SQL Server 2017 (14.x) e do SQL Server 2019 (15.x). No SQL Server 2022 (16.x), você pode baixar e instalar todos os runtimes e pacotes personalizados do Python desejados.

Para ver uma lista de quais pacotes do Python estão instalados, incluindo a versão, execute o script a seguir.

EXECUTE sp_execute_external_script @language = N'Python'
    , @script = N'
import pkg_resources
import pandas
dists = [str(d) for d in pkg_resources.working_set]
OutputDataSet = pandas.DataFrame(dists)
'
WITH RESULT SETS(([Package] NVARCHAR(max)))
GO

A lista é do pkg_resources.working_set no Python e retornada para o SQL como uma estrutura de dados.

Próximas etapas

Para saber como usar estruturas de dados ao usar o Python no aprendizado de máquina do SQL Server, siga este início rápido:

Início Rápido: objetos e estruturas de dados usando Python