Jupyterlab ノートブックでのデータアクセス

サポートされる各カーネルは、ノートブック内のデータセットから Platform データを読み取るための組み込み機能を備えてます。現在、Adobe Experience Platform Data Science Workspaceの JupyterLab は、Python、R、PySpark、Scala 用のノートブックをサポートしています。 ただし、データのページ番号付けのサポートは、Python および R ノートブックに制限されています。 このガイドでは、JupyterLab ノートブックを使用してデータにアクセスする方法を重点的に説明します。

はじめに

このガイドを読む前に、JupyterLab ユーザーガイドを参照して、JupyterLab の概要とデータサイエンスWorkspace内での役割を確認してください。

ノートブックのデータ制限 notebook-data-limits

次の情報は、読み取ることができるデータの最大量、使用されたデータの種類、およびデータの読み取りにかかる推定期間を定義します。

PythonとRについては、40GBのRAMで構成されたノートブックサーバーがベンチマークに使用されました。PySpark と Scala では、64 GB の RAM、8 コア、2 DBU (最大 4 ワーカー) で構成されたデータブリック クラスターを、以下に概説するベンチマークに使用しました。

使用される ExperienceEvent スキーマ データのサイズは、1,000 行から 10 億行までさまざまでした。 PySpark および Spark メトリックでは、XDMデータに 10 日間の日付範囲が使用されていたことに注意してください。

アドホックスキーマデータは、「テーブル Query Service 選択として作成」（CTAS）を使用して前処理されました。 このデータのサイズも、1,000 (1K) 行から最大 10 億 (1B) 行までさまざまでした。

バッチモードとインタラクティブモードを使用する場合 mode

PySpark および Scala ノートブックでデータセットを読み取る場合、対話モードまたはバッチ モードを使用してデータセットを読み取るオプションがあります。 インタラクティブは迅速な結果を得るために作られていますが、バッチモードは大規模なデータセット用です。

Python notebook のデータ制限

XDM ExperienceEvent スキーマ： XDM データの最大 200 万行（ディスク上の最大 6.1 GB データ）を 22 分以内に読み取ることができるはずです。 行を追加すると、エラーが発生する場合があります。

アドホックスキーマ： 非 XDM （アドホック）データの最大 500 万行（ディスク上の最大 5.6 GB のデータ）を 14 分以内に読み取ることができるはずです。 行を追加すると、エラーが発生する場合があります。

R ノートブックのデータ制限

XDM ExperienceEvent スキーマ： 最大 100 万行の XDM データ（ディスク上の 3 GB データ）を 13 分以内に読み取ることができるはずです。

アドホックスキーマ： 約 10 分で最大 300 万行のアドホックスキーマ（ディスク上の 293 MB のデータ）を読み取れるはずです。

PySpark （Python カーネル）ノートブックのデータ制限： pyspark-data-limits

XDM ExperienceEvent スキーマ： インタラクティブモードでは、約 20 分で XDM データの最大 500 万行（ディスク上の最大 13.42 GB データ）を読み取れるはずです。 インタラクティブモードでサポートできる行は 500 万行までです。 より大きなデータセットを読み取る場合は、バッチモードに切り替えることをお勧めします。 バッチモードでは、約 14 時間で最大 5 億行（ディスク上の最大 1.31 TB のデータ）の XDM データを読み取ることができます。

広告-hoc スキーマ: インタラクティブ モードでは、最大 500 万行 (ディスク上に ~5.36 GB のデータ) の非 XDM データを 3 分以内に読み取ることができます。 バッチモードでは、約 18 分で最大 10 億行 (ディスク上に ~1.05 TB のデータ) の非 XDM データを読み取ることができます。

Spark (Scala カーネル)ノートブックのデータ制限: scala-data-limits

XDM エクスペリエンス イベント スキーマ: 対話モードでは、約 18 分で最大 500 万行 (ディスク上に ~13.42 GB のデータ) のXDMデータを読み取ることができます。 インタラクティブモードでは、最大 500 万行のみがサポートされます。 より大きなデータセットを読み取る場合は、バッチモードに切り替えることをお勧めします。 バッチモードでは、約14時間で最大5億行(ディスク上に~1.31TBのデータ)のXDMデータを読み取ることができます。

アドホックスキーマ： インタラクティブモードでは、非 XDM データの最大 500 万行（ディスク上の最大 5.36 GB データ）を 3 分以内に読み取ることができます。 バッチモードでは、約 16 分で最大 10 億行（ディスク上の約 1.05 TB のデータ）の非 XDM データを読み取ることができます。

Python ノートブック python-notebook

