Mengatur buku catatan dan memodulasi kode di buku catatan

Pelajari cara mengatur buku catatan dan memodulasi kode di buku catatan. Lihat contoh dan pahami kapan harus menggunakan metode alternatif untuk orkestrasi notebook.

Metode orkestrasi dan modularisasi kode

Tabel berikut membandingkan metode yang tersedia untuk mengatur buku catatan dan memodulasi kode di buku catatan.

%run vs. dbutils.notebook.run()

Perintah ini %run memungkinkan Anda menyertakan buku catatan lain dalam buku catatan. Anda dapat menggunakan %run untuk memodulasi kode Anda dengan menempatkan fungsi pendukung di notebook terpisah. Anda juga dapat menggunakannya untuk menggabungkan buku catatan yang menerapkan langkah-langkah dalam analisis. Saat Anda menggunakan %run, buku catatan yang dipanggil segera dijalankan dan fungsi serta variabel yang ditentukan di dalamnya menjadi tersedia di buku catatan panggilan.

API dbutils.notebook melengkapi %run karena memungkinkan Anda meneruskan parameter ke dan mengembalikan nilai dari notebook. Ini memungkinkan Anda untuk membangun alur kerja dan alur yang kompleks dengan dependensi. Misalnya, Anda bisa mendapatkan daftar file di direktori dan meneruskan nama ke buku catatan lain, yang tidak mungkin dengan %run. Anda juga dapat membuat alur kerja if-then-else berdasarkan nilai yang dikembalikan.

Tidak seperti %run, metode dbutils.notebook.run() ini memulai pekerjaan baru untuk menjalankan buku catatan.

Seperti semua API dbutils, metode ini hanya tersedia di Python dan Scala. Namun, Anda dapat menggunakan dbutils.notebook.run() untuk memanggil buku catatan R.

Gunakan %run untuk mengimpor buku catatan

Dalam contoh ini, notebook pertama menentukan fungsi, reverse, yang tersedia di notebook kedua setelah Anda menggunakan %run sihir untuk mengeksekusi shared-code-notebook.

Karena kedua notebook berada dalam direktori yang sama di ruang kerja, gunakan awalan ./ di ./shared-code-notebook untuk menunjukkan bahwa jalur harus ditentukan relatif terhadap notebook yang sedang berjalan. Anda dapat menata buku catatan pada direktori, seperti %run ./dir/notebook, atau menggunakan jalur absolut seperti %run /Users/username@organization.com/directory/notebook.

Menggunakan dbutils.notebook.run untuk memulai pekerjaan baru

Menjalankan buku catatan dan mengembalikan nilai keluarnya. Metode ini memulai pekerjaan singkat yang berjalan dengan segera.

Metode yang tersedia di dbutils.notebook API adalah run dan exit. Parameter dan nilai yang dikembalikan harus berupa string.

run(path: String, timeout_seconds: int, arguments: Map): String

Parameter timeout_seconds mengontrol batas waktu eksekusi (0 berarti tidak ada batas waktu). Panggilan ke run menghasilkan pengecualian jika belum selesai dalam waktu yang ditentukan. Jika Azure Databricks turun selama lebih dari 10 menit, menjalankan buku catatan gagal terlepas dari timeout_seconds.

Parameter arguments menetapkan nilai widget dari notebook target. Secara khusus, jika buku catatan yang Anda jalankan memiliki widget bernama A, dan Anda melewati pasangan ("A": "B") nilai kunci sebagai bagian dari parameter argumen ke panggilan run(), maka mengambil nilai widget A akan kembali "B". Anda dapat menemukan petunjuk untuk membuat dan bekerja dengan widget di artikel widget Databricks.

run Penggunaan

Python

dbutils.notebook.run("notebook-name", 60, {"argument": "data", "argument2": "data2", ...})

Scala

dbutils.notebook.run("notebook-name", 60, Map("argument" -> "data", "argument2" -> "data2", ...))

Mengirimkan data terstruktur antara buku catatan

Bagian ini mengilustrasikan cara meneruskan data terstruktur antar buku catatan.

Python

# Example 1 - returning data through temporary views.
# You can only return one string using dbutils.notebook.exit(), but since called notebooks reside in the same JVM, you can
# return a name referencing data stored in a temporary view.

## In callee notebook
spark.range(5).toDF("value").createOrReplaceGlobalTempView("my_data")
dbutils.notebook.exit("my_data")

## In caller notebook
returned_table = dbutils.notebook.run("LOCATION_OF_CALLEE_NOTEBOOK", 60)
global_temp_db = spark.conf.get("spark.sql.globalTempDatabase")
display(table(global_temp_db + "." + returned_table))

# Example 2 - returning data through DBFS.
# For larger datasets, you can write the results to DBFS and then return the DBFS path of the stored data.

## In callee notebook
dbutils.fs.rm("/tmp/results/my_data", recurse=True)
spark.range(5).toDF("value").write.format("parquet").save("dbfs:/tmp/results/my_data")
dbutils.notebook.exit("dbfs:/tmp/results/my_data")

