ノートブックを作成する

このドキュメントでは、BigQuery で Colab Enterprise ノートブックを作成する方法について説明します。ノートブックは、Dataform が提供する BigQuery Studio コードアセットです。

始める前に

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

必要な権限

ノートブックを作成、編集、表示するための適切な権限を設定します。

Dataform 管理者（roles/dataform.admin）ロールを持つすべてのユーザーは、プロジェクトで作成されたすべてのノートブックに対するオーナー アクセス権を持ちます。

BigQuery Identity and Access Management（IAM）の詳細については、IAM によるアクセス制御をご覧ください。

ノートブックを作成する権限

ノートブックの作成と実行に必要な権限を取得するには、次の IAM ロールを付与するよう管理者に依頼してください。

• BigQuery 読み取りセッション ユーザー（roles/bigquery.readSessionUser）

• BigQuery Studio ユーザー（roles/bigquery.studioUser） BigQuery Studio ユーザーロールは、次の IAM ロールを組み合わせたものです。

  • BigQuery ジョブユーザー（roles/bigquery.jobUser）
  • ノートブック ランタイム ユーザー（roles/aiplatform.notebookRuntimeUser）

  • コード作成者（roles/dataform.codeCreator）

    注: プロジェクトでコード作成者ロールが割り当てられているユーザーは、Dataform API または Dataform コマンドライン インターフェース（CLI）を使用して、そのプロジェクトのコードアセットの名前を一覧取得できます。BigQuery Studio を使用する管理者以外のユーザーは、自身が作成したコードアセットまたは自身と共有されているコードアセットのみを表示できます。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。ノートブックの作成と実行に必要な権限を確認するには、[必要な権限] セクションを開きます。

必要な権限

• bigquery.config.get
• bigquery.jobs.create
• bigquery.readsessions.create
• bigquery.readsessions.getData
• bigquery.readsessions.update
• resourcemanager.projects.get
• resourcemanager.projects.list
• dataform.locations.get
• dataform.locations.list
• dataform.repositories.create
注: dataform.repositories.create 権限を持つユーザーは、デフォルトの Dataform サービス アカウントと、そのサービス アカウントに付与されたすべての権限を使用してコードを実行できます。詳細については、Dataform 権限のセキュリティに関する考慮事項をご覧ください。
• dataform.repositories.list
• dataform.collections.create
• dataform.collections.list
• aiplatform.notebookRuntimeTemplates.apply
• aiplatform.notebookRuntimeTemplates.get
• aiplatform.notebookRuntimeTemplates.list
• aiplatform.notebookRuntimeTemplates.getIamPolicy
• aiplatform.notebookRuntimes.assign
• aiplatform.notebookRuntimes.get
• aiplatform.notebookRuntimes.list
• aiplatform.operations.list

ノートブックを編集するロール

ノートブックを編集して実行するには、次の IAM ロールが必要です。

• BigQuery ジョブユーザー（roles/bigquery.jobUser）
• BigQuery 読み取りセッション ユーザー（roles/bigquery.readSessionUser）
• ノートブック ランタイム ユーザー（roles/aiplatform.notebookRuntimeUser）
• コードエディタ（roles/dataform.codeEditor）

ノートブックを表示するロール

ノートブックを表示して実行するには、次の IAM ロールが必要です。

• BigQuery ジョブユーザー（roles/bigquery.jobUser）
• BigQuery 読み取りセッション ユーザー（roles/bigquery.readSessionUser）
• ノートブック ランタイム ユーザー（roles/aiplatform.notebookRuntimeUser）
• コード閲覧者（roles/dataform.codeViewer）

ノートブックを作成する

ノートブックの作成方法については、次のセクションをご覧ください。

コードアセットにデフォルトのリージョンを設定する

コードアセットを初めて作成する場合は、コードアセットのデフォルト リージョンを設定する必要があります。コードアセットのリージョンを作成後に変更することはできません。

注: ノートブックを作成し、コードアセットに使用しているリージョンとは異なるデフォルト リージョンを選択する（たとえば us-west1 使用している場合に us-central1を選択する）と、そのノートブックと、その後に作成したすべてのコードアセットでは、デフォルトで新しいリージョンが使用されます。既存のコードアセットでは、作成時に割り当てられたリージョンが引き続き使用されます。

