Jupyterlab筆記本中的資料訪問

每個支援的內核都提供內建功能，允許您從筆記型電腦內的資料集讀取Platform資料。 目前，Adobe Experience Platform Data Science Workspace中的JupyterLab支援Python、R、PySpark和Scala的筆記型電腦。 但是，對分頁資料的支援僅限於Python和R筆記型電腦。 本指南著重於如何使用JupyterLab筆記型電腦存取您的資料。

快速入門

閱讀本指南之前，請參閱JupyterLab 使用手冊 ，以了解JupyterLab及其在Data Science Workspace中角色的詳細介紹。

筆記本資料限制

下列資訊定義可讀取的資料量上限、使用的資料類型，以及讀取資料所花費的估計時間範圍。

對於Python和R，使用配置為40GB RAM的筆記型電腦伺服器作為基準。 對於PySpark和Scala，以下列基準使用了配置為64GB RAM、8個內核、2個DBU（最多4個工作人員）的資料庫群集。

使用的ExperienceEvent結構資料大小從一千(1K)列開始，長達十億(1B)列。 請注意，對於PySpark和Spark量度，XDM資料使用10天的日期範圍。

已使用Query Service以選取方式建立表格(CTAS)來預先處理臨機架構資料。 這些資料的大小也從1000(1K)列開始，範圍高達10億(1B)列。

何時使用批次模式與互動式模式

使用PySpark和Scala筆記型電腦讀取資料集時，您可以選擇使用互動式模式或批次模式來讀取資料集。 互動式可提供快速結果，批次模式則適用於大型資料集。

• 對於PySpark和Scala筆記本，當讀取500萬行或更多資料時，應使用批次模式。 有關每種模式的效率的詳細資訊，請參閱下面的PySpark或Scala資料限制表。

Python 筆記型資料限制

XDM ExperienceEvent結構： 您應該能在不到22分鐘內讀取最多200萬列的XDM資料（磁碟上約6.1 GB的資料）。新增其他列可能會導致錯誤。

臨機結構： 您應能在不到14分鐘內讀取最多500萬列非XDM（臨機）資料（磁碟上約5.6 GB資料）。新增其他列可能會導致錯誤。

R筆記本資料限制

XDM ExperienceEvent結構： 您應該能在13分鐘內最多讀取100萬列XDM資料（磁碟上3GB資料）。

臨機結構： 您最多應能在約10分鐘內讀取300萬列臨機資料（磁碟上293MB資料）。

PySpark（Python內核）筆記型電腦資料限制：

XDM ExperienceEvent結構： 在互動式模式中，大約20分鐘內應能讀取500萬列（磁碟上約13.42GB的資料）的XDM資料。互動式模式最多只支援500萬列。 如果您想要讀取較大的資料集，建議您切換至批次模式。 在批次模式下，您應能在約14小時內讀取最多5億行的XDM資料（磁碟上約1.31TB的資料）。

臨機結構： 在互動式模式中，您最多應能在不到3分鐘內讀取500萬列（磁碟上約5.36GB的資料）的非XDM資料。在批處理模式下，您應能在約18分鐘內讀取非XDM資料的10億行（磁碟上約1.05TB資料）。

Spark （擴展內核）筆記本資料限制：

XDM ExperienceEvent結構： 在互動式模式中，大約18分鐘內可讀取500萬列（磁碟上約13.42GB的資料）的XDM資料。互動式模式最多只支援500萬列。 如果您想要讀取較大的資料集，建議您切換至批次模式。 在批次模式下，您應能在約14小時內讀取最多5億行的XDM資料（磁碟上約1.31TB的資料）。

臨機結構： 在互動式模式中，您最多應能在不到3分鐘內讀取500萬列非XDM資料（磁碟上約5.36GB資料）。在批次模式下，您應能在約16分鐘內讀取非XDM資料的10億行（磁碟上約1.05TB資料）。

Python筆記本

Python 筆記本允許您在訪問資料集時分頁資料。以下示範使用和不使用分頁來讀取資料的范常式式碼。 有關可用啟動Python筆記本的詳細資訊，請訪問JupyterLab使用手冊中的JupyterLab 啟動器部分。

下面的Python文檔概述了以下概念：

• 從資料集讀取
• 寫入資料集
• 查詢資料
• 篩選ExperienceEvent資料

從Python中的資料集讀取

不分頁：

執行下列程式碼會讀取整個資料集。 如果執行成功，則資料將保存為變數df引用的Pancits資料幀。

