Gunakan perintah dan fitur notebook bawaan di Azure Cosmos DB Python notebooks (pratinjau)

  • Artikel
  • 5 menit untuk membaca

BERLAKU UNTUK: SQL API

Notebook Jupyter bawaan di Azure Cosmos DB memudahkan Anda menganalisis dan memvisualisasikan data Anda dari portal Microsoft Azure. Artikel ini menjelaskan cara menggunakan perintah dan fitur notebook bawaan untuk melakukan operasi umum di Python notebook.

Memasang paket baru

Setelah mengaktifkan dukungan notebook untuk akun Azure Cosmos, Anda bisa membuka notebook baru dan memasang paket.

Di sel kode baru, sisipkan dan jalankan kode berikut, ganti PackageToBeInstalleddengan paket Python yang diinginkan.

import sys
!{sys.executable} -m pip install PackageToBeInstalled --user

Paket ini akan tersedia untuk digunakan dari notebook apa pun di ruang kerja akun Azure Cosmos.

Tip

Jika notebook Anda memerlukan paket kustom, kami menyarankan agar menambahkan sel di notebook Anda untuk memasang paket, karena paket dihapus jika Anda mereset ruang kerja.

Menjalankan kueri SQL

Anda dapat menggunakan %%sql perintah ajaib untuk menjalankankueri SQL terhadap kontainer apa pun di akun Anda. Gunakan sintaks:

%%sql --database {database_id} --container {container_id}
{Query text}
  • Mengganti{database_id} dan {container_id} dengan nama database dan kontainer di akun Cosmos Anda. Jika argumen --database dan --container tidak disediakan, kueri akan dijalankan pada database dan kontainer default.
  • Anda dapat menjalankan kueri SQL yang valid di Azure Cosmos DB. Teks kueri harus berada di baris baru.

Contohnya:

%%sql --database RetailDemo --container WebsiteData
SELECT c.Action, c.Price as ItemRevenue, c.Country, c.Item FROM c

Jalankan %%sql? dalam sel untuk melihat dokumentasi bantuan untuk perintah ajaib sql di notebook.

Menjalankan kueri dan output SQL ke Pandas DataFrame

Anda dapat meng-output hasil kueri %%sql ke dalam Pandas DataFrame. Gunakan sintaks:

%%sql --database {database_id} --container {container_id} --output {outputDataFrameVar}
{Query text}
  • Mengganti{database_id} dan {container_id} dengan nama database dan kontainer di akun Cosmos Anda. Jika argumen --database dan --container tidak disediakan, kueri akan dijalankan pada database dan kontainer default.
  • Mengganti {outputDataFrameVar} dengan nama variabel DataFrame yang akan berisi hasil.
  • Anda dapat menjalankan kueri SQL yang valid di Azure Cosmos DB. Teks kueri harus berada di baris baru.

Contohnya:

%%sql --database RetailDemo --container WebsiteData --output df_cosmos
SELECT c.Action, c.Price as ItemRevenue, c.Country, c.Item FROM c

df_cosmos.head(10)

    Action    ItemRevenue    Country/Region    Item
0    Viewed    9.00    Tunisia    Black Tee
1    Viewed    19.99    Antigua and Barbuda    Flannel Shirt
2    Added    3.75    Guinea-Bissau    Socks
3    Viewed    3.75    Guinea-Bissau    Socks
4    Viewed    55.00    Czech Republic    Rainjacket
5    Viewed    350.00    Iceland    Cosmos T-shirt
6    Added    19.99    Syrian Arab Republic    Button-Up Shirt
7    Viewed    19.99    Syrian Arab Republic    Button-Up Shirt
8    Viewed    33.00    Tuvalu    Red Top
9    Viewed    14.00    Cabo Verde    Flip Flop Shoes

Mengatur database default untuk kueri

Anda bisa mengatur perintah database default %%sql yang akan digunakan untuk notebook. Mengganti {database_id} dengan nama database Anda.

%database {database_id}

Jalankan %database? dalam sel untuk melihat dokumentasi di notebook.

Mengatur kontainer default untuk kueri

Anda bisa mengatur perintah database default %%sql yang akan digunakan untuk notebook. Mengganti{container_id} dengan nama kontainer Anda.

%container {container_id}

Jalankan %container? dalam sel untuk melihat dokumentasi di notebook.

Mengunggah item JSON ke kontainer

Anda dapat menggunakan %%upload perintah ajaib untuk mengunggah data dari file JSON ke kontainer Azure Cosmos tertentu. Gunakan perintah berikut untuk mengunggah item:

%%upload --databaseName {database_id} --containerName {container_id} --url {url_location_of_file}
  • Mengganti{database_id} dan {container_id} dengan nama database dan kontainer di akun Azure Cosmos Anda. Jika argumen --database dan --container tidak disediakan, kueri akan dijalankan pada database dan kontainer default.
  • Mengganti {url_location_of_file} dengan lokasi file JSON Anda. File harus merupakan array obyek JSON yang berlaku dan seharusnya bisa diakses melalui Internet publik.