Python ノートブックを使用すると、データセットにアクセスする際に、データにページ番号を付けることができます。 ページネーションを使用してデータを読み取るサンプルコードと使用しないサンプルデータを以下に示します。 使用可能なスターター Python ノートブックについて詳しくは、JupyterLab ユーザーガイドの JupyterLab ランチャーの節を参照してください。

以下の Python ドキュメントでは、以下の概念の概要を説明しています。

Python でデータセットから読み取る python-read-dataset

ページネーションなし：

次のコードを実行すると、データセット全体が読み取られます。実行が成功した場合、データは df 変数で参照される Pandas データフレームとして保存されます。

# 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 変数が参照する Pandas データフレームとして保存されます。

# 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 でデータセットに書き込む write-python

JupyterLab ノートブックのデータセットに書き込むには、JupyterLab の左ナビゲーションにあるデータアイコンタブ (以下で強調表示) を選択します。 データセット ​ディレクトリと​ スキーマ ​ディレクトリが表示されます。 [ データセット を選択して右クリックし、使用するデータセットのドロップダウンメニューから ノートブックにデータを書き込む オプションを選択します。 実行可能コード エントリがノートブックの下部に表示されます。

または、次のコードセルをコピーして貼り付けることもできます。 {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')

の Query Service を使用してデータをクエリ Python query-data-python

JupyterLab on Platform を使用すると、 Python ノートブックで SQL を使用して Adobe Experience Platformクエリ サービスを介してデータにアクセスできます。 Query Service を通じたデータへのアクセスは実行時間が短いので、大規模なデータセットの処理に役立ちます。Query Service を使用したデータのクエリには 10 分間の処理時間制限があることに注意してください。

JupyterLab で Query Service を使用する前に、Query Service SQL 構文について実践的に理解していることを確認してください。

Query Service を使用したデータのクエリには、ターゲットデータセットの名前を指定する必要があります。 必要なコードセルを生成するには、データエクスプローラー ​を使用して目的のデータセットを見つけます。データセットリストを右クリックし、「ノートブックのデータをクエリ」をクリックして、ノートブックに 2 つのコードセルを生成します。 これら 2 つのセルについて、以下で詳しく説明します。

Query Service を JupyterLab で利用するには、まず作業中の Python ノートブックと Query Service の間の接続を作成する必要があります。 これは、最初に生成されたセルを実行することで達成できます。

qs_connect()

2 番目に生成されたセルでは、最初の行を SQL クエリの前に定義する必要があります。デフォルトでは、生成されたセルは、クエリ結果を Pandas データフレームとして保存するオプションの変数（df0）を定義します。
-c QS_CONNECTION 引数は必須で、Query Service に対して SQL クエリを実行するようにカーネルに指示します。 その他の引数のリストは、付録を参照してください。

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

Python 変数は、次の例に示すように、文字列形式の構文を使用して中括弧（{}）で囲むことで、SQL クエリ内で直接参照できます。

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-filter

Python ノートブック内のExperienceEvent データセットにアクセスしてフィルター処理するには、論理演算子を使用して特定の時間範囲を定義するフィルター規則と共に、データセット の ID ({DATASET_ID}) を指定する必要があります。時間範囲を定義すると、指定されたページ番号は無視され、データセット全体が考慮されます。

フィルタリング操作のリストを以下に示します。

次のセルでは、ExperienceEvent データセットを、2019 年 1 月 1 日～2019 年 12 月 31 日（PT）の間にのみ存在するデータにフィルタリングします。

# 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-notebooks

r ノートブックを使用すると、データセットにアクセスする際にデータのページ番号を付けることができます。 ページネーションを使用してデータを読み取るサンプルコードと使用しないサンプルデータを以下に示します。 使用可能なスターター R ノートブックの詳細については、JupyterLab ユーザー ガイド内の JupyterLab ランチャー セクション訪問してください。

以下の R ドキュメントでは、次の概念の概要について説明します。

R のデータセットからの読み取り r-read-dataset

ページネーションなし：

次のコードを実行すると、データセット全体が読み取られます。実行が成功した場合、データは df0 変数で参照される Pandas データフレームとして保存されます。

# 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 変数が参照する Pandas データフレームとして保存されます。

# 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 のデータセットへの書き込み write-r

JupyterLab ノートブックのデータセットに書き込むには、JupyterLab の左側のナビゲーションにある「データ」アイコンタブ（以下でハイライト表示）を選択します。 データセット ​ディレクトリと​ スキーマ ​ディレクトリが表示されます。 「データセット」を選択して右クリックし、使用するデータセットのドロップダウンメニューから「ノートブックにデータを書き込む」オプションを選択します。 ノートブックの下部に実行可能コードエントリが表示されます。

または、次のコードセルをコピーして貼り付けることもできます。

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-filter

R ノートブックの ExperienceEvent データセットにアクセスしてフィルタリングするには、データセット（{DATASET_ID}）の ID と、論理演算子を使用して特定の時間範囲を定義するフィルタールールを指定する必要があります。 時間範囲を定義すると、指定されたページ番号は無視され、データセット全体が考慮されます。

フィルタリング操作のリストを以下に示します。

次のセルフィルター、2019 年 1 月 1 日から 2019 年 12 月 31 日までの間に排他的に存在するデータへの ExperienceEvent データセットです。

# 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-notebook

以下の PySpark のドキュメントでは、次の概念の概要について説明しています。

sparkSession の初期化 spark-initialize

すべての Spark 2.4 ノートブックでは、次のボイラープレートコードを使用してセッションを初期化する必要があります。

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

%dataset を使用した PySpark 3 ノートブックの読み取りと書き込み magic

Spark 2.4 の導入に伴い、PySpark 3 （Spark 2.4）ノートブックで使用するた %dataset のカスタムマジックが提供されています。 IPython カーネルで利用可能なマジックコマンドについて詳しくは、IPython マジックドキュメントを参照してください。

用途

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

説明

PySpark notebook （Python 3 カーネル）からデータセットを読み取ったり書き込んだりするためのカスタム Data Science Workspace magic コマンド。

例

JupyterLab buy では、次の方法を使用して、上記の例を自動生成できます。

JupyterLab の左側のナビゲーションにある「データ」アイコンタブ（以下で強調表示）を選択します。 データセット ​ディレクトリと​ スキーマ ​ディレクトリが表示されます。 「データセット」を選択して右クリックし、使用するデータセットのドロップダウンメニューから「ノートブックにデータを書き込む」オプションを選択します。 ノートブックの下部に実行可能コードエントリが表示されます。

ローカルデータフレームの作成 pyspark-create-dataframe

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-filter-experienceevent

PySpark ノートブックの ExperienceEvent データセットへのアクセスとフィルタリングには、データセット ID （{DATASET_ID}）、組織の IMS ID、特定の時間範囲を定義するフィルタールールを指定する必要があります。 フィルター時間範囲は、関数 spark.sql() を使用して定義します。関数パラメーターは SQL クエリ文字列です。

次のセルでは、ExperienceEvent データセットを、2019 年 1 月 1 日～2019 年 12 月 31 日（PT）の間にのみ存在するデータにフィルタリングします。

# 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()

Scala ノートブック scala-notebook

以下のドキュメントには、次の概念の例が含まれています。

SparkSession の初期化 scala-initialize

すべての Scala ノートブックでは、以下のボイラープレートコードを使用してセッションを初期化する必要があります。

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

データセットの読み取り read-scala-dataset

Scalaでは、 clientContext をインポートしてPlatform値を取得および返すことができるため、 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 購入で自動生成できます。

JupyterLab の左ナビゲーションにあるデータアイコンタブ(以下でハイライト表示)を選択します。 データセット ​ディレクトリと​ スキーマ ​ディレクトリが表示されます。 「データセット」を選択して右クリックし、使用するデータセットのドロップダウンメニューから「ノートブックのデータを調査」オプションを選択します。実行可能コード エントリがノートブックの下部に表示されます。および

データセットへの書き込み scala-write-dataset

Scala では、clientContext を読み込んで Platform の値を取得したり返したりできるので、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-create-dataframe

Scala を使用してローカルデータフレームを作成するには、SQL クエリが必要です。 例：

sparkdf.createOrReplaceTempView("sparkdf")

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

ExperienceEvent データのフィルタリング scala-experienceevent

Scala ノートブックの ExperienceEvent データセットにアクセスしてフィルタリングするには、データセット ID （{DATASET_ID}）、組織の IMS ID、特定の時間範囲を定義するフィルタールールを指定する必要があります。 時間範囲のフィルタリングは、spark.sql() 関数を使用して定義します。関数パラメータは SQL クエリ文字列です。

次のセルでは、ExperienceEvent データセットを、2019 年 1 月 1 日～2019 年 12 月 31 日（PT）の間にのみ存在するデータにフィルタリングします。

// 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 ノートブックのクエリサービス のドキュメント訪問してください。 データセットを探索して視覚化する方法の詳細については、 ノートブックを使用したデータの分析に関するドキュメント訪問してください。

オプションの SQL フラグ Query Service optional-sql-flags-for-query-service

次の表に、 Query Serviceに使用できるオプションの SQL フラグの概要を示します。