モデル メタデータの更新

概要

このページでは、BigQuery ML モデルのメタデータの更新方法を紹介します。次の方法で、モデル メタデータを更新できます。

  • Google Cloud コンソールを使用する。
  • bq コマンドライン ツールの bq update コマンドを使用する。
  • models.patch API メソッドを、直接またはクライアント ライブラリを使用して呼び出す。

次のモデル メタデータを更新できます。

  • 説明: Google Cloud コンソール、bq コマンドライン ツール、API、またはクライアント ライブラリを使用して更新できます。
  • ラベル: Google Cloud コンソール、bq コマンドライン ツール、API、またはクライアント ライブラリを使用して更新できます。
  • 有効期限: bq ツール、API、またはクライアント ライブラリを使用して更新できます。

必要な権限

モデル メタデータを更新するには、データセットに対する WRITER ロールが割り当てられているか、bigquery.models.updateMetadata 権限を含むプロジェクト レベルの Identity and Access Management（IAM）ロールが割り当てられている必要があります。プロジェクト レベルで bigquery.models.updateMetadata 権限が付与されている場合は、プロジェクト内の任意のデータセット内のモデルのメタデータを更新できます。プロジェクト レベルの次の IAM 事前定義ロールには bigquery.models.updateMetadata 権限が含まれています。

  • bigquery.dataEditor
  • bigquery.dataOwner
  • bigquery.admin

BigQuery ML での IAM ロールと権限の詳細については、アクセス制御をご覧ください。

モデルの説明を更新する

モデルの説明は、モデルを簡単に識別するために使われるテキスト文字列です。

モデルの説明を更新する手順は以下のとおりです。

コンソール

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

    [BigQuery] ページに移動

  2. ナビゲーション パネルの [リソース] セクションで、プロジェクト名とデータセット名を展開します。

  3. モデル名をクリックします。モデルにはモデルアイコン モデルアイコン がついています。

  4. [詳細] タブをクリックします。

  5. モデルの説明を更新するには、[説明] の右側にある編集アイコン（鉛筆）をクリックします。

  6. [説明を編集] ダイアログで、テキストを入力して [更新] をクリックします。

bq

モデルの説明を更新するには、--model または -m フラグと --description フラグを指定して bq update コマンドを実行します。

更新するモデルがデフォルト プロジェクト以外のプロジェクトにある場合は、[PROJECT_ID]:[DATASET] の形式でプロジェクト ID をデータセットに追加します。

bq update --model --description "[STRING]" [PROJECT_ID]:[DATASET].[MODEL]

ここで

  • [STRING] は、モデルを引用符で囲んで記述したテキスト文字列です。
  • [PROJECT_ID] はプロジェクト ID です。
  • [DATASET] はデータセットの名前です。
  • [MODEL] はモデルの名前です。

コマンド出力は、次のようになります。

Model '[PROJECT_ID]:[DATASET].[MODEL]' successfully updated.

bq show コマンドを実行して、変更を確認できます。詳細については、モデル メタデータの取得をご覧ください。

例:

デフォルト プロジェクトの mydataset 内にある mymodel の説明を更新するには、次のコマンドを入力します。

bq update --model --description "My updated description" \
mydataset.mymodel

myotherproject の mydataset 内にある mymodel の説明を更新するには、次のコマンドを入力します。

bq update --model --description "My updated description" \
myotherproject:mydataset.mymodel

API

API を使用してモデルの説明を更新するには、models.patch メソッドを呼び出し、projectId、datasetId、modelId を指定します。説明を変更するには、モデルリソースの description プロパティを追加または更新します。

Go

このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートの Go の手順に沿って設定を行ってください。詳細については、BigQuery Go API のリファレンス ドキュメントをご覧ください。

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証を設定するをご覧ください。

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// updateModelDescription demonstrates fetching BigQuery ML model metadata and updating the
// Description metadata.
func updateModelDescription(projectID, datasetID, modelID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// modelID := "mymodel"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %w", err)
	}
	defer client.Close()

	model := client.Dataset(datasetID).Model(modelID)
	oldMeta, err := model.Metadata(ctx)
	if err != nil {
		return fmt.Errorf("couldn't retrieve model metadata: %w", err)
	}
	update := bigquery.ModelMetadataToUpdate{
		Description: "This model was modified from a Go program",
	}
	if _, err = model.Update(ctx, update, oldMeta.ETag); err != nil {
		return fmt.Errorf("couldn't update model: %w", err)
	}
	return nil
}