## In caller notebook
returned_table = dbutils.notebook.run("LOCATION_OF_CALLEE_NOTEBOOK", 60)
display(spark.read.format("parquet").load(returned_table))

# Example 3 - returning JSON data.
# To return multiple values, you can use standard JSON libraries to serialize and deserialize results.

## In callee notebook
import json
dbutils.notebook.exit(json.dumps({
  "status": "OK",
  "table": "my_data"
}))

## In caller notebook
import json

result = dbutils.notebook.run("LOCATION_OF_CALLEE_NOTEBOOK", 60)
print(json.loads(result))

Scala

// Example 1 - returning data through temporary views.
// You can only return one string using dbutils.notebook.exit(), but since called notebooks reside in the same JVM, you can
// return a name referencing data stored in a temporary view.

/** In callee notebook */
sc.parallelize(1 to 5).toDF().createOrReplaceGlobalTempView("my_data")
dbutils.notebook.exit("my_data")

/** In caller notebook */
val returned_table = dbutils.notebook.run("LOCATION_OF_CALLEE_NOTEBOOK", 60)
val global_temp_db = spark.conf.get("spark.sql.globalTempDatabase")
display(table(global_temp_db + "." + returned_table))

// Example 2 - returning data through DBFS.
// For larger datasets, you can write the results to DBFS and then return the DBFS path of the stored data.

/** In callee notebook */
dbutils.fs.rm("/tmp/results/my_data", recurse=true)
sc.parallelize(1 to 5).toDF().write.format("parquet").save("dbfs:/tmp/results/my_data")
dbutils.notebook.exit("dbfs:/tmp/results/my_data")

/** In caller notebook */
val returned_table = dbutils.notebook.run("LOCATION_OF_CALLEE_NOTEBOOK", 60)
display(sqlContext.read.format("parquet").load(returned_table))

// Example 3 - returning JSON data.
// To return multiple values, use standard JSON libraries to serialize and deserialize results.

/** In callee notebook */

// Import jackson json libraries
import com.fasterxml.jackson.module.scala.DefaultScalaModule
import com.fasterxml.jackson.module.scala.experimental.ScalaObjectMapper
import com.fasterxml.jackson.databind.ObjectMapper

// Create a json serializer
val jsonMapper = new ObjectMapper with ScalaObjectMapper
jsonMapper.registerModule(DefaultScalaModule)

// Exit with json
dbutils.notebook.exit(jsonMapper.writeValueAsString(Map("status" -> "OK", "table" -> "my_data")))

/** In caller notebook */

// Import jackson json libraries
import com.fasterxml.jackson.module.scala.DefaultScalaModule
import com.fasterxml.jackson.module.scala.experimental.ScalaObjectMapper
import com.fasterxml.jackson.databind.ObjectMapper

// Create a json serializer
val jsonMapper = new ObjectMapper with ScalaObjectMapper
jsonMapper.registerModule(DefaultScalaModule)

val result = dbutils.notebook.run("LOCATION_OF_CALLEE_NOTEBOOK", 60)
println(jsonMapper.readValue[Map[String, String]](result))

Menangani kesalahan

Bagian ini menggambarkan cara menangani kesalahan.

Python

# Errors throw a WorkflowException.

def run_with_retry(notebook, timeout, args = {}, max_retries = 3):
  num_retries = 0
  while True:
    try:
      return dbutils.notebook.run(notebook, timeout, args)
    except Exception as e:
      if num_retries > max_retries:
        raise e
      else:
        print("Retrying error", e)
        num_retries += 1

run_with_retry("LOCATION_OF_CALLEE_NOTEBOOK", 60, max_retries = 5)

Scala

// Errors throw a WorkflowException.

import com.databricks.WorkflowException

// Since dbutils.notebook.run() is just a function call, you can retry failures using standard Scala try-catch
// control flow. Here, we show an example of retrying a notebook a number of times.
def runRetry(notebook: String, timeout: Int, args: Map[String, String] = Map.empty, maxTries: Int = 3): String = {
  var numTries = 0
  while (true) {
    try {
      return dbutils.notebook.run(notebook, timeout, args)
    } catch {
      case e: WorkflowException if numTries < maxTries =>
        println("Error, retrying: " + e)
    }
    numTries += 1
  }
  "" // not reached
}

runRetry("LOCATION_OF_CALLEE_NOTEBOOK", timeout = 60, maxTries = 5)

Menjalankan beberapa buku catatan secara bersamaan

Anda dapat menjalankan beberapa buku catatan secara bersamaan dengan menggunakan konstruksi Scala dan Python standar seperti Threads (Scala, Python) dan Futures (Scala, Python). Contoh notebook menunjukkan cara menggunakan konstruksi ini.

1. Unduh empat buku catatan berikut. Buku catatan ditulis dalam Scala.
2. Impor buku catatan ke dalam satu folder di ruang kerja.
3. Jalankan Jalankan buku catatan secara bersamaan .

Jalankan buku catatan secara bersamaan

Dapatkan buku catatan

Jalankan di buku catatan paralel

Dapatkan buku catatan

Menguji buku catatan

Dapatkan buku catatan

Buku catatan Pengujian-2

Dapatkan buku catatan