BigQuery Studio のすべてのコードアセットは同じデフォルト リージョンを使用します。コードアセットのデフォルト リージョンを設定する手順は次のとおりです。

1. [BigQuery] ページに移動します。

   [BigQuery] に移動

2. [エクスプローラ] ペインで、コードアセットを有効にしたプロジェクトを見つけます。

3. プロジェクトの横にある （アクションを表示）をクリックし、[デフォルトのコード リージョンを変更] をクリックします。

4. [リージョン] で、コードアセットに使用するリージョンを選択します。

5. [選択] をクリックします。

サポートされているリージョンの一覧については、BigQuery Studio のロケーションをご覧ください。

ノートブック ギャラリーを使用してノートブックを作成する

プレビュー版

この機能は サービス固有の規約の対象となります。 一般提供前の機能は「現状のまま」で提供されるものであり、サポートが制限されることがあります。 詳細については、リリース ステージの説明をご覧ください。

注: フィードバックの提供やプロダクトの機能強化のリクエストについては、[e-mail] までお問い合わせください。

BigQuery の Google Cloud コンソールのノートブック ギャラリーは、構築済みのノートブック テンプレートを見つけて使用するための中央ハブです。

ノートブック ギャラリーのテンプレートからノートブックを作成する手順は次のとおりです。

1. [BigQuery] ページに移動します。

   [BigQuery] に移動

2. ギャラリーを開くには、エディタペインのタブバーで、 [SQL クエリ] の横にある 矢印をクリックし、[ノートブック > すべてのテンプレート] をクリックします。

3. ノートブック ギャラリーでテンプレートを選択します。たとえば、[BigQuery DataFrames のスタートガイド] を選択します。

   新しいノートブックが開き、bigquery-public-data.ml_datasets.penguins 一般公開データセットに対するクエリの例を示すセルが表示されます。

4. または、 SQL クエリの横にある 矢印をクリックし、[ノートブック] > [空のノートブック]、[ノートブック] > [BigQuery テンプレート]、または [ノートブック] > [Spark テンプレート] をクリックして、これらの特定のテンプレートを開くこともできます。

5. テンプレートから実行可能なノートブックを作成するには、[このテンプレートを使用] をクリックします。

6. 省略可: ノートブックの詳細やバージョン履歴を表示する、新しいコメントを追加する、既存のコメントに返信する、または既存のコメントへのリンクを取得するには、次のツールバーを使用します。

   

   [詳細]、[変更履歴]、[コメント] のツールバー機能はプレビュー版です。これらの機能に関するフィードバックやサポートをリクエストする場合は、[e-mail] までメールをお送りください。

7. 省略可: ツールバーの [リファレンス] パネルを使用して、テーブル、スナップショット、ビュー、マテリアライズド ビューのスキーマの詳細をプレビューしたり、新しいタブで開いたりすることができます。このパネルには、最近使用したリソースとスター付きリソースの一覧も表示されます。

テーブルからノートブックを作成する

特定のテーブル用のデフォルト クエリを含むノートブックを作成する手順は、次のとおりです。

1. [BigQuery] ページに移動します。

   BigQuery に移動

2. 左側のペインで、 [エクスプローラ] をクリックします。

   

   左側のペインが表示されていない場合は、 左側のペインを開くをクリックしてペインを開きます。

3. [エクスプローラ] ペインで、プロジェクトを開き、[データセット] をクリックして、データセットをクリックします。

4. [概要 > テーブル] をクリックし、クエリするテーブルを見つけます。

5. テーブルの横にある （アクション）をクリックし、[次で開く] > [Python ノートブック] をクリックします。

   新しいノートブックが開き、選択したテーブルに対するクエリの例が表示されます。

クエリの結果セットを調べるためのノートブックを作成する

クエリの結果セットを調べるノートブックを作成する手順は次のとおりです。

1. [BigQuery] ページに移動します。

   BigQuery に移動

2. エディタペインで、クエリ結果を生成するクエリを実行します。