Java

このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートの Java の手順に沿って設定を行ってください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証を設定するをご覧ください。

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Model;
import com.google.cloud.bigquery.ModelId;

// Sample to update description on a model
public class UpdateModelDescription {

  public static void runUpdateModelDescription() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String modelName = "MY_MODEL_NAME";
    String newDescription = "A really great model.";
    updateModelDescription(datasetName, modelName, newDescription);
  }

  public static void updateModelDescription(
      String datasetName, String modelName, String newDescription) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      Model model = bigquery.getModel(ModelId.of(datasetName, modelName));
      bigquery.update(model.toBuilder().setDescription(newDescription).build());
      System.out.println("Model description updated successfully to " + newDescription);
    } catch (BigQueryException e) {
      System.out.println("Model description was not updated \n" + e.toString());
    }
  }
}

Node.js

このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートの Node.js の手順に沿って設定を行ってください。詳細については、BigQuery Node.js API のリファレンス ドキュメントをご覧ください。

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証を設定するをご覧ください。

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function updateModel() {
  // Updates a model's metadata.

  /**
   * TODO(developer): Uncomment the following lines before running the sample
   */
  // const datasetId = "my_dataset";
  // const modelId = "my__model";

  const metadata = {
    description: 'A really great model.',
  };

  const dataset = bigquery.dataset(datasetId);
  const [apiResponse] = await dataset.model(modelId).setMetadata(metadata);
  const newDescription = apiResponse.description;

  console.log(`${modelId} description: ${newDescription}`);
}

Python

このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートの Python の手順に沿って設定を行ってください。詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証を設定するをご覧ください。


from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set model_id to the ID of the model to fetch.
# model_id = 'your-project.your_dataset.your_model'

model = client.get_model(model_id)  # Make an API request.
model.description = "This model was modified from a Python program."
model = client.update_model(model, ["description"])  # Make an API request.

full_model_id = "{}.{}.{}".format(model.project, model.dataset_id, model.model_id)
print(
    "Updated model '{}' with description '{}'.".format(
        full_model_id, model.description
    )
)

モデルのラベルを更新する

ラベルは、リソースに添付可能な Key-Value ペアです。BigQuery ML のリソースを作成する際には、ラベルは必須ではありません。詳細については、ラベルの追加と使用をご覧ください。

モデルのラベルを更新する手順は以下のとおりです。

コンソール

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

    [BigQuery] ページに移動

  2. ナビゲーション パネルの [リソース] セクションで、プロジェクト名とデータセット名を展開します。

  3. モデル名をクリックします。モデルにはモデルアイコン モデルアイコン がついています。

  4. [詳細] タブをクリックします。

  5. モデルのラベルを更新するには、[ラベル] の右側にある編集アイコン（鉛筆）をクリックします。

  6. [ラベルを編集] ダイアログで、次の操作を行います。

    • 追加のラベルを適用するには、[ラベルを追加] をクリックします。各キーはデータセットごとに 1 度しか使用できませんが、同じキーが同じプロジェクト内の複数のデータセットで使用できます。
    • ラベルを更新するには、既存のキーまたは値を変更します。
    • [更新] をクリックして、変更を保存します。

bq

モデルのラベルを更新するには、--model または -m フラグと --set_label フラグを指定して bq update コマンドを実行します。複数のラベルを追加または更新するには、--set_label フラグを繰り返し指定します。

更新するモデルがデフォルト プロジェクト以外のプロジェクトにある場合は、[PROJECT_ID]:[DATASET] の形式でプロジェクト ID をデータセットに追加します。

bq update --model --set_label [KEY:VALUE] \
[PROJECT_ID]:[DATASET].[MODEL]

