在 Azure Synapse Analytics 中建立、開發及維護 Synapse 筆記本

Synapse 筆記本是一個 web 介面,可讓您建立包含即時程式碼、視覺效果和敘述文字的檔案。 筆記本是驗證想法和使用快速實驗從您的資料取得見解的絕佳位置。 筆記本也廣泛用於資料準備、資料視覺效果、機器學習和其他巨量資料案例。

使用 Synapse 筆記本,您可以:

  • 無須設定即可開始使用。
  • 使用內建的企業安全性功能保護資料的安全。
  • 分析包括原始格式 (CSV、txt、JSON 等)、經處理的檔案格式 (parquet、Delta Lake、ORC 等),以及針對 Spark 和 SQL 的 SQL 表格式資料檔案等各種資料。
  • 透過增強的撰寫功能和內建的資料視覺效果,提高生產力。

本文說明如何使用 Synapse Studio 中的筆記本。

新筆記本體驗的預覽

Synapse 團隊將新的筆記本元件帶入 Synapse Studio 中,為 Microsoft 客戶提供一致的筆記本體驗,並最大化探索能力、生產力、共用和共同作業。 新的筆記本體驗已備妥可供預覽。 檢查筆記本工具列中的 [ 預覽功能 ] 按鈕以開啟。 下表會捕捉現有筆記本 (的功能比較,因此稱為「傳統筆記本」 ) 新的預覽版本。