3. [クエリ結果] ペインで、[次で開く] > [ノートブック] をクリックします。

   新しいノートブックが開き、クエリ SQL とクエリ結果を返すコードを含むセルが表示されます。

既存のノートブックからノートブックを作成する

既存のノートブックの任意のバージョンを新しいノートブックとして開くには、次の操作を行います。

1. Google Cloud コンソールで、[BigQuery] ページに移動します。

   BigQuery に移動

2. 左側のペインで、 [エクスプローラ] をクリックします。

   

3. [エクスプローラ] ペインで、プロジェクトを開き、[ノートブック] をクリックします。

4. ノートブックを選択します。

5. [変更履歴] をクリックします。

6. ノートブック バージョンの横にある （アクションを表示）をクリックし、[新しい Python ノートブックとして開く] をクリックします。

   ノートブックのコピーが新しいノートブックとして開かれます。

ノートブックをアップロードする

ローカル ノートブックをアップロードして、BigQuery Studio で使用できるようにします。アップロードされたノートブックは、 Google Cloud コンソールの BigQuery ページに表示されます。

ノートブックをアップロードするには、次の操作を行います。

1. Google Cloud コンソールで、[BigQuery] ページに移動します。

   BigQuery に移動

2. 左側のペインで、 [エクスプローラ] をクリックします。

   

3. [エクスプローラ] ペインでプロジェクトを開き、次のいずれかを行います。

   • [ノートブック] の横にある （アクションを表示）> [Notebooks にアップロード] をクリックします。
   • Google Cloud プロジェクト名の横にある （アクションを表示）> [プロジェクトにアップロードする] > [ノートブック] をクリックします。

4. [ノートブックのアップロード] ダイアログの [ノートブック] フィールドで、[参照] をクリックして、アップロードするノートブックを選択します。

5. 省略可: [ノートブック名] フィールドで、ノートブック ファイルの名前を編集します。

6. [リージョン] フィールドで、ノートブックをアップロードするリージョンを選択します。

7. [アップロード] をクリックします。

ノートブックには、[エクスプローラ] ペインからアクセスできます。

ランタイムに接続する

以降のセクションでは、ノートブックを Vertex AI ランタイムに接続する方法について説明します。ランタイムは、ノートブックでコードを実行するコンピューティング リソースです。ランタイムは、ノートブックと同じリージョンに存在する必要があります。

ランタイムの詳細については、ランタイムとランタイム テンプレートをご覧ください。

注: VPC Service Controls を使用する場合は、ランタイムに接続する前に、VPC Service Controls でプライベート Google アクセスを構成していることを確認してください。それ以外の場合、サービスは Failed to connect to Runtime Network projects/projectid/global/networks/default' was not found.
エラーを返します。

デフォルトのランタイムに接続する

デフォルトのランタイムは、最小限の設定が必要なプリセット ランタイムです。

デフォルトのランタイムに接続する手順は、次のとおりです。

1. Google Cloud コンソールで、[BigQuery] ページに移動します。

   BigQuery に移動

2. 左側のペインで、 [エクスプローラ] をクリックします。

   

3. [エクスプローラ] ペインで、プロジェクトを開き、[ノートブック] をクリックします。

4. ノートブックの名前をクリックして開きます。

5. ノートブックで [接続] をクリックするか、ノートブックの任意のセルを実行します。

   アクティブなランタイムがない場合、デフォルトのランタイムへの接続に数分かかることがあります。

デフォルト以外のランタイムに接続する

デフォルト ランタイム以外のランタイムを使用する場合は、まず Vertex AI で追加のランタイムを作成する必要があります。

デフォルト以外のランタイムに接続する手順は、次のとおりです。

1. Google Cloud コンソールで、[BigQuery] ページに移動します。

   BigQuery に移動

2. 左側のペインで、 [エクスプローラ] をクリックします。

   

3. [エクスプローラ] ペインで、プロジェクトを開き、[ノートブック] をクリックします。

4. ノートブックの名前をクリックして開きます。

5. ノートブックで、[接続] の横にある プルダウンをクリックし、[Connect to a runtime] をクリックします。

6. [既存のランタイムに接続します] をクリックします。