Contohnya:

%%upload --database databaseName --container containerName --url 
https://contoso.com/path/to/data.json

Documents successfully uploaded to ContainerName
Total number of documents imported : 2654
Total time taken : 00:00:38.1228087 hours
Total RUs consumed : 25022.58

Dengan statistik output, Anda dapat menghitung RU/dtk efektif yang digunakan untuk mengunggah item. Misalnya, jika 25.000 RU yang digunakan lebih dari 38 detik, RU/dtk yang efektif adalah 25.000 RU / 38 detik = 658 RU/dtk.

Anda bisa menyimpan file (seperti file CSV atau JSON) ke ruang kerja notebook lokal. Kami menyarankan agar Anda menambahkan sel di notebook Anda untuk menyimpan file. Anda dapat melihat file-file ini dari terminal terintegrasi di lingkungan notebook. Anda dapat menggunakan perintah "ls" untuk melihat file yang disimpan. Namun, file-file ini dihapus jika Anda mengatur ulang ruang kerja. Jadi, sebaiknya menggunakan penyimpanan persisten seperti GitHub atau akun penyimpanan daripada ruang kerja lokal.

Menjalankan notebook lain di notebook saat ini

Anda bisa menggunakan %%run perintah ajaib untuk menjalankan notebook lain di ruang kerja Anda dari notebook Anda saat ini. Gunakan sintaks:

%%run ./path/to/{notebookName}.ipynb

Mengganti {notebookName} dengan nama notebook yang ingin Anda jalankan. Notebook harus berada di 'Ruang Kerja Notebook Saya' saat ini.

Menggunakan penjelajah data nteract bawaan

Anda dapat menggunakan penjelajah data nteract bawaan untuk memfilter dan memvisualisasikan DataFrame. Untuk mengaktifkan fitur ini, atur opsi pd.options.display.html.table_schema ke True dan pd.options.display.max_rows ke nilai yang diinginkan (Anda dapat mengatur pd.options.display.max_rows ke None untuk menampilkan semua hasil).

import pandas as pd
pd.options.display.html.table_schema = True
pd.options.display.max_rows = None

df_cosmos.groupby("Item").size()

nteract data explorer

Menggunakan Python SDK bawaan

Versi 4 dari Azure Cosmos DB Python SDK untuk SQL API dipasang dan disertakan dalam lingkungan notebook untuk akun Azure Cosmos.

Gunakan instance bawaan cosmos_client untuk menjalankan operasi SDK apa pun.

Contohnya:

## Import modules as needed
from azure.cosmos.partition_key import PartitionKey

## Create a new database if it doesn't exist
database = cosmos_client.create_database_if_not_exists('RetailDemo')

## Create a new container if it doesn't exist
container = database.create_container_if_not_exists(id='WebsiteData', partition_key=PartitionKey(path='/CartID'))

Lihat Sampel Python SDK.

Penting

Python SDK bawaan hanya didukung untuk akun API SQL (Core). Untuk API lain, Anda harus memasang driver Python yang relevan yang sesuai dengan API.

Membuat instans cosmos_client kustom

Untuk fleksibilitas lebih lanjut, Anda dapat membuat instans cosmos_client kustom untuk:

  • Menyesuaikan kebijakan koneksi
  • Jalankan operasi terhadap akun Azure Cosmos yang berbeda dari yang Anda masuki

Anda dapat mengakses string koneksi dan kunci utama akun saat ini melalui variabel lingkungan.

import azure.cosmos.cosmos_client as cosmos
import azure.cosmos.documents as documents

# These should be set to a region you've added for Azure Cosmos DB
region_1 = "Central US" 
region_2 = "East US 2"

custom_connection_policy = documents.ConnectionPolicy()
custom_connection_policy.PreferredLocations = [region_1, region_2] # Set the order of regions the SDK will route requests to. The regions should be regions you've added for Cosmos, otherwise this will error.

# Create a new instance of CosmosClient, getting the endpoint and key from the environment variables
custom_client = cosmos.CosmosClient(url=COSMOS.ENDPOINT, credential=COSMOS.KEY, connection_policy=custom_connection_policy)

Mengakses titik akhir akun dan variabel env kunci utama

Anda bisa mengakses titik akhir bawaan dan kunci akun tempat notebook Anda berada.

endpoint = COSMOS.ENDPOINT
primary_key = COSMOS.KEY

Penting

Variabel COSMOS.ENDPOINT dan COSMOS.KEY hanya berlaku untuk SQL API. Untuk API lain, temukan titik akhir dan kunci di bilah String Koneksi atau Kunci di akun Azure Cosmos Anda.

Mereset ruang kerja notebook

Untuk mengatur ulangt ruang kerja notebook ke pengaturan default, pilih Reset Ruang Kerja pada bilah perintah. Cara Ini akan menghapus paket yang dipasang kustom dan memulai ulang server Jupyter. Notebook, file, dan sumber daya Azure Cosmos Anda tidak akan terpengaruh.

Reset notebooks workspace

Langkah berikutnya