Updating model metadata

Overview

This page shows you how to update BigQuery ML model metadata. You can update model metadata by:

• Using the Cloud Console.
• Using the bq update command in the bq command-line tool.
• Calling the models.patch API method directly or by using the client libraries.

The following model metadata can be updated:

• Description: Can be updated by using the Cloud Console, bq command-line tool, API, or client libraries.
• Labels: Can be updated by using the Cloud Console, bq command-line tool, API, or client libraries.
• Expiration time: Can be updated by using the bq command-line tool, API, or client libraries.

Required permissions

To update model metadata, you must be assigned the WRITER role on the dataset, or you must be assigned a project-level IAM role that includes bigquery.models.updateMetadata permissions. If you are granted bigquery.models.updateMetadata permissions at the project level, you can update metadata for models in any dataset in the project. The following predefined, project-level IAM roles include bigquery.models.updateMetadata permissions:

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

For more information on IAM roles and permissions in BigQuery ML, see Access control. For more information on dataset-level roles, see Basic roles for datasets in the BigQuery documentation.

Updating a model's description

A model's description is a text string that is used to easily identify the model.

To update a model's description:

Console

1. In the Cloud Console, go to the BigQuery page.

   Go to the BigQuery page

2. In the navigation panel, in the Resources section, expand your project name and dataset name.

3. Click your model name. Models are indicated by the model icon: .

4. Click the Details tab.

5. To update the model's description, click the edit icon (pencil) to the right of Description.

6. In the Edit description dialog, enter your text and then click Update.

bq

To update a model's description, issue the bq update command with the --model or -m flag and the --description flag.

If you are updating a model in a project other than your default project, add the project ID to the dataset in the following format: [PROJECT_ID]:[DATASET].

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

Where:

• [STRING] is the text string that describes your model in quotes.
• [PROJECT_ID] is your project ID.
• [DATASET] is the name of the dataset.
• [MODEL] is the name of the model.

The command output looks like the following:

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

You can confirm your changes by issuing the bq show command. For more information, see Getting model metadata.

Examples:

Enter the following command to update the description of mymodel in mydataset in your default project.

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

Enter the following command to update the description of mymodel in mydataset in myotherproject.

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

API

To update a model's description by using the API, call the models.patch method and provide the projectId, datasetId, and modelId. To modify the description, add to or update the "description" property for the model resource.

Go

View on GitHub Feedback

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: %v", err)
	}
	defer client.Close()

	model := client.Dataset(datasetID).Model(modelID)
	oldMeta, err := model.Metadata(ctx)
	if err != nil {
		return fmt.Errorf("Metadata: %v", 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("Update: %v", err)
	}
	return nil
}

Java

View on GitHub Feedback

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

View on GitHub Feedback

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

View on GitHub Feedback

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

Updating a model's labels

Labels are key-value pairs that you can attach to a resource. When you create BigQuery ML resources, labels are optional. For more information, see Adding and using labels in the BigQuery documentation.

To update a model's labels:

Console

1. In the Cloud Console, go to the BigQuery page.

   Go to the BigQuery page

2. In the navigation panel, in the Resources section, expand your project name and dataset name.

3. Click your model name. Models are indicated by the model icon: .

4. Click the Details tab.

5. To update the model's labels, click the edit icon (pencil) to the right of Labels.

6. In the Edit labels dialog:

   • To apply additional labels, click Add label. Each key can be used only once per dataset, but you can use the same key in different datasets in the same project.
   • Modify the existing keys or values to update a label.
   • Click Update to save your changes.

bq

To update a model's labels, issue the bq update command with the --model or -m flag and the --set_label flag. Repeat the --set_label flag to add or update multiple labels.

If you are updating a model in a project other than your default project, add the project ID to the dataset in the following format: [PROJECT_ID]:[DATASET].

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

Where:

• [KEY:VALUE] corresponds to a key:value pair for a label that you want to add or update. If you specify the same key as an existing label, the value for the existing label is updated. The key must be unique.
• [PROJECT_ID] is your project ID.
• [DATASET] is the name of the dataset.
• [MODEL] is the name of the model.

The command output looks like the following.

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

You can confirm your changes by issuing the bq show command. For more information, see Getting model metadata.

Examples:

To update the department label on mymodel, enter the bq update command and specify department as the label key. For example, to update the department:shipping label to department:logistics, enter the following command. mydataset is in myotherproject, not your default project.

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

API

To update a model's labels by using the API, call the models.patch method and provide the projectId, datasetId, and modelId. To modify the labels, add to or update the "labels" property for the model resource.

Updating a model's expiration time

A model's expiration time is a timestamp value that dictates when a model is deleted. You can set a model's expiration time when the model is created by using the CLI, the API, or the client libraries. You can also set or update the expiration time on a model after it is created. A model's expiration time is often referred to as "time to live" or TTL.

If you do not set an expiration time on a model, the model never expires and you must delete the model manually.

Note: Setting or updating the expiration time on a model is not currently supported by the Cloud Console.

The value for the expiration time is expressed differently depending on where the value is set. Use the method that gives you the appropriate level of granularity:

• In the command-line tool, expiration is expressed in seconds from the current UTC time. When you specify the expiration on the command line, the integer value in seconds is added to the current UTC timestamp.
• In the API, expiration is expressed in milliseconds since the epoch. If you specify an expiration value that is less than the current timestamp, the model expires immediately.

To update the expiration time for a model:

Console

Setting or updating the expiration time on a model is not currently supported by the Cloud Console.

bq

To update a model's expiration time, issue the bq update command with the --model or -m flag and the --expiration flag.

If you are updating a model in a project other than your default project, add the project ID to the dataset in the following format: [PROJECT_ID]:[DATASET].

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

Where:

• [INTEGER] is the lifetime (in seconds) for the model. The minimum value is 3600 seconds (one hour). The expiration time evaluates to the current UTC time plus the integer value.
• [PROJECT_ID] is your project ID.
• [DATASET] is the name of the dataset.
• [MODEL] is the name of the model.

The command output looks like the following.

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

You can confirm your changes by issuing the bq show command. For more information, see Getting model metadata.

Examples:

Enter the following command to update the expiration time of mymodel in mydataset to 5 days (432000 seconds). mydataset is in your default project.

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

Enter the following command to update the expiration time of mymodel in mydataset to 5 days (432000 seconds). mydataset is in myotherproject, not your default project.

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

API

To update a model's expiration by using the API, call the models.patch method and provide the projectId, datasetId, and modelId. To modify the expiration, add to or update the "expirationTime" property for the model resource. "expirationTime" is expressed in milliseconds since the epoch.

What's next

• For an overview of BigQuery ML, see Introduction to BigQuery ML.
• To get started using BigQuery ML, see Getting started with BigQuery ML using the Cloud Console.
• To learn more about working with models, see:
  • Getting model metadata
  • Listing models
  • Managing models
  • Deleting models