Início Rápido: Conectar-se a um banco de dados SQL de um Jupyter Notebook

Neste guia de início rápido, use o Jupyter Notebook no Visual Studio Code para extrair insights de negócios rapidamente. Use o mssql-python driver do Python para conectar ao seu banco de dados SQL, ler os dados e então formatá-los para uso em e-mails, relatórios e apresentações.

O mssql-python driver não requer nenhuma dependência externa em computadores Windows. O driver instala tudo o que precisa com uma única pip instalação, permitindo que você use a versão mais recente do driver para novos scripts sem quebrar outros scripts que você não tem tempo para atualizar e testar.

Documentação | Código-fonte | Pacote (PyPI) | Visual Studio Code

Pré-requisitos

Criar um banco de dados SQL

Crie ou conecte-se a um banco de dados SQL em uma das seguintes plataformas:

Criar o projeto e executar o código

Criar um novo projeto

  1. Abra um prompt de comando no diretório de desenvolvimento. Se você não tiver um, crie um novo diretório, como python ou scripts. Evite pastas no seu OneDrive, pois a sincronização pode interferir no gerenciamento do seu ambiente virtual.

  2. Crie um novo projeto com uv.

    uv init jupyter-notebook-qs
cd jupyter-notebook-qs

Adicionar dependências

No mesmo diretório, instale os pacotes mssql-python, python-dotenv, rich, pandas e matplotlib. Em seguida, adicione ipykernel e uv como dependências de desenvolvimento. O VS Code exige ipykernel para executar células de notebook e uv para gerenciar pacotes de dentro das células do notebook.

uv add mssql-python python-dotenv rich pandas matplotlib
uv add --dev ipykernel
uv add --dev uv

Iniciar o Visual Studio Code

No mesmo diretório, execute o comando a seguir.

code .

Atualizar pyproject.toml

  1. O pyproject.toml contém os metadados do projeto.

  2. Atualize a descrição para ser mais descritiva.

    description = "A quick example using the mssql-python driver and Jupyter Notebooks."

  3. Salve e feche o arquivo.

Salvar a cadeia de conexão

  1. Abra o .gitignore arquivo e adicione uma exclusão para .env arquivos. Seu arquivo deve ser semelhante a este exemplo. Salve-o e feche-o quando terminar.

    # Python-generated files
__pycache__/
*.py[oc]
build/
dist/
wheels/
*.egg-info

# Virtual environments
.venv

# Connection strings and secrets
.env

  2. No diretório atual, crie um novo arquivo chamado .env.

  3. No arquivo .env, adicione uma entrada para sua string de conexão chamada SQL_CONNECTION_STRING. Substitua o exemplo aqui pelo valor real da cadeia de conexão.

    SQL_CONNECTION_STRING="Server=<server_name>;Database=<database_name>;Encrypt=yes;TrustServerCertificate=no;Authentication=ActiveDirectoryInteractive"

    Dica

    A cadeia de conexão usada aqui depende em grande parte do tipo de banco de dados SQL ao qual você está se conectando. Se você estiver se conectando a um Banco de Dados SQL do Azure ou a um banco de dados SQL no Fabric, use a cadeia de conexão ODBC na guia cadeias de conexão. Talvez seja necessário ajustar o tipo de autenticação dependendo do seu cenário. Para obter mais informações sobre cadeias de conexão e sua sintaxe, consulte a referência de sintaxe da cadeia de conexão.

Criar um Jupyter Notebook

  1. Selecione Arquivo e, em seguida, Novo Arquivo e Jupyter Notebook na lista. Um novo bloco de anotações é aberto.

  2. Selecione Arquivo e, em seguida, Salve como... e dê um nome ao novo bloco de anotações.

  3. Adicione as seguintes importações na primeira célula.

    from os import getenv
from mssql_python import connect
from dotenv import load_dotenv
from rich.console import Console
from rich.table import Table
import pandas as pd
import matplotlib.pyplot as plt

  4. Use o botão + Markdown na parte superior do bloco de anotações para adicionar uma nova célula markdown.

  5. Adicione o texto a seguir à nova célula markdown.

    ## Define queries for use later

  6. Selecione a marca de seleção na barra de ferramentas da célula ou use os atalhos Ctrl+Enter de teclado ou Shift+Enter para renderizar a célula markdown.

  7. Use o botão + Código na parte superior do bloco de anotações para adicionar uma nova célula de código.

  8. Adicione o código a seguir à nova célula de código.

    SQL_QUERY_ORDERS_BY_CUSTOMER = """
SELECT TOP 5
c.CustomerID,
c.CompanyName,
COUNT(soh.SalesOrderID) AS OrderCount
FROM
SalesLT.Customer AS c
LEFT OUTER JOIN SalesLT.SalesOrderHeader AS soh
ON c.CustomerID = soh.CustomerID
GROUP BY
c.CustomerID,
c.CompanyName
ORDER BY
OrderCount DESC;
"""