7. [ランタイム] で、使用するランタイムを選択します。ランタイムは、ノートブックと同じ場所に存在する必要があります。

8. [接続] をクリックします。

新しいランタイムに接続する

新しいランタイムに接続する手順は、次のとおりです。

1. Google Cloud コンソールで、[BigQuery] ページに移動します。

   BigQuery に移動

2. 左側のペインで、 [エクスプローラ] をクリックします。

   

3. [エクスプローラ] ペインで、プロジェクトを開き、[ノートブック] をクリックします。

4. ノートブックの名前をクリックして開きます。

5. ノートブックで、[接続] の横にある プルダウンをクリックし、[Connect to a runtime] をクリックします。

6. [ランタイムを新規作成します] をクリックします。

7. [ランタイム テンプレート] で、使用する Vertex AI ランタイム テンプレートを選択します。

8. [ランタイム名] にランタイムの名前を入力します。

9. [接続] をクリックします。

セルについて

ノートブックは、編集可能なセルで構成されています。次のタイプのセルがサポートされています。

• テキストセル: テキストセルを使用して、マークダウンでノートブックに説明と画像を追加します。
• コードセル: コードセルを使用して、ノートブックに Python を追加します。各コードセルを個別に実行できます。コードセルは、すでに実行した別のセルで作成された変数であれば、どれでも参照できます。

• SQL セル（プレビュー）: SQL セルを使用して GoogleSQL クエリを実行します。クエリの出力は、セルのタイトルと同じ名前の DataFrame として自動的に保存されます。1 つの SQL セルで複数の SQL ステートメントを実行できますが、DataFrame に保存されるのは最後のステートメントの結果のみです。

  式で Python 変数を参照したり、変数名を中かっこ（{ }）で囲んで BigQuery DataFrames をクエリのテーブルとして使用したりできます。

  # Refer to the Python variable my_threshold in a SQL expression.
  SELECT * FROM my_dataset.my_table WHERE x > {my_threshold};
  
  # Reference previous query results to iterate on your queries.
  SELECT * FROM {df};
  

ノートブックへのアクセス権を付与する

他のユーザーにノートブックへのアクセス権を付与するには、そのユーザーを適切な IAM ロールに追加します。

重要: ノートブックにアクセスできるユーザーは、ノートブック内のコードによって生成されたすべての出力を表示できます。自分がアクセスできないテーブルのデータが含まれた出力でも表示できます。保存した出力が共有されないようにするには、ノートブックの出力保存を無効にします。

1. Google Cloud コンソールで、[BigQuery] ページに移動します。

   BigQuery に移動

2. 左側のペインで、 [エクスプローラ] をクリックします。

   

   左側のペインが表示されていない場合は、 左側のペインを開くをクリックしてペインを開きます。

3. [エクスプローラ] ペインで、プロジェクトを開き、[ノートブック] をクリックします。

4. アクセス権を付与するノートブックを見つけます。

5. ノートブックの横にある （アクションを開く）をクリックし、[共有] をクリックします。

6. [共有権限] ペインで、[ユーザー/グループを追加] をクリックします。

7. [新しいプリンシパル] フィールドに、プリンシパルを入力します。

8. [ロール] リストで、次のいずれかのロールを選択します。

   • コードオーナー: ノートブックの削除や共有など、ノートブックに対するあらゆるアクションを実行できます。
   • コードエディタ: ノートブックを編集できます。
   • コード閲覧者: ノートブックを表示できます。
   注: また、ノートブックを実行するには、プリンシパルにノートブック ランタイム ユーザー（roles/aiplatform.notebookRuntimeUser）と BigQuery ユーザー（roles/bigquery.user）のロールが必要です。

9. 省略可: ロールと詳細な共有設定の完全なリストを表示するには、[詳細な共有] をクリックします。

10. [保存] をクリックします。

11. ノートブック情報ページに戻るには、[閉じる] をクリックします。

ノートブックを共有する

ノートブックを他のユーザーと共有するには、ノートブックへのリンクを生成して共有します。共有したノートブックを他のユーザーに表示するには、最初にノートブックへのアクセス権を付与する必要があります。