功能 傳統筆記本 預覽筆記本
% 執行 不支援
% 歷程記錄 不支援
% 載入 不支援
%% html 不支援
拖放以移動儲存格 不支援
內容) 的大綱 (資料表 不支援
變數瀏覽器 不支援
使用工具列按鈕格式化文字儲存格 無法使用
復原資料格作業 無法使用

建立 Notebook

建立筆記本的方法有兩種。 您可以建立新的筆記本,或從 物件總管 將現有的筆記本匯入至 Synapse 工作區。 Synapse 筆記本會辨識標準 Jupyter Notebook .IPYNB 檔案。

建立匯入筆記本

開發筆記本

筆記本是由儲存格組成,也就是個別的程式碼區塊或可獨立執行或作為群組執行的文字。

新增儲存格

有多種方式可將新的儲存格新增至您的筆記本。

  1. 展開左上方的 [+ 儲存格] 按鈕,然後選取 [加入程式碼儲存格] 或 [加入文字儲存格]。

    add-cell-with-cell-button

  2. 將游標停留在兩個儲存格之間的空間,然後選取 [新增程式碼] 或 [新增文字]。

    add-cell-between-space

  3. 使用 命令模式下的快速鍵。 按下 [A],將儲存格插入目前的儲存格上方。 按下 [B],將儲存格插入目前的儲存格下方。

設定主要語言

Synapse 筆記本支援四種 Apache Spark 語言:

  • pySpark (Python)
  • Spark (Scala)
  • SparkSQL
  • 適用於 Apache Spark 的 .NET (C#)

您可以從頂端命令列的下拉式清單中,為新加入的儲存格設定主要語言。

default-synapse-language

使用多種語言

您可以在儲存格的開頭指定正確的語言 magic 命令,以便在同個筆記本中使用多種語言。 下表列出用來切換儲存格語言的 magic 命令。

Magic 命令 Language 描述
%%pyspark Python 針對 Spark 內容執行 Python 查詢。
%%spark Scala 針對 Spark 內容執行 Scala 查詢。
%%sql SparkSQL 針對 Spark 內容執行 SparkSQL 查詢。
%%csharp 適用於 Spark C# 的 .NET 針對 Spark 內容執行 適用於 Spark C# 的 .NET 查詢。

下圖是如何使用 %%pyspark magic 命令,或在 Spark(Scala) 筆記本中使用 %%sql magic 命令的 SparkSQL 查詢,以便撰寫 PySpark 查詢的範例。 請注意,筆記本的主要語言會設定為 pySpark。

Synapse spark 魔術命令

<a name="use-temp-tables-to-reference-data-across-languages">使用暫存資料表跨語言參考資料

您無法直接在 Synapse 筆記本中的不同語言參考資料或變數。 在 Spark 中,可以跨語言參考暫存資料表。 以下範例說明如何使用 Spark 暫存資料表做為因應措施,讀取 PySparkSparkSQL 中的 Scala 資料框架。

  1. 在儲存格1中,使用 Scala 從 SQL 集區連接器讀取資料框架並建立臨時表。

    %%scala
    val scalaDataFrame = spark.read.sqlanalytics(&quot;mySQLPoolDatabase.dbo.mySQLPoolTable")
    scalaDataFrame.createOrReplaceTempView( "mydataframetable" )
    
  2. 在儲存格 2 中,使用 Spark SQL 查詢資料。

    %%sql
    SELECT * FROM mydataframetable
    
  3. 在儲存格 3 中,使用 PySpark 中的資料。

    %%pyspark
    myNewPythonDataFrame = spark.sql("SELECT * FROM mydataframetable")
    

整合式開發環境 (IDE) 樣式的 IntelliSense

Synapse 筆記本會與摩納哥編輯器整合,以將 IDE 樣式的 IntelliSense 帶入儲存格編輯器。 語法醒目提示、錯誤標記和自動程式碼完成可協助您更快速地撰寫程式碼及找出問題。

IntelliSense 功能在不同語言的成熟度層級不同。 使用下表來查看支援的功能。

Languages 語法醒目提示 語法錯誤標記 語法程式碼完成 變數程式碼完成 系統函數程式碼完成 使用者函式程式碼完成 智慧縮排 程式碼摺疊功能
PySpark (Python)
Spark (Scala) - - -
SparkSQL - - - - - -
適用於 Spark (C#) 的 .NET - - - - - - -

程式碼片段

Synapse 筆記本提供的程式碼片段可讓您更輕鬆地輸入常用的程式碼模式,例如設定您的 Spark 會話、以 Spark 資料框架的形式讀取資料,或使用 matplotlib 等繪圖圖表。

程式碼片段會與其他建議混合出現在 IntelliSense 中。 程式碼片段的內容與程式碼儲存格語言一致。 您可以在程式碼資料格編輯器的程式碼片段標題中輸入 程式碼片段 或任何關鍵字,以查看可用的程式碼片段。 例如,輸入 read 可以看到程式碼片段清單,從各種資料來源讀取資料。

Synapse 程式碼片段

使用工具列按鈕格式化文字儲存格

您可以使用 [文字儲存格] 工具列中的 [格式] 按鈕來執行常見的 Markdown 動作。 其中包含粗體文字、斜體文字、插入程式碼片段、插入未排序的清單、插入已排序的清單,以及從 URL 插入影像。

Synapse 文字資料格工具列

復原儲存格作業

選取 [ 復原 ] 按鈕,或按 Ctrl + Z 以撤銷最新的資料格運算。 現在您可以復原最近的 20 個歷史儲存格動作。

Synapse 復原儲存格

移動儲存格

選取省略號 ( ... ) 以存取最右邊的其他 [資料格動作] 功能表。 然後選取 [向上移動儲存格] 或 [向下移動儲存格] 以移動目前的儲存格。

您也可以使用 命令模式下的快速鍵。 按下 Ctrl+Alt+↑ 上移目前的儲存格。 按下 Ctrl+Alt+↓ 下移目前的儲存格。

move-a-cell

刪除儲存格

若要刪除資料格,請選取省略號 ( ... ) 以存取最右邊的其他儲存格動作功能表,然後選取 [ 刪除資料格]。

您也可以使用 命令模式下的快速鍵。 按下 D,D 以刪除目前的儲存格。

delete-a-cell

摺疊儲存格輸入

選取目前儲存格底部的箭號按鈕來折迭它。 若要展開,請在資料格折迭時選取箭號按鈕。

collapse-cell-input

摺疊儲存格輸出

選取目前資料格輸出左上角的 [折迭 輸出 ] 按鈕,以折迭它。 若要展開它,請選取 [在資料格輸出折迭時 顯示儲存格輸出 ]。

collapse-cell-output

筆記本大綱

不支援。

執行筆記本

您可以個別或一次全部在您的筆記本中執行程式碼儲存格。 每個儲存格的狀態和進度都會在筆記本中表示。

執行儲存格

有數種方式可以在儲存格中執行程式碼。

  1. 將游標停留在您想要執行的儲存格上,然後選取 [執行儲存格] 按鈕,或按下 Ctrl+Enter

    run-cell-1

  2. 使用 命令模式下的快速鍵。 按下 Shift+Enter 以執行目前的儲存格,然後選取下方的儲存格。 按下 Alt+Enter 以執行目前的儲存格,並在下方插入新的儲存格。


執行所有儲存格

選取 [ 全部執行 ] 按鈕,以依序執行目前筆記本中的所有儲存格。

run-all-cells

執行上方或下方所有儲存格

若要存取最右邊的其他儲存格動作功能表,請選取省略號 (...) 。然後,選取 [ 執行上方儲存格 ],以依序執行目前的資料格。 選取 [執行下方的儲存格],依序執行目前儲存格下方的所有儲存格。

run-cells-above-or-below

取消所有執行中的儲存格

選取 [ 全部取消 ] 按鈕,取消執行中的儲存格或等候佇列中的資料格。 全部取消-儲存格

筆記本參考

不支援。

變數瀏覽器

不支援。

儲存格狀態指標

儲存格下方會逐步顯示儲存格執行狀態,以協助您檢視目前的進度。 儲存格執行完成之後,會顯示包含總持續時間和結束時間的執行摘要,並保留在該處供日後參考。

cell-status

Spark 進度指示器

Synapse 筆記本純粹以 Spark 為基礎。 程式碼資料格會從遠端在無伺服器 Apache Spark 集區上執行。 系統隨即會提供具有即時進度列的 Spark 作業進度列指示器,以協助您瞭解作業執行狀態。 每個作業或階段的工作數目可協助您識別 spark 作業的平行層級。 您也可以透過選取作業 (或階段) 名稱的連結,深入瞭解特定工作的 Spark UI (或階段) 。

spark-progress-indicator

Spark 工作階段設定

您可以在 [設定工作階段] 中指定要提供給目前 Spark 工作階段的執行程式逾時時間、數目和大小。 重新啟動 Spark 工作階段,設定變更才會生效。 所有快取的筆記本變數都會清除。

會話管理

Spark 會話設定魔術命令

您也可以透過魔術命令 %% configure 來指定 spark 會話設定。 Spark 會話需要重新開機才能使設定生效。 建議您在筆記本開頭執行 %% 的設定 。 以下是範例, https://github.com/cloudera/livy#request-body 如需有效參數的完整清單,請參閱。

%%configure -f
{
    to config the session.
    "driverMemory":"2g",
    "driverCores":3,
    "executorMemory":"2g",
    "executorCores":2,
    "jars":["myjar1.jar","myjar.jar"],
    "conf":{
        "spark.driver.maxResultSize":"10g"
    }
}

注意

Synapse 管線不支援 Spark 會話設定魔術命令。

將資料帶入筆記本

您可以從 Azure Blob 儲存體、Azure Data Lake Store Gen 2 和 SQL 集區載入資料,如下列程式碼範例所示。

從 Azure Data Lake Store Gen2 讀取 CSV 做為 Spark 資料框架

from pyspark.sql import SparkSession
from pyspark.sql.types import *
account_name = "Your account name"
container_name = "Your container name"
relative_path = "Your path"
adls_path = 'abfss://%s@%s.dfs.core.windows.net/%s' % (container_name, account_name, relative_path)

df1 = spark.read.option('header', 'true') \
                .option('delimiter', ',') \
                .csv(adls_path + '/Testfile.csv')

以 Spark 資料框架的形式從 Azure Blob 儲存體讀取 CSV


from pyspark.sql import SparkSession

# Azure storage access info
blob_account_name = 'Your account name' # replace with your blob name
blob_container_name = 'Your container name' # replace with your container name
blob_relative_path = 'Your path' # replace with your relative folder path
linked_service_name = 'Your linked service name' # replace with your linked service name

blob_sas_token = mssparkutils.credentials.getConnectionStringOrCreds(linked_service_name)

# Allow SPARK to access from Blob remotely

wasb_path = 'wasbs://%s@%s.blob.core.windows.net/%s' % (blob_container_name, blob_account_name, blob_relative_path)

spark.conf.set('fs.azure.sas.%s.%s.blob.core.windows.net' % (blob_container_name, blob_account_name), blob_sas_token)
print('Remote blob path: ' + wasb_path)

df = spark.read.option("header", "true") \
            .option("delimiter","|") \
            .schema(schema) \
            .csv(wasbs_path)

讀取主要儲存體帳戶中的資料

您可以直接存取主要儲存體帳戶中的資料。 不需要提供祕密金鑰。 在 [資料總管] 中,以滑鼠右鍵按一下檔案,然後選取 [新筆記本],以檢視已自動產生資料解壓縮的新筆記本。

data-to-cell

儲存筆記本

您可以將單一筆記本或所有筆記本儲存在工作區中。

  1. 若要儲存對單一筆記本所做的變更,請在筆記本命令列上選取 [發佈] 按鈕。

    publish-notebook

  2. 若要儲存工作區中的所有筆記本,請選取 [工作區] 命令列上的 [全部發佈] 按鈕。

    publish-all

在筆記本屬性中,您可以設定是否要在儲存時包含儲存格輸出。

notebook-properties

Magic 命令

您可以在 Synapse 筆記本中使用熟悉的 Jupyter 魔術命令。 請檢查下列清單,做為目前可用的魔術命令。 請在 GitHub 上告訴我們您的使用案例,讓我們可以繼續建立更多魔術命令以符合您的需求。

注意

Synapse 管線中僅支援下列魔術命令:%% pyspark、%% spark、%% csharp、%% sql。

可用的行 magic:%lsmagic, %time, %timeit

可用的儲存格 magic: %% 時間%% timeit.exe%% capture%% writefile%% sql%% pyspark%% spark%% csharp%% 設定

整合筆記本

將筆記本新增至管線

選取右上角的 [ 新增至管線 ] 按鈕,將筆記本新增至現有的管線或建立新的管線。

將筆記本新增至管線

指定參數儲存格

若要將您的筆記本參數化,請選取省略號 ( ... ) 以存取最右邊的其他 [儲存格動作] 功能表。 然後選取 [ 切換參數資料格 ],將資料格指定為 [參數] 儲存格。

切換參數

Azure Data Factory 會尋找參數儲存格,並將此資料格視為在執行時間傳入之參數的預設值。 執行引擎會使用輸入參數,在參數資料格下方新增資料格,以便覆寫預設值。 如果未指定參數儲存格,插入的儲存格將會插入到筆記本的頂端。

從管線指派參數值

建立具有參數的筆記本之後,您可以從具有 Synapse 筆記本活動的管線執行它。 將活動新增至管線畫布之後,您將能夠在 [設定] 索引標籤的 [基底參數] 區段下設定參數值。

指派參數

指派參數值時,您可以使用 管線運算式語言系統變數

快速鍵

類似于 Jupyter 筆記本,Synapse 筆記本具有模式使用者介面。 鍵盤會根據筆記本儲存格所在的模式來執行不同的動作。 Synapse 筆記本支援指定程式碼資料格的下列兩種模式:命令模式和編輯模式。

  1. 沒有文字游標提示您輸入時,儲存格就會處於命令模式。 儲存格處於命令模式時,您可以將筆記本當做整體編輯,但無法輸入個別的儲存格。 按下 ESC 或使用滑鼠選取資料格的編輯器區域以外的地方,進入命令模式。

    command-mode

  2. 編輯模式會以文字游標指示,提示您在編輯器區域中輸入。 當儲存格處於編輯模式時,您可以在資料格中輸入資料格。 按下 Enter 或使用滑鼠選取儲存格的編輯器區域,進入編輯模式。

    edit-mode

命令模式下的快速鍵

您可以使用下列按鍵快速鍵,更輕鬆地流覽和執行 Synapse 筆記本中的程式碼。

動作 Synapse 筆記本快速鍵
執行目前的儲存格並在下方選取 Shift+Enter
執行目前的儲存格並在下方插入 Alt+Enter
選取上方儲存格 上移
選取下方儲存格 向下
在上方插入儲存格 A
在下方插入儲存格 B
展開上方選取的儲存格 Shift+Up
展開下方選取的儲存格 Shift+Down
向上移動儲存格 Ctrl+Alt+↑
向下移動儲存格 Ctrl+Alt+↓
刪除選取的儲存格 D,D
切換至編輯模式 Enter

編輯模式下的快速鍵

您可以使用下列按鍵快速鍵,在編輯模式下,更輕鬆地流覽和執行 Synapse 筆記本中的程式碼。

動作 Synapse 筆記本快速鍵
向上移動資料指標 上移
向下移動資料指標 向下
復原 Ctrl + Z
取消復原 Ctrl + Y
註解/取消註解 Ctrl + /
刪除此前的文字 Ctrl + 退格鍵
刪除此後的文字 Ctrl + Delete
移至儲存格開端 Ctrl + Home
移至儲存格末端 Ctrl + End
往左移一個單字 Ctrl + 向左鍵
往右移一個單字 Ctrl + 向右鍵
全選 Ctrl + A
縮排 Ctrl +]
Dedent Ctrl + [
切換到命令類型 Esc

後續步驟