# Python

from platform_sdk.dataset_reader import DatasetReader
dataset_reader = DatasetReader(get_platform_sdk_client_context(), dataset_id="{DATASET_ID}")
df = dataset_reader.read()
df.head()

分頁：

執行下列程式碼會讀取指定資料集的資料。 通過分別通過函式limit()和offset()限制和偏移資料來實現分頁。 限制資料是指要讀取的最大資料點數，而偏移是指在讀取資料之前要跳過的資料點數。 如果讀取操作成功執行，則資料將保存為變數df引用的Pancits資料幀。

# Python

from platform_sdk.dataset_reader import DatasetReader

dataset_reader = DatasetReader(get_platform_sdk_client_context(), dataset_id="{DATASET_ID}")
df = dataset_reader.limit(100).offset(10).read()

以Python寫入資料集

若要寫入JupyterLab筆記型電腦中的資料集，請在JupyterLab的左側導覽中選取「資料」圖示標籤（以下醒目提示）。 出現​Datates​和​Schemas​目錄。 選擇​資料集，按一下右鍵，然後從要使用的資料集的下拉菜單中選擇​在筆記本中寫入資料​選項。 可執行的代碼條目出現在筆記本底部。

• 使用​在筆記本中寫入資料​生成包含所選資料集的寫入單元格。
• 使用​在筆記本中瀏覽資料​生成包含所選資料集的讀取單元格。
• 使用「筆記本​查詢資料」生成包含所選資料集的基本查詢單元格。

或者，您也可以複製並貼上下列程式碼儲存格。 同時更換{DATASET_ID}和{PANDA_DATAFRAME}。

from platform_sdk.models import Dataset
from platform_sdk.dataset_writer import DatasetWriter

dataset = Dataset(get_platform_sdk_client_context()).get_by_id(dataset_id="{DATASET_ID}")
dataset_writer = DatasetWriter(get_platform_sdk_client_context(), dataset)
write_tracker = dataset_writer.write({PANDA_DATAFRAME}, file_format='json')

在Python中使用Query Service查詢資料

JupyterLab on Platform 可讓您在筆記型電腦中使 Python 用SQL來存取 Adobe Experience Platform Query Service。透過Query Service存取資料對於處理大型資料集非常有用，因為其執行時間較長。 請注意，使用Query Service查詢資料的處理時間限制為10分鐘。

在JupyterLab中使用Query Service之前，請務必了解Query Service SQL語法。

使用Query Service查詢資料時，需要提供目標資料集的名稱。 您可以使用​資料總管​找到所需的資料集，以產生必要的程式碼儲存格。 按一下右鍵資料集清單，然後按一下「筆記本中的​查詢資料」，在筆記本中生成兩個代碼單元格。 以下將詳細說明這兩個儲存格。

要在JupyterLab中使用Query Service，必須首先在工作的Python筆記本和Query Service之間建立連接。 這可以通過執行第一生成單元來實現。

qs_connect()

在第二個產生的儲存格中，必須在SQL查詢之前定義第一行。 依預設，產生的儲存格會定義選用變數(df0)，將查詢結果儲存為Pancits資料幀。
引 -c QS_CONNECTION 數是強制的，它告訴內核執行SQL查 Query Service詢。如需其他引數的清單，請參閱附錄 。

%%read_sql df0 -c QS_CONNECTION
SELECT *
FROM name_of_the_dataset
LIMIT 10
/* Querying table "name_of_the_dataset" (datasetId: {DATASET_ID})*/

可使用字串格式語法並以大括弧({})包住變數，在SQL查詢中直接引用Python變數，如以下示例所示：

table_name = 'name_of_the_dataset'
table_columns = ','.join(['col_1','col_2','col_3'])

%%read_sql demo -c QS_CONNECTION
SELECT {table_columns}
FROM {table_name}

篩選ExperienceEvent資料

若要存取及篩選Python筆記型電腦中的ExperienceEvent資料集，您必須提供資料集的ID({DATASET_ID})，以及使用邏輯運算子定義特定時間範圍的篩選規則。 定義時間範圍時，會忽略任何指定的分頁，並考量整個資料集。

篩選運算子的清單如下所述：

• eq(): Equal to
• gt(): Greater than
• ge(): Greater than or equal to
• lt(): Less than
• le(): Less than or equal to
• And():邏輯AND運算子
• Or():邏輯OR運算子