ノートブックを実行するには、ノートブックがアクセスするデータにユーザーがアクセスできる必要があります。詳細については、データセットへのアクセス権を付与するをご覧ください。

重要: ノートブックにアクセスできるユーザーは、ノートブック内のコードによって生成されたすべての出力を表示できます。自分がアクセスできないテーブルのデータが含まれた出力でも表示できます。保存した出力が共有されないようにするには、ノートブックの出力保存を無効にします。

1. Google Cloud コンソールで、[BigQuery] ページに移動します。

   BigQuery に移動

2. 左側のペインで、 [エクスプローラ] をクリックします。

   

   左側のペインが表示されていない場合は、 左側のペインを開くをクリックしてペインを開きます。

3. [エクスプローラ] ペインで、プロジェクトを開き、[ノートブック] をクリックします。

4. 共有するノートブックを見つけます。検索機能またはフィルタを使用して、ノートブックを見つけることができます。

5. ノートブックの横にある （アクションを表示）をクリックし、[共有] > [リンクをコピー] をクリックします。

6. リンクを他のユーザーと共有します。

ノートブックの出力保存を無効にする

ノートブックの出力保存を無効にすると、ノートブック ファイルにアクセスできる他のユーザーと保存済みのノートブック出力を共有できなくなります。

選択したノートブックの出力保存を無効にすると、BigQuery はノートブック ファイルに保存されているすべての出力を削除し、その後の実行の出力は保存されません。

ただし、ノートブックにアクセスできるユーザーは、次の方法で出力を表示できます。

• ノートブックを実行して、現在の出力を確認します。この出力は保存されません。
• ノートブックのアーカイブ バージョンとその出力をリビジョン履歴で確認します。

選択したノートブックの出力保存を無効にするには、次の操作を行います。

1. Google Cloud コンソールで、[BigQuery] ページに移動します。

   BigQuery に移動

2. 左側のペインで、 [エクスプローラ] をクリックします。

   

   左側のペインが表示されていない場合は、 左側のペインを開くをクリックしてペインを開きます。

3. [エクスプローラ] ペインで、プロジェクトを開き、[ノートブック] をクリックします。

4. 出力を保存しないようにするノートブックをクリックします。

5. メニューバーを展開するには、keyboard_arrow_down（ヘッダーの表示 / 非表示を切り替える）をクリックします。

6. [編集> ノートブックの設定] をクリックします。

7. [Notebook settings] ウィンドウで、[Omit code cell output when saving this notebook] を選択します。

8. [保存] をクリックします。

9. [再読み込み] をクリックします。

競合を解決する

ユーザーと別のユーザーがノートブックで競合する変更を加えると、Automatic saving failed. This file was updated remotely or in another tab. エラーが返され、Show diff リンクが提供されます。競合を解決する手順は次のとおりです。

1. Show diff リンクをクリックします。[リモート変更の確認] ダイアログが開きます。
2. 省略可: ノートブックのソースコードを比較するには、[元の形式のソース] チェックボックスをオンにします。
3. 省略可: 個別のペインではなく、インラインでバージョンを比較するには、[インラインで差分を表示] チェックボックスをオンにします。
4. 変更内容を確認して、どれを残すかを判断し、必要に応じて入力を変更します。
5. [変更を保存] をクリックします。

ノートブックの名前を変更する

ノートブックの名前を変更するには、次の操作を行います。

1. Google Cloud コンソールで、[BigQuery] ページに移動します。

   BigQuery に移動

2. 左側のペインで、 [エクスプローラ] をクリックします。

   

3. [エクスプローラ] ペインで、プロジェクトを開き、[ノートブック] をクリックします。

4. 名前を変更するノートブックをクリックします。

5. keyboard_arrow_down [ヘッダーの表示 / 非表示を切り替える] をクリックして、メニューバーを開きます。

6. [File> Rename] をクリックします。

7. [ノートブック名の変更] ダイアログで、ノートブックの名前を入力して [名前を変更] をクリックします。

トラブルシューティング

詳細については、Colab Enterprise のトラブルシューティングをご覧ください。

次のステップ

• ノートブックを管理する方法を確認する。
• ノートブックのスケジュールを設定する方法を学習する。