モデルのメタデータを更新する

このページでは、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 ロールと権限の詳細については、アクセス制御をご覧ください。

モデルの説明を更新する

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

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

コンソール

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

[BigQuery] ページに移動
ナビゲーションパネルの [リソース] セクションで、プロジェクト名とデータセット名を展開します。
モデル名をクリックします。モデルにはモデルアイコンがついています。
[詳細] タブをクリックします。
モデルの説明を更新するには、[説明] の右側にある編集アイコン（鉛筆）をクリックします。
[説明を編集] ダイアログで、テキストを入力して [更新] をクリックします。

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 のリファレンスドキュメントをご覧ください。

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 のリファレンスドキュメントをご覧ください。

// 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 のリファレンスドキュメントをご覧ください。


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 のリソースを作成する際には、ラベルは必須ではありません。詳細については、ラベルの追加と使用をご覧ください。

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

コンソール

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

[BigQuery] ページに移動
ナビゲーションパネルの [リソース] セクションで、プロジェクト名とデータセット名を展開します。
モデル名をクリックします。モデルにはモデルアイコンがついています。
[詳細] タブをクリックします。
モデルのラベルを更新するには、[ラベル] の右側にある編集アイコン（鉛筆）をクリックします。
[ラベルを編集] ダイアログで、次の操作を行います。
- 追加のラベルを適用するには、[ラベルを追加] をクリックします。各キーはデータセットごとに 1 度しか使用できませんが、同じキーが同じプロジェクト内の複数のデータセットで使用できます。
- ラベルを更新するには、既存のキーまたは値を変更します。
- [更新] をクリックして、変更を保存します。

bq

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

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 コマンドを実行します。

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 プロパティは、エポックからのミリ秒単位で表されます。

次のステップ

BigQuery ML の概要で BigQuery ML の概要を確認する。
BigQuery ML の使用を開始するには、BigQuery ML で機械学習モデルを作成するをご覧ください。
モデルを使った作業の詳細を確認するには、以下をご覧ください。