DataWorks のノートブックは、Python、SQL、Markdown セルを組み合わせて、MaxCompute、EMR、AnalyticDB などのコンピューティングエンジンに接続し、データ処理、探索的分析、可視化、モデル開発を行うためのインタラクティブな環境を提供します。
クイックスタート：5分で最初のノートブックを実行
ノートブックを作成し、Python から SQL へパラメーターを渡し、MaxCompute テーブルをクエリします。
前提条件
ワークスペースで DataStudio が有効化されていること。
サーバーレスリソースグループ を持っていること。
個人用開発環境インスタンス を持っていること (Python セルを含むノートブックに必要です)。
まだ作成していない場合： 個人用開発環境インスタンスを作成。
手順：
ノートブックノードの作成
DataStudio に移動します。[プロジェクトディレクトリ] の [データ開発] セクションで、新しいノートブックノードを作成します。
ノートブックの名前 (例：
hello_notebook) を入力し、送信します。
個人用開発環境の選択
上部メニューで 個人開発環境 をクリックし、ドロップダウンリストからお使いの個人用開発環境インスタンスを選択します。
Python セルを記述してパラメーターを定義
SQL クエリのために city 変数を定義します。
# 後続の SQL クエリ用の変数を定義 city = 'Beijing' print(f"Defined city variable city = {city}")SQL セルを記述してデータをクエリ
最初のセルの下に、新しい SQL セルを追加します。
セルの右下隅で、SQL タイプを
MaxCompute SQLに切り替えます。次の SQL を入力します。これは、
${city}構文を使用して Python セルのcity変数を参照します。-- Python で定義された変数を使用してデータをクエリ SELECT '${city}' AS city;
セルを実行して結果を表示
ノートブックのツールバーにある [すべて実行] ボタンをクリックします。
各セルの実行を確認します：
Python セルは
Defined city variable city = Beijingを出力します。SQL セルの下に、クエリ結果のテーブルが表示されます。
Python と SQL が連携するノートブックを作成し、実行しました。
コアコンセプト
これらのコンセプトを理解することで、開発環境と本番環境におけるノートブックの動作の一貫性を確保できます。
ノートブックのモード
DataWorks のノートブックは 2 つのモードで動作します：
SQL と Markdown モード (デフォルト)：データクエリとドキュメント作成のために SQL と Markdown セルのみをサポートします。サーバーレスリソースグループのみが必要で、個人用開発環境インスタンスは不要です。右上隅に SQL カーネル が表示されます。
フルモード (Python + SQL + Markdown)：データ処理、分析、可視化のために Python、SQL、Markdown セルをサポートします。Python コードの実行には 個人用開発環境インスタンス が必要です。インスタンスを選択すると、右上隅にカーネルバージョンが表示されます (例：
(バージョンは参考用です))。
開発環境と本番環境
項目 | 開発環境 | 本番環境 |
ランタイム環境 | 個人用開発環境インスタンス | [スケジューリング設定] で指定された [リソースグループ] と [イメージ] |
主な違い | Python セルを含むノートブックは、専用の開発インスタンスを使用します。ここでは、デバッグのために Python ライブラリを自由にインストールできます。 SQL と Markdown セルのみを含むノートブックの場合、サーバーレスリソースグループのみが必要です。 | タスクが オペレーションセンター から定期的にトリガーされるか、DataStudio から手動でトリガーされるかにかかわらず、タスクはスケジューリング設定のリソースグループで実行されます。環境 (ライブラリ、ネットワークアクセスなど) は、イメージとリソースグループによって決定されます。 |
一貫性の確保 |
重要 ネットワーク接続：VPC にバインドされていない個人用開発環境は、デフォルトでパブリックネットワークへのアクセスが制限されています。デプロイされたノートブックのネットワークアクセスは、そのリソースグループに依存します。一貫性を確保するために、個人用開発環境をスケジューリングに使用する同じリソースグループにバインドしてください。 | |
コンピューティングリソースとカーネル
コードがどのように実行されるかは、コンピューティングリソース と カーネル という 2 つの概念によって決定されます。
コンピューティングリソース：データタスクを実行・処理するバックエンドのコンピューティングエンジンであり、ランタイム環境と計算能力を定義します。
定義：独立したスケジューリング可能なコンピューティングサービスインスタンス (例：MaxCompute プロジェクトや EMR Serverless Spark クラスター)。
機能：SQL クエリ、Spark ジョブ、その他のタスクに実際の計算能力を提供します。
選択：各タスクを特定のコンピューティングリソースに関連付けます。
カーネル：セル内のコードを解析・実行し、どのプログラミング言語が使用されるかを決定します。
Python カーネル：
機能：Python コードを実行し、データ処理、アルゴリズム実装、タスクオーケストレーションのための複雑なロジックをサポートします。
対話モデル：Python カーネル内で、
マジックコマンド(%sqlなど) や SDK を使用して、指定された コンピューティングリソース に計算タスク (SQL クエリなど) を送信できます。その後、結果を取得してさらに分析を行うことができます。
SQL カーネル：
機能：SQL で書かれたクエリを直接解釈し、送信します。
対話モデル：SQL カーネルは、SQL 文を直接、指定されたバックエンドの コンピューティングリソース (例：EMR Spark SQL や MaxCompute SQL セッション) に転送して実行します。
Markdown カーネル：
機能：Markdown でフォーマットされたリッチテキストをレンダリングします。計算ロジックは一切実行しません。
関係の概要：
カーネル はフロントエンドの 言語インタープリター であり、「何を書くか」(Python か SQL か) を決定します。
コンピューティングリソース はバックエンドの 実行エンジン であり、「どこでコードが実行されるか」(MaxCompute 上か Spark 上か) を決定します。
ディレクトリタイプとユースケース
ノートブックを作成する場所によって、そのコラボレーション範囲、権限、デプロイオプションが決定されます。
ディレクトリタイプ | ユースケース | コラボレーションとデプロイ |
ワークスペースディレクトリ | チームコラボレーションとスケジュール実行される本番タスク。ノードはワークスペース内で共有され、開発、コミット、デプロイのワークフローに従います。 | 複数ユーザーでのコラボレーション。ノードをスケジュール実行するには、本番環境に デプロイ する必要があります。 |
個人用ディレクトリ | 個人での開発とデバッグ。個人用のスクリプトや一時的なタスク向けで、作成者本人のみが利用できます。 | 自分にのみ表示されます。ノードをスケジュール実行するには、まず ワークスペースディレクトリ にコミットしてからデプロイする必要があります。 |
ノートブックの開発とデバッグ
DataStudio はデフォルトでは自動保存されません。コードの損失を避けるために 手動で保存 するか、設定項目 > [ファイル：自動保存] で自動保存を有効にしてください。
ノートブックが遅延したり応答しなくなったりした場合は、上部ツールバーの 再起動 ボタンをクリックしてカーネルを再起動してください。
セルの管理
セルの追加：セルの上端または下端にカーソルを合わせ、[+ SQL] などのボタンをクリックするか、ツールバーのボタンを使用します。
セルタイプの切り替え：右下隅のタイプ識別子 (例：
Python) をクリックし、SQLやMarkdownなどの新しいタイプを選択します。コードは保持されますが、修正が必要な場合があります。セルの移動：セルの左側にある青い垂直線にカーソルを合わせ、クリックしてドラッグすることで順序を変更できます。
セルの実行：
単一セルの実行：セルの左側にある [実行] アイコンをクリックします。
すべてのセルを実行：ノートブックの上部ツールバーにある [すべて実行] ボタンをクリックします。
パラメーターの受け渡し
Python 変数の SQL への受け渡し
SQL セル内で ${variable_name} 形式を使用して Python 変数を参照します。
例：
Python セル
table_name = "dwd_user_info_d" limit_num = 10SQL セル
SELECT * FROM ${table_name} LIMIT ${limit_num};
SQL 結果の Python への受け渡し
SELECT クエリを実行すると、結果は自動的にデータフレーム変数に変換され、後続の Python セルで使用できます。
セルに複数の SQL 文が含まれている場合、最後の文の結果のみがデータフレーム変数に保存されます。
変数名：デフォルトの変数名は
df_で始まります。SQL セルの左下隅にある変数名をクリックして名前を変更できます。変数の型：
複数の変数の型がサポートされている場合、左下隅のデータフレーム名をクリックして型を切り替えることができます。
MaxCompute SQL の場合、
Pandas DataFrameとMaxCompute MaxFrameオブジェクトの両方がサポートされています。ADB Spark SQL の場合、
Pandas DataFrameとPySpark DataFrameオブジェクトの両方がサポートされています。他の SQL タイプの場合、
Pandas DataFrameオブジェクトが生成されます。
データリネージの表示 (ベータ版)
対応リージョン：中国 (杭州)、中国 (上海)、中国 (北京)、中国 (張家口)、中国 (ウランチャブ)、中国 (深圳)、中国 (成都)、中国 (香港)。
データリネージ機能は、ノートブック内の Python コード (MaxFrame フレームワーク対応) を静的に分析することで、データの流れを明確にします。
手順
ノートブックの上部ツールバーで、リネージ ボタンをクリックします。システムは現在のノートブックのすべてのセル内のコードを自動的に分析し、エディターにデータリネージグラフを表示します。
データリネージはベータ版の機能で、Python/MaxFrame コードのみをサポートしています。リネージパネルには、ソーステーブルとターゲットテーブル間のデータの流れが有向グラフとして表示されます。
データリネージ分析は、ノートブック内の静的コードを検査します。これは、タスク実行による実際のデータの流れではなく、コードで定義されたデータロジックを反映します。コードを実行しなくてもデータリネージを表示できます。
現在、この機能は開発とデバッグ用に設計されています。システムは分析されたリネージ関係を自動的に データマップ に報告しません。
コードを修正した場合、リネージ または パージ を再度クリックして、更新されたリネージグラフを生成する必要があります。
対応シナリオ
データリネージ分析は、現在 以下のシナリオのみ をサポートしています：
MaxCompute テーブル間のリネージ：1 つ以上の MaxCompute テーブルからデータを読み取り、MaxFrame で処理し、結果を別の MaxCompute テーブルに書き込むと、リネージグラフにはテーブル間の処理関係が表示されます。
たとえば、注文テーブル (ods_order) を店舗ディメンションテーブル (dim_shop) と結合し、結果をワイド注文テーブル (dwd_order) に書き込む場合などです。
MaxCompute テーブルと外部データ間のリネージ：コードが外部データソース (バインドされたデータセットや OSS ファイルなど) と MaxCompute テーブルの両方とやり取りする場合、データリネージ機能はこれらの関係を可視化します。
バインドされたデータセット経由：個人用開発環境のマウントパス (例：
/mnt/data/) を通じてバインドされたデータセットにアクセスし、MaxCompute テーブルとデータを交換する (データセットからテーブルへの読み取り、またはその逆) 場合、リネージグラフにはデータフロー全体が表示されます。OSS パス経由：バインドされたデータセットがなくても、コード内で OSS パスを使用してファイルを直接読み書きする場合、データリネージ分析は OSS パスと MaxCompute テーブル間の双方向のデータの流れを識別します。
説明この OSS パスが データマップ にデータセットとしても登録されている場合、リネージグラフはそれを自動的にデータセットノードとして表示し、資産管理がしやすくなります。
Copilot 支援プログラミング
DataWorks Copilot は、コードの生成と説明を支援する組み込みの AI プログラミングアシスタントです。
呼び出し方法：
選択したセルの左上隅にある Copilot
アイコンをクリックします。SQL セル内を右クリックし、[Copilot] を選択します。
キーボードショートカット
Cmd+I(macOS) またはCtrl+I(Windows) を使用します。
ノートブックのスケジューリングとデプロイ
ノートブックをスケジュール実行するには、そのスケジューリングプロパティを設定し、本番環境にデプロイします。
1. スケジューリングパラメーターの設定 (パラメーター化されたスケジューリング)
パラメーター化されたスケジューリングを設定して、ノートブックのパラメーターが実行ごとに動的に変更されるようにします。たとえば、毎日異なるパーティションを処理できます。
パラメーターセルのマーク：パラメーター定義を持つ Python セルで、右上隅の
...をクリックし、[セルをパラメーターとしてマーク] を選択します。parametersタグがセルをパラメーターのエントリポイントとしてマークします。スケジューリングパラメーターの設定：
ノートブックの右側パネルで、スケジューリング設定 をクリックします。
[スケジューリングパラメーター] エリアで、コードで定義された変数 (例：
var) に値を割り当てます。たとえば、パラメーター値を
$[yyyymmdd]に設定できます。スケジュール実行時に、これは実際の日付に動的に置き換えられます。
タスクがスケジューリングシステムによって自動実行されると、コード内の var パラメーターは、スケジューリングパラメーターで設定された値に動的に置き換えられます。
2. ランタイム環境とリソースの設定
イメージの設定：[スケジューリング] 設定で、ノートブックが必要とするすべての依存関係を含む イメージ を選択します。これにより、本番環境でタスクを確実に実行できるようになります。
重要pip installを使用して Python パッケージをインストールした場合、本番環境に同じ依存関係があることを確実にするために、個人用開発環境から DataWorks イメージを作成する必要があります。[スケジューリング] 設定でこのイメージを選択します。リソースグループ：タスク用の リソースグループ を選択します。サーバーレスリソースグループの場合、起動失敗を避けるために
16 CU以下に設定してください。タスクあたりの最大値は64 CUです。関連ロールの設定：ノードに RAM ロール を関連付けて、きめ細かな権限制御を可能にします。ロールの関連付け：他のクラウドリソースへの安全なアクセス。
3. ノードのデプロイ
ワークスペースディレクトリ内のノードのみがデプロイおよびスケジュール実行できます。
ワークスペースディレクトリ内のノートブックの場合：設定完了後、上部ツールバーの 公開 ボタンをクリックします。
個人用ディレクトリ内のノートブックの場合：まず 保存 ボタンをクリックし、プロジェクトに送信してからデプロイする必要があります。
デプロイ後、オペレーションセンター の 自動トリガーノード ページでノートブックタスクを監視します。
よくある質問
Q：開発中はコードがパブリックネットワークにアクセスできるのに、スケジュール実行中に失敗するのはなぜですか？
A： 開発環境と本番環境では、異なるネットワークポリシーが適用されるためです。
開発環境 (個人用開発環境)：Virtual Private Cloud (VPC) にバインドされていない個人用開発環境は、デフォルトでパブリックネットワークへのアクセスが制限されていますが、一時的にパッケージをインストールしたり API を呼び出したりすることは可能です。
本番環境 (スケジュールタスク)：セキュリティと安定性のために、スケジュールタスクはデフォルトで VPC 内で実行され、パブリックネットワークに直接アクセスすることはできません。タスクのネットワーク設定は、スケジューリング設定 で選択したリソースグループによって決定されます。そのリソースグループの VPC に NAT ゲートウェイが設定されていない場合、タスクはパブリックネットワークにアクセスできません。
解決策： 個人用開発環境とサーバーレスリソースグループが同じ VPC を使用するように設定します。
Q：開発環境ではコードが正常に実行されるのに、スケジュール実行中にサードパーティパッケージが見つからずに失敗するのはなぜですか？
A： すべての依存関係をカスタムイメージにパッケージ化し、スケジューリング設定 でそれを選択してください。「個人用開発環境から DataWorks イメージを作成する」をご参照ください。
Q：Python カーネルのバージョンを変更するにはどうすればよいですか？
A： 個人用開発環境のターミナル
で異なる Python バージョンをインストールします。その後、ノートブックツールバーの右側にある 
ボタンをクリックしてカーネルのバージョンを切り替えます。新しいカーネルバージョンには SQL セルに必要な依存関係が含まれていない可能性があるため、追加の Python カーネルをインストールすることは推奨されません。