ここで

  • [KEY:VALUE] は、追加または更新するラベルの Key-Value ペアに対応します。既存のラベルと同じキーを指定した場合は、その既存ラベルの値が更新されます。キーは一意でなければなりません。
  • [PROJECT_ID] はプロジェクト ID です。
  • [DATASET] はデータセットの名前です。
  • [MODEL] はモデルの名前です。

コマンド出力は、次のようになります。

Model '[PROJECT_ID]:[DATASET].[MODEL]' successfully updated.

bq show コマンドを実行して、変更を確認できます。詳細については、モデル メタデータの取得をご覧ください。

例:

mymodel の department ラベルを更新するには、bq update コマンドを入力し、ラベルキーとして department を指定します。たとえば、department:shipping ラベルを department:logistics に更新するには、次のコマンドを入力します。mydataset はデフォルト プロジェクトではなく myotherproject にあります。

bq update --model --set_label department:logistics \
myotherproject:mydataset.mymodel

API

API を使用してモデルのラベルを更新するには、models.patch メソッドを呼び出し、projectId、datasetId、modelId を指定します。ラベルを変更するには、モデルリソースの labels プロパティを追加または更新します。

モデルの有効期限を更新する

モデルの有効期限は、いつモデルが削除されるかを示すタイムスタンプ値です。モデルの有効期限を設定するには、モデルを作成する際に、CLI、API、クライアント ライブラリを使用します。モデルの作成後にも、有効期限を設定または更新できます。モデルの有効期限は、多くの場合 TTL（time to live）と呼ばれます。

モデルに有効期限を設定しないと、モデルは期限切れにならないため、手動で削除する必要があります。

有効期限の値は、値の設定場所によって異なります。適切な粒度の方法を使用してください。

  • コマンドライン ツールでは、有効期限は現在の UTC 時間からの秒数で表示されます。コマンドラインで有効期限を指定すると、整数値が秒単位で現在の UTC タイムスタンプに追加されます。
  • API では、有効期限はエポックからのミリ秒単位で表されます。現在のタイムスタンプに満たない値を有効期限に指定すると、モデルは直ちに期限切れになります。

次の方法で、モデルの有効期限を更新できます。

コンソール

現在、Google Cloud コンソールではモデルの有効期限の設定や更新ができません。

bq

モデルの有効期限を更新するには、--model フラグまたは -m フラグと --expiration フラグを指定して bq update コマンドを実行します。

更新するモデルがデフォルト プロジェクト以外のプロジェクトにある場合は、[PROJECT_ID]:[DATASET] の形式でプロジェクト ID をデータセットに追加します。

bq update --model --expiration [INTEGER] \
[PROJECT_ID]:[DATASET].[MODEL]

ここで

  • [INTEGER] はモデルの存続期間（秒単位）です。最小値は 3,600 秒（1 時間）です。現在の UTC 時間にこの整数値を足した値が、有効期限になります。
  • [PROJECT_ID] はプロジェクト ID です。
  • [DATASET] はデータセットの名前です。
  • [MODEL] はモデルの名前です。

コマンド出力は、次のようになります。

Model '[PROJECT_ID]:[DATASET].[MODEL]' successfully updated.

bq show コマンドを実行して、変更を確認できます。詳細については、モデル メタデータの取得をご覧ください。

例:

次のコマンドを入力して、mydataset 内の mymodel のパーティションの有効期限を 5 日間（432,000 秒）に更新します。mydataset はデフォルト プロジェクトにあります。

bq update --model --expiration 432000 mydataset.mymodel

次のコマンドを入力して、mydataset 内の mymodel のパーティションの有効期限を 5 日間（432,000 秒）に更新します。mydataset はデフォルト プロジェクトではなく myotherproject にあります。

bq update --model --expiration 432000 myotherproject:mydataset.mymodel

API

API を使用してモデルの有効期限を更新するには、models.patch メソッドを呼び出し、projectId、datasetId、modelId を指定します。有効期限を変更するには、モデルリソースの expirationTime プロパティを追加または更新します。expirationTime プロパティは、エポックからのミリ秒単位で表されます。

次のステップ