下列儲存格會將ExperienceEvent資料集篩選為2019年1月1日至2019年12月31日底之間僅存在的資料。

# Python

from platform_sdk.dataset_reader import DatasetReader

dataset_reader = DatasetReader(get_platform_sdk_client_context(), dataset_id="{DATASET_ID}")
df = dataset_reader.\
    where(dataset_reader["timestamp"].gt("2019-01-01 00:00:00").\
    And(dataset_reader["timestamp"].lt("2019-12-31 23:59:59"))\
).read()

R筆記本

R筆記本允許您在訪問資料集時分頁資料。 以下示範使用和不使用分頁來讀取資料的范常式式碼。 有關可用啟動器R筆記本的詳細資訊，請訪問JupyterLab使用手冊中的JupyterLab 啟動器部分。

以下R檔案概述下列概念：

• 從資料集讀取
• 寫入資料集
• 篩選ExperienceEvent資料

從R中的資料集讀取

不分頁：

執行下列程式碼會讀取整個資料集。 如果執行成功，則資料將保存為變數df0引用的Pancits資料幀。

# R

library(reticulate)
use_python("/usr/local/bin/ipython")
psdk <- import("platform_sdk")
datetime <- import("datetime", convert = FALSE)
py_run_file("~/.ipython/profile_default/startup/platform_sdk_context.py")
DatasetReader <- psdk$dataset_reader$DatasetReader
dataset_reader <- DatasetReader(py$get_platform_sdk_client_context(), dataset_id="{DATASET_ID}")
df0 <- dataset_reader$read()
head(df0)

分頁：

執行下列程式碼會讀取指定資料集的資料。 通過分別通過函式limit()和offset()限制和偏移資料來實現分頁。 限制資料是指要讀取的最大資料點數，而偏移是指在讀取資料之前要跳過的資料點數。 如果讀取操作成功執行，則資料將保存為變數df0引用的Pancits資料幀。

# R

library(reticulate)
use_python("/usr/local/bin/ipython")
psdk <- import("platform_sdk")
datetime <- import("datetime", convert = FALSE)
py_run_file("~/.ipython/profile_default/startup/platform_sdk_context.py")

DatasetReader <- psdk$dataset_reader$DatasetReader
dataset_reader <- DatasetReader(py$get_platform_sdk_client_context(), dataset_id="{DATASET_ID}") 
df0 <- dataset_reader$limit(100L)$offset(10L)$read()

寫入R中的資料集

若要寫入JupyterLab筆記型電腦中的資料集，請在JupyterLab的左側導覽中選取「資料」圖示標籤（以下醒目提示）。 出現​Datates​和​Schemas​目錄。 選擇​資料集，按一下右鍵，然後從要使用的資料集的下拉菜單中選擇​在筆記本中寫入資料​選項。 可執行的代碼條目出現在筆記本底部。

• 使用​在筆記本中寫入資料​生成包含所選資料集的寫入單元格。
• 使用​在筆記本中瀏覽資料​生成包含所選資料集的讀取單元格。

或者，您也可以複製並貼上下列程式碼儲存格：

psdk <- import("platform_sdk")
dataset <- psdk$models$Dataset(py$get_platform_sdk_client_context())$get_by_id(dataset_id="{DATASET_ID}")
dataset_writer <- psdk$dataset_writer$DatasetWriter(py$get_platform_sdk_client_context(), dataset)
write_tracker <- dataset_writer$write(df, file_format='json')

篩選ExperienceEvent資料

若要存取及篩選R型筆記型電腦中的ExperienceEvent資料集，您必須提供資料集的ID({DATASET_ID})，以及使用邏輯運算子定義特定時間範圍的篩選規則。 定義時間範圍時，會忽略任何指定的分頁，並考量整個資料集。

篩選運算子的清單如下所述：

• eq():等於
• gt():大於
• ge():大於或等於
• lt():小於
• le():小於或等於
• And():邏輯AND運算子
• Or():邏輯OR運算子

下列儲存格會將ExperienceEvent資料集篩選為2019年1月1日至2019年12月31日底之間僅存在的資料。

# R

library(reticulate)
use_python("/usr/local/bin/ipython")
psdk <- import("platform_sdk")
datetime <- import("datetime", convert = FALSE)
py_run_file("~/.ipython/profile_default/startup/platform_sdk_context.py")

client_context <- py$PLATFORM_SDK_CLIENT_CONTEXT
DatasetReader <- psdk$dataset_reader$DatasetReader
dataset_reader <- DatasetReader(py$get_platform_sdk_client_context(), dataset_id="{DATASET_ID}") 