SQL_QUERY_SPEND_BY_CATEGORY = """
select top 10
pc.Name as ProductCategory,
SUM(sod.OrderQty * sod.UnitPrice) as Spend
from SalesLT.SalesOrderDetail sod
inner join SalesLT.SalesOrderHeader soh on sod.salesorderid = soh.salesorderid
inner join SalesLT.Product p on sod.productid = p.productid
inner join SalesLT.ProductCategory pc on p.ProductCategoryID = pc.ProductCategoryID
GROUP BY pc.Name
ORDER BY Spend;
"""

Exibir resultados em uma tabela

  1. Use o botão + Markdown na parte superior do bloco de anotações para adicionar uma nova célula markdown.

  2. Adicione o texto a seguir à nova célula markdown.

    ## Print orders by customer and display in a table

  3. Selecione a marca de seleção na barra de ferramentas da célula ou use os atalhos Ctrl+Enter de teclado ou Shift+Enter para renderizar a célula markdown.

  4. Use o botão + Código na parte superior do bloco de anotações para adicionar uma nova célula de código.

  5. Adicione o código a seguir à nova célula de código.

    load_dotenv()
with connect(getenv("SQL_CONNECTION_STRING")) as conn: # type: ignore
    with conn.cursor() as cursor:
        cursor.execute(SQL_QUERY_ORDERS_BY_CUSTOMER)
        if cursor:
            table = Table(title="Orders by Customer")
            # https://rich.readthedocs.io/en/stable/appendix/colors.html
            table.add_column("Customer ID", style="bright_blue", justify="center")
            table.add_column("Company Name", style="bright_white", justify="left")
            table.add_column("Order Count", style="bold green", justify="right")

            records = cursor.fetchall()

            for r in records:
                table.add_row(f"{r.CustomerID}",
                                f"{r.CompanyName}", f"{r.OrderCount}")

            Console().print(table)

    Dica

    No macOS, tanto ActiveDirectoryInteractive quanto ActiveDirectoryDefault funcionam para autenticação do Microsoft Entra. ActiveDirectoryInteractive solicita que você faça login toda vez que executar o script. Para evitar repetidos prompts de login, faça login uma vez pela CLI do Azure executando az login, depois use ActiveDirectoryDefault, que reutiliza a credencial em cache.

  6. Use o botão Executar Tudo na parte superior do notebook para executá-lo.

  7. Selecione o kernel jupyter-notebook-qs quando solicitado.

Exibir resultados em um gráfico

  1. Examine a saída da última célula. Você deve ver uma tabela com três colunas e cinco linhas.

  2. Use o botão + Markdown na parte superior do bloco de anotações para adicionar uma nova célula markdown.

  3. Adicione o texto a seguir à nova célula markdown.

    ## Display spend by category in a horizontal bar chart

  4. Selecione a marca de seleção na barra de ferramentas da célula ou use os atalhos Ctrl+Enter de teclado ou Shift+Enter para renderizar a célula markdown.

  5. Use o botão + Código na parte superior do bloco de anotações para adicionar uma nova célula de código.

  6. Adicione o código a seguir à nova célula de código.

    with connect(getenv("SQL_CONNECTION_STRING")) as conn: # type: ignore
    data = pd.read_sql_query(SQL_QUERY_SPEND_BY_CATEGORY, conn)
    # Set the style - use print(plt.style.available) to see all options
    plt.style.use('seaborn-v0_8-notebook')
    plt.barh(data['ProductCategory'], data['Spend'])

  7. Use o botão Executar Célula ou Ctrl+Alt+Enter execute a célula.

  8. Revise os resultados. Torne este bloco de anotações seu.

Próximas Etapas 

Use estes artigos para continuar construindo:

  • Construa strings de conexão para configurar conexões para diferentes tipos de bancos de dados SQL e métodos de autenticação.
  • Integração com pandas para carregar resultados de consulta diretamente em DataFrames para análise em notebooks.
  • Integração do Arrow para trabalhar com dados colunares usando o Apache Arrow para análises de alto desempenho.

Construir cadeias de conexão

  • Last updated on