df0 <- dataset_reader$
    where(dataset_reader["timestamp"]$gt("2019-01-01 00:00:00")$
    And(dataset_reader["timestamp"]$lt("2019-12-31 23:59:59"))
)$read()

PySpark 3筆記型電腦

下面的PySpark文檔概述了以下概念：

• 初始化SparkSession
• 讀和寫資料
• 建立本地資料幀
• 篩選ExperienceEvent資料

初始化sparkSession

所有Spark 2.4筆記本都要求您使用以下模板代碼初始化會話。

from pyspark.sql import SparkSession
spark = SparkSession.builder.getOrCreate()

使用%資料集，使用PySpark 3筆記本進行讀寫

隨著Spark 2.4的推出，%dataset自定義魔術被提供用於PySpark 3(Spark 2.4)筆記本。 有關IPython內核中可用的魔術命令的詳細資訊，請訪問IPython魔術文檔。

使用狀況

%dataset {action} --datasetId {id} --dataFrame {df} --mode batch

說明

用於從PySpark筆記本（Python 3內核）讀取或寫入資料集的自定義Data Science Workspace魔術命令。

範例

• 閱讀範例: %dataset read --datasetId 5e68141134492718af974841 --dataFrame pd0 --mode batch
• 撰寫範例: %dataset write --datasetId 5e68141134492718af974842 --dataFrame pd0 --mode batch

您可以使用下列方法在JupyterLab購買中自動產生上述範例：

在JupyterLab的左側導覽中選取「資料」圖示標籤（以下醒目提示）。 出現​Datates​和​Schemas​目錄。 選擇​資料集，按一下右鍵，然後從要使用的資料集的下拉菜單中選擇​在筆記本中寫入資料​選項。 可執行的代碼條目出現在筆記本底部。

• 使用​在筆記本中瀏覽資料​生成讀單元。
• 使用​在筆記本中寫入資料​生成寫單元。

建立本地資料幀

要使用PySpark 3建立本地資料幀，請使用SQL查詢。 例如：

date_aggregation.createOrReplaceTempView("temp_df")

df = spark.sql('''
  SELECT *
  FROM sparkdf
''')

local_df

df = spark.sql('''
  SELECT *
  FROM sparkdf
  LIMIT limit
''')

sample_df = df.sample(fraction)

篩選ExperienceEvent資料

存取和篩選PySpark筆記型電腦中的ExperienceEvent資料集時，您必須提供資料集身分({DATASET_ID})、貴組織的IMS身分，以及定義特定時間範圍的篩選規則。 篩選時間範圍是使用函式spark.sql()來定義，其中函式參數為SQL查詢字串。

下列儲存格會將ExperienceEvent資料集篩選為2019年1月1日至2019年12月31日期末之間僅存在的資料。

# PySpark 3 (Spark 2.4)

from pyspark.sql import SparkSession
spark = SparkSession.builder.getOrCreate()

%dataset read --datasetId {DATASET_ID} --dataFrame df --mode batch

df.createOrReplaceTempView("event")
timepd = spark.sql("""
    SELECT *
    FROM event
    WHERE timestamp > CAST('2019-01-01 00:00:00.0' AS TIMESTAMP)
    AND timestamp < CAST('2019-12-31 23:59:59.9' AS TIMESTAMP)
""")
timepd.show()

縮放筆記本

以下檔案包含下列概念的範例：

• 初始化SparkSession
• 讀取資料集
• 寫入資料集
• 建立本地資料幀
• 篩選ExperienceEvent資料

初始化SparkSession

所有Scala筆記本都要求您使用以下模板代碼初始化會話：

import org.apache.spark.sql.{ SparkSession }
val spark = SparkSession
  .builder()
  .master("local")
  .getOrCreate()

讀取資料集

在Scala中，您可以匯入clientContext以取得並傳回平台值，如此就不需要定義變數，例如var userToken。 在以下的Scala範例中， clientContext用於取得並傳回讀取資料集所需的所有必要值。

import org.apache.spark.sql.{Dataset, SparkSession}
import com.adobe.platform.token.ClientContext
val spark = SparkSession.builder().master("local").config("spark.sql.warehouse.dir", "/").getOrCreate()

val clientContext = ClientContext.getClientContext()
val df1 = spark.read.format("com.adobe.platform.query")
  .option("user-token", clientContext.getUserToken())
  .option("ims-org", clientContext.getOrgId())
  .option("api-key", clientContext.getApiKey())
  .option("service-token", clientContext.getServiceToken())
  .option("sandbox-name", clientContext.getSandboxName())
  .option("mode", "batch")
  .option("dataset-id", "5e68141134492718af974844")
  .load()

df1.printSchema()
df1.show(10)

您可以使用下列方法在JupyterLab buy中自動產生上述範例：

在JupyterLab的左側導覽中選取「資料」圖示標籤（以下醒目提示）。 出現​Datates​和​Schemas​目錄。 選取​資料集，按一下滑鼠右鍵，然後在您要使用之資料集的下拉式選單中選取​在筆記型電腦中探索資料​選項。 可執行的代碼條目出現在筆記本底部。
和

• 使用​在筆記本中瀏覽資料​生成讀單元。
• 使用​在筆記本中寫入資料​生成寫單元。

寫入資料集

在Scala中，您可以匯入clientContext以取得並傳回平台值，如此就不需要定義變數，例如var userToken。 在以下的Scala範例中， clientContext用於定義並傳回寫入資料集所需的所有必要值。

import org.apache.spark.sql.{Dataset, SparkSession}
import com.adobe.platform.token.ClientContext
val spark = SparkSession.builder().master("local").config("spark.sql.warehouse.dir", "/").getOrCreate()

val clientContext = ClientContext.getClientContext()
df1.write.format("com.adobe.platform.query")
  .option("user-token", clientContext.getUserToken())
  .option("service-token", clientContext.getServiceToken())
  .option("ims-org", clientContext.getOrgId())
  .option("api-key", clientContext.getApiKey())
  .option("sandbox-name", clientContext.getSandboxName())
  .option("mode", "batch")
  .option("dataset-id", "5e68141134492718af974844")
  .save()

建立本地資料幀

要使用Scala建立本地資料幀，需要SQL查詢。 例如：

sparkdf.createOrReplaceTempView("sparkdf")

val localdf = spark.sql("SELECT * FROM sparkdf LIMIT 1)

篩選ExperienceEvent資料

存取和篩選Scala筆記型電腦中的ExperienceEvent資料集時，您必須提供資料集身分({DATASET_ID})、貴組織的IMS身分，以及定義特定時間範圍的篩選規則。 篩選時間範圍是使用函式spark.sql()定義的，其中函式參數為SQL查詢字串。

下列儲存格會將ExperienceEvent資料集篩選為2019年1月1日至2019年12月31日期末之間僅存在的資料。

// Spark (Spark 2.4)

// Turn off extra logging
import org.apache.log4j.{Level, Logger}
Logger.getLogger("org").setLevel(Level.OFF)
Logger.getLogger("com").setLevel(Level.OFF)

import org.apache.spark.sql.{Dataset, SparkSession}
val spark = org.apache.spark.sql.SparkSession.builder().appName("Notebook")
  .master("local")
  .getOrCreate()

// Stage Exploratory
val dataSetId: String = "{DATASET_ID}"
val orgId: String = sys.env("IMS_ORG_ID")
val clientId: String = sys.env("PYDASDK_IMS_CLIENT_ID")
val userToken: String = sys.env("PYDASDK_IMS_USER_TOKEN")
val serviceToken: String = sys.env("PYDASDK_IMS_SERVICE_TOKEN")
val mode: String = "batch"

var df = spark.read.format("com.adobe.platform.query")
  .option("user-token", userToken)
  .option("ims-org", orgId)
  .option("api-key", clientId)
  .option("mode", mode)
  .option("dataset-id", dataSetId)
  .option("service-token", serviceToken)
  .load()
df.createOrReplaceTempView("event")
val timedf = spark.sql("""
    SELECT * 
    FROM event 
    WHERE timestamp > CAST('2019-01-01 00:00:00.0' AS TIMESTAMP)
    AND timestamp < CAST('2019-12-31 23:59:59.9' AS TIMESTAMP)
""")
timedf.show()

後續步驟

本檔案說明使用JupyterLab筆記型電腦存取資料集的一般准則。 如需查詢資料集的更深入範例，請造訪JupyterLab筆記本🔗中的查詢服務檔案。 有關如何探索和視覺化資料集的詳細資訊，請訪問上的文檔，使用notebooks分析資料。

Query Service的可選SQL標誌

此表概述了可用於Query Service的可選SQL標誌。