Labels zu Ressourcen hinzufügen

In diesem Dokument wird beschrieben, wie Sie BigQuery-Ressourcen mit Labels versehen. Dazu gehören die folgenden Ressourcen:

Datasets
Tabellen und Ansichten
Jobs
Job-Sitzungen
reservations

Weitere Informationen zu Labels in BigQuery finden Sie unter Einführung in Labels.

Hinweis

Weisen Sie Nutzern die erforderlichen IAM-Rollen (Identity and Access Management) zu, damit sie die einzelnen Aufgaben in diesem Dokument ausführen können. Im Abschnitt „Erforderliche IAM-Rollen“ jeder Aufgabe werden die Berechtigungen aufgeführt, die zum Ausführen der jeweiligen Aufgabe erforderlich sind.

Datasets Labels hinzufügen

Sie können einem BigQuery-Dataset bei seiner Erstellung ein Label hinzufügen. Dafür verwenden Sie den Befehl bq mk des bq-Befehlszeilentools oder die API-Methode datasets.insert. Sie können einem Dataset kein Label hinzufügen, wenn Sie es mit der Google Cloud Console erstellen. Sie können jedoch nach der Erstellung ein Dataset-Label hinzufügen. Weitere Informationen zum Erstellen eines Datasets finden Sie unter Dataset erstellen.

Wenn Sie einem Dataset ein Label hinzufügen, wird das Label nicht an Ressourcen innerhalb des Datasets weitergegeben. Tabellen oder Ansichten übernehmen keine Dataset-Labels. Wenn Sie einem Dataset ein Label hinzufügen, ist es in den Speicherabrechnungsdaten enthalten, jedoch nicht in den jobbezogenen Abrechnungsdaten.

Weitere Informationen zum Labelformat finden Sie unter Anforderungen für Labels.

Erforderliche IAM-Rollen

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle BigQuery-Dateninhaber (roles/bigquery.dataOwner) zuzuweisen, um die Berechtigung zu erhalten, die Sie benötigen, um einem vorhandenen Dataset ein Label hinzuzufügen. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Diese vordefinierte Rolle enthält die Berechtigung bigquery.datasets.update, die erforderlich ist, um einem vorhandenen Dataset ein Label hinzuzufügen.

Sie können diese Berechtigung auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

Weitere Informationen zu IAM-Rollen und Berechtigungen in BigQuery finden Sie unter Vordefinierte Rollen und Berechtigungen.

Dataset mit einem Label versehen

So fügen Sie einem Dataset ein Label hinzu, nachdem es erstellt wurde:

Console

Wählen Sie das Dataset in der Google Cloud -Console aus.
Klicken Sie auf der Seite mit den Dataset-Details im Bereich Labels auf Bearbeiten.
Im Dialogfeld Labels bearbeiten gehen Sie so vor:
- Klicken Sie auf Label hinzufügen.
- Geben Sie den Schlüssel und den Wert in die entsprechenden Felder ein. Klicken Sie auf Label hinzufügen, um weitere Labels anzuwenden. Jeder Schlüssel kann pro Dataset nur einmal verwendet werden, Sie können ihn aber in verschiedenen Datasets eines Projekts verwenden.
- Ändern Sie die vorhandenen Schlüssel oder Werte, um ein Label zu aktualisieren.
- Um die Änderungen zu speichern, klicken Sie auf Aktualisieren.

SQL

Verwenden Sie die DDL-Anweisung ALTER SCHEMA SET OPTIONS, um die Labels für ein vorhandenes Dataset festzulegen. Durch diese Aktion werden alle vorhandenen Labels im Dataset überschrieben. Im folgenden Beispiel wird ein Label für das Dataset mydataset festgelegt:

Rufen Sie in der Google Cloud Console die Seite BigQuery auf.

BigQuery aufrufen

Geben Sie im Abfrageeditor die folgende Anweisung ein:

ALTER SCHEMA mydataset
SET OPTIONS (
  labels = [('sensitivity', 'high')]);

Klicken Sie auf Ausführen.

Informationen zum Ausführen von Abfragen finden Sie unter Interaktive Abfrage ausführen.

bq

Zum Hinzufügen eines Labels zu einem vorhandenen Dataset verwenden Sie den Befehl bq update mit dem Flag set_label. Wiederholen Sie das Flag, um mehrerer Labels hinzuzufügen.

Wenn sich das Dataset in einem anderen Projekt als Ihrem Standardprojekt befindet, geben Sie die Projekt-ID im folgenden Format an: PROJECT_ID:DATASET.

bq update --set_label KEY:VALUE PROJECT_ID:DATASET

Ersetzen Sie Folgendes:

KEY:VALUE: Das Schlüssel/Wert-Paar für ein Label, das Sie hinzufügen möchten. Der Schlüssel muss eindeutig sein. Schlüssel und Werte dürfen nur Kleinbuchstaben, Ziffern, Unterstriche und Bindestriche enthalten. Alle Zeichen müssen UTF-8-codiert sein. Internationale Zeichen sind zulässig.
PROJECT_ID: Ihre Projekt-ID.
DATASET ist das Dataset, dem Sie ein Label zuweisen.

Beispiele:

Wenn Sie ein Label hinzufügen möchten, um Departments nachzuverfolgen, verwenden Sie den Befehl bq update und legen Sie department als Labelschlüssel fest. Wenn Sie in Ihrem Standardprojekt beispielsweise ein Label department:shipping zu mydataset hinzufügen möchten, verwenden Sie Folgendes:

    bq update --set_label department:shipping mydataset

Zum Hinzufügen mehrerer Labels zu einem Dataset wiederholen Sie das Flag set_label und geben für jedes Label einen eindeutigen Schlüssel an. Wenn Sie in Ihrem Standardprojekt beispielsweise die Labels department:shipping und cost_center:logistics zu mydataset hinzufügen möchten, verwenden Sie Folgendes:

    bq update \
    --set_label department:shipping \
    --set_label cost_center:logistics \
    mydataset

API

Rufen Sie die Methode datasets.patch auf und geben Sie das Attribut labels für die Dataset-Ressource ein, um einem vorhandenen Dataset ein Label hinzuzufügen.

Da die Methode datasets.update die gesamte Dataset-Ressource ersetzt, sollten Sie stattdessen die Methode datasets.patch verwenden.

Go

Bevor Sie dieses Beispiel anwenden, folgen Sie den Schritten zur Einrichtung von Go in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Go API.

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

import (
	"context"
	"fmt"

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

// addDatasetLabel demonstrates adding label metadata to an existing dataset.
func addDatasetLabel(projectID, datasetID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	ds := client.Dataset(datasetID)
	meta, err := ds.Metadata(ctx)
	if err != nil {
		return err
	}

	update := bigquery.DatasetMetadataToUpdate{}
	update.SetLabel("color", "green")
	if _, err := ds.Update(ctx, update, meta.ETag); err != nil {
		return err
	}
	return nil
}

Java

In diesem Beispiel wird die Google-HTTP-Clientbibliothek für Java verwendet, um eine Anfrage an die BigQuery API zu senden.

Bevor Sie dieses Beispiel ausprobieren, folgen Sie der Java-Einrichtungsanleitung in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Java API.

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;
import java.util.HashMap;
import java.util.Map;

// Sample to updates a label on dataset
public class LabelDataset {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    labelDataset(datasetName);
  }

  public static void labelDataset(String datasetName) {
    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();

      // This example dataset starts with existing label { color: 'green' }
      Dataset dataset = bigquery.getDataset(datasetName);
      // Add label to dataset
      Map<String, String> labels = new HashMap<>();
      labels.put("color", "green");

      dataset.toBuilder().setLabels(labels).build().update();
      System.out.println("Label added successfully");
    } catch (BigQueryException e) {
      System.out.println("Label was not added. \n" + e.toString());
    }
  }
}

Node.js

Bevor Sie dieses Beispiel anwenden, folgen Sie den Schritten zur Einrichtung von Node.js in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Node.js API.

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

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

async function labelDataset() {
  // Updates a label on a dataset.

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

  // Retrieve current dataset metadata.
  const dataset = bigquery.dataset(datasetId);
  const [metadata] = await dataset.getMetadata();

  // Add label to dataset metadata
  metadata.labels = {color: 'green'};
  const [apiResponse] = await dataset.setMetadata(metadata);

  console.log(`${datasetId} labels:`);
  console.log(apiResponse.labels);
}

Python

Bevor Sie dieses Beispiel anwenden, folgen Sie den Schritten zur Einrichtung von Python in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Python API.

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.


from google.cloud import bigquery

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

# TODO(developer): Set dataset_id to the ID of the dataset to fetch.
# dataset_id = "your-project.your_dataset"

dataset = client.get_dataset(dataset_id)  # Make an API request.
dataset.labels = {"color": "green"}
dataset = client.update_dataset(dataset, ["labels"])  # Make an API request.

print("Labels added to {}".format(dataset_id))

Tabellen und Ansichten Labels hinzufügen

In diesem Dokument wird beschrieben, wie Sie einer vorhandenen Tabelle oder Ansicht ein Label hinzufügen. Weitere Informationen zum Hinzufügen eines Labels beim Erstellen einer Tabelle oder Ansicht finden Sie unter Tabelle erstellen bzw. Ansicht erstellen.

Da Ansichten wie Tabellenressourcen behandelt werden, können Sie mit der Methode tables.patch sowohl Ansichten als auch Tabellen ändern.

Tabellen- und Ansichtslabels werden nicht in die Abrechnungsdaten einbezogen.

Erforderliche IAM-Rollen

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle BigQuery-Datenbearbeiter (roles/bigquery.dataEditor) zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Hinzufügen eines Labels zu einer vorhandenen Tabelle oder Ansicht benötigen. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Diese vordefinierte Rolle enthält die Berechtigungen, die zum Hinzufügen eines Labels zu einer vorhandenen Tabelle oder Ansicht erforderlich sind. Maximieren Sie den Abschnitt Erforderliche Berechtigungen, um die notwendigen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind erforderlich, um einer vorhandenen Tabelle oder Ansicht ein Label hinzuzufügen:

bigquery.tables.update
bigquery.tables.get

Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

Weitere Informationen zu IAM-Rollen und Berechtigungen in BigQuery finden Sie unter Vordefinierte Rollen und Berechtigungen.

Einer Tabelle oder Ansicht ein Label hinzufügen

So fügen Sie einer vorhandenen Tabelle oder Ansicht ein Label hinzu:

Console

Wählen Sie in der Google Cloud Console die Tabelle oder Ansicht aus.
Klicken Sie auf den Tab Details.
Klicken Sie im Bereich Labels auf Bearbeiten.
Im Dialogfeld Labels bearbeiten gehen Sie so vor:
- Klicken Sie auf Label hinzufügen.
- Geben Sie den Schlüssel und den Wert in die entsprechenden Felder ein. Klicken Sie auf Label hinzufügen, um weitere Labels anzuwenden. Jeder Schlüssel kann pro Dataset nur einmal verwendet werden, Sie können ihn aber in verschiedenen Datasets eines Projekts verwenden.
- Ändern Sie vorhandene Schlüssel oder Werte, um ein Label zu aktualisieren.
- Klicken Sie auf Update (Aktualisieren), um die Änderungen zu speichern.

SQL

Verwenden Sie die DDL-Anweisung ALTER TABLE SET OPTIONS, um die Labels für eine vorhandene Tabelle festzulegen, oder die DDL-Anweisung ALTER VIEW SET OPTIONS, um die Labels auf eine vorhandene Ansicht festzulegen. Mit dieser Aktion werden vorhandene Labels für die Tabelle oder Ansicht überschrieben. Im folgenden Beispiel werden zwei Labels für die Tabelle mytable festgelegt:

Rufen Sie in der Google Cloud Console die Seite BigQuery auf.

BigQuery aufrufen

Geben Sie im Abfrageeditor die folgende Anweisung ein:

ALTER TABLE mydataset.mytable
SET OPTIONS (
  labels = [('department', 'shipping'), ('cost_center', 'logistics')]);

Klicken Sie auf Ausführen.

Informationen zum Ausführen von Abfragen finden Sie unter Interaktive Abfrage ausführen.

bq

Sie verwenden den Befehl bq update mit dem Flag set_label, um einer vorhandenen Tabelle oder Ansicht ein Label hinzuzufügen. Wiederholen Sie das Flag, um mehrerer Labels hinzuzufügen.

Wenn sich die Tabelle oder Ansicht in einem anderen Projekt als Ihrem Standardprojekt befindet, geben Sie die Projekt-ID im folgenden Format an: PROJECT_ID:DATASET.

bq update \
--set_label KEY:VALUE \
PROJECT_ID:DATASET.TABLE_OR_VIEW

Ersetzen Sie Folgendes:

KEY:VALUE: Das Schlüssel/Wert-Paar für ein Label, das Sie hinzufügen möchten. Der Schlüssel muss eindeutig sein. Schlüssel und Werte dürfen nur Kleinbuchstaben, Ziffern, Unterstriche und Bindestriche enthalten. Alle Zeichen müssen UTF-8-codiert sein. Internationale Zeichen sind zulässig.
PROJECT_ID: Ihre Projekt-ID.
DATASET ist das Dataset, das die Tabelle oder Ansicht enthält, die Sie mit einem Label versehen möchten.
TABLE_OR_VIEW ist der Name der Tabelle oder Ansicht, die Sie mit einem Label versehen möchten.

Beispiele:

Zum Hinzufügen eines Tabellenlabels, das zur Nachverfolgung von Departments dient, verwenden Sie den Befehl bq update und geben department als Labelschlüssel an. Wenn Sie in Ihrem Standardprojekt beispielsweise ein Label department:shipping zu mytable hinzufügen möchten, verwenden Sie Folgendes:

    bq update --set_label department:shipping mydataset.mytable

Verwenden Sie den Befehl bq update und geben Sie department als Labelschlüssel an, um ein Ansichtslabel hinzuzufügen, das zur Nachverfolgung von Departments dient. Wenn Sie in Ihrem Standardprojekt beispielsweise ein Label department:shipping zu myview hinzufügen möchten, verwenden Sie Folgendes:

    bq update --set_label department:shipping mydataset.myview

Zum Hinzufügen mehrerer Labels zu einer Tabelle oder Ansicht wiederholen Sie das Flag set_label und legen für jedes Label einen eindeutigen Schlüssel fest. Wenn Sie in Ihrem Standardprojekt beispielsweise die Labels department:shipping und cost_center:logistics zu mytable hinzufügen möchten, verwenden Sie Folgendes:

    bq update \
    --set_label department:shipping \
    --set_label cost_center:logistics \
    mydataset.mytable

API

Rufen Sie die Methode tables.patch auf und füllen Sie das Attribut labels für die Tabellenressource aus, um ein Label zu einer vorhandenen Tabelle oder Ansicht hinzuzufügen.

Da Ansichten wie Tabellenressourcen behandelt werden, können Sie mit der Methode tables.patch sowohl Ansichten als auch Tabellen ändern.

Da die Methode tables.update die gesamte Dataset-Ressource ersetzt, sollten Sie stattdessen die Methode tables.patch verwenden.

Go

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

import (
	"context"
	"fmt"

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

// addTableLabel demonstrates adding Label metadata to a BigQuery table.
func addTableLabel(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	tbl := client.Dataset(datasetID).Table(tableID)
	meta, err := tbl.Metadata(ctx)
	if err != nil {
		return err
	}

	update := bigquery.TableMetadataToUpdate{}
	update.SetLabel("color", "green")
	if _, err := tbl.Update(ctx, update, meta.ETag); err != nil {
		return err
	}
	return nil
}

Java

In diesem Beispiel wird die Google-HTTP-Clientbibliothek für Java verwendet, um eine Anfrage an die BigQuery API zu senden.

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Table;
import com.google.cloud.bigquery.TableId;
import java.util.HashMap;
import java.util.Map;

// Sample to adds a label to an existing table
public class LabelTable {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    labelTable(datasetName, tableName);
  }

  public static void labelTable(String datasetName, String tableName) {
    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();

      // This example table starts with existing label { color: 'green' }
      Table table = bigquery.getTable(TableId.of(datasetName, tableName));
      // Add label to table
      Map<String, String> labels = new HashMap<>();
      labels.put("color", "green");

      table.toBuilder().setLabels(labels).build().update();
      System.out.println("Label added successfully");
    } catch (BigQueryException e) {
      System.out.println("Label was not added. \n" + e.toString());
    }
  }
}

Node.js

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

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

async function labelTable() {
  // Adds a label to an existing table.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'my_table';

  const dataset = bigquery.dataset(datasetId);
  const [table] = await dataset.table(tableId).get();

  // Retrieve current table metadata
  const [metadata] = await table.getMetadata();

  // Add label to table metadata
  metadata.labels = {color: 'green'};
  const [apiResponse] = await table.setMetadata(metadata);

  console.log(`${tableId} labels:`);
  console.log(apiResponse.labels);
}

Python

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

from google.cloud import bigquery

client = bigquery.Client()

# TODO(dev): Change table_id to the full name of the table you want to create.
table_id = "your-project.your_dataset.your_table_name"

table = client.get_table(table_id)  # API request

labels = {"color": "green"}
table.labels = labels

table = client.update_table(table, ["labels"])  # API request

print(f"Added {table.labels} to {table_id}.")

Jobs Labels hinzufügen

Mit dem --label-Flag des bq-Befehlszeilentools können Labels zu Abfragejobs über die Befehlszeile hinzugefügt werden. Mit dem bq-Tool können Labels nur Abfragejobs hinzugefügt werden.

Sie können einem Job auch ein Label hinzufügen, wenn er über die API übertragen wird. Geben Sie dazu in der Jobkonfiguration das Attribut labels an, wenn Sie die Methode jobs.insert aufrufen. Über die API können Labels beliebigen Jobtypen hinzugefügt werden.

Sie können keine Labels zu ausstehenden, laufenden oder abgeschlossenen Jobs hinzufügen oder für derartige Jobs aktualisieren.

Wenn Sie einem Job ein Label hinzufügen, wird das Label in Ihre Abrechnungsdaten einbezogen.

Erforderliche IAM-Rollen

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle BigQuery-Nutzer (roles/bigquery.user) zuzuweisen, um die Berechtigung zu erhalten, die Sie brauchen, um einem Job ein Label hinzuzufügen. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Diese vordefinierte Rolle enthält die Berechtigung bigquery.jobs.create, die zum Hinzufügen eines Labels zu einem Job erforderlich ist.

Sie können diese Berechtigung auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

Weitere Informationen zu IAM-Rollen und Berechtigungen in BigQuery finden Sie unter Vordefinierte Rollen und Berechtigungen.

Job ein Label hinzufügen

So fügen Sie einem Job ein Label hinzu:

bq

Mit dem Befehl bq query mit dem Flag --label fügen Sie einem Abfragejob ein Label hinzu. Wiederholen Sie das Flag, um mehrerer Labels hinzuzufügen. Das Flag zeigt an, dass Ihre Abfrage die GoogleSQL-Syntax verwendet.

bq query --label KEY:VALUE  'QUERY'

Ersetzen Sie Folgendes:

KEY:VALUE: Das Schlüssel/Wert-Paar für ein Label, das Sie dem Abfragejob hinzufügen möchten. Der Schlüssel muss eindeutig sein. Schlüssel und Werte dürfen nur Kleinbuchstaben, Ziffern, Unterstriche und Bindestriche enthalten. Alle Zeichen müssen UTF-8-codiert sein. Internationale Zeichen sind zulässig. Um einem Abfragejob mehrere Labels hinzuzufügen, wiederholen Sie das Flag --label und geben Sie für jedes Label einen eindeutigen Schlüssel an.
QUERY ist eine gültige GoogleSQL-Abfrage.

Beispiele:

So fügen Sie einem Abfragejob ein Label hinzu:

    bq query \
    --label department:shipping \
     \
    'SELECT
       column1, column2
     FROM
       `mydataset.mytable`'

Wiederholen Sie das Flag --label und geben Sie für jedes Label einen eindeutigen Schlüssel an, um einem Abfragejob mehrere Labels hinzuzufügen. So fügen Sie beispielsweise einem Abfragejob die Labels department:shipping und cost_center:logistics hinzu:

    bq query \
    --label department:shipping \
    --label cost_center:logistics \
     \
    'SELECT
       column1, column2
     FROM
       `mydataset.mytable`'

API

Rufen Sie die Methode jobs.insert auf und geben Sie das Attribut labels für die Jobkonfiguration ein, um einem Job ein Label hinzuzufügen. Über die API können Sie jedem Jobtyp Labels hinzufügen.

Python

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

from google.cloud import bigquery

client = bigquery.Client()

sql = """
    SELECT corpus
    FROM `bigquery-public-data.samples.shakespeare`
    GROUP BY corpus;
"""
labels = {"color": "green"}

config = bigquery.QueryJobConfig()
config.labels = labels
location = "us"
job = client.query(sql, location=location, job_config=config)
job_id = job.job_id

print(f"Added {job.labels} to {job_id}.")

Jobs in einer Sitzung mit einem Label verknüpfen

Wenn Sie Abfragen in einer Sitzung ausführen, können Sie allen zukünftigen Abfragejobs in der Sitzung ein Label mit BigQuery-Abfragen mit mehreren Anweisungen zuweisen.

SQL

Legen Sie in der Sitzung die Systemvariable @@query_label fest:

  SET @@query_label = "KEY:VALUE";

KEY:VALUE: Das Schlüssel/Wert-Paar für das Label, das allen zukünftigen Abfragen in der Sitzung zugewiesen werden soll. Sie können auch mehrere Schlüssel/Wert-Paare hinzufügen, die durch ein Komma getrennt sind, z. B. SET @@query_label = "key1:value1,key2:value2". Der Schlüssel muss eindeutig sein. Schlüssel und Werte dürfen nur Kleinbuchstaben, Ziffern, Unterstriche und Bindestriche enthalten. Alle Zeichen müssen UTF-8-codiert sein. Internationale Zeichen sind zulässig.

Beispiel:

  SET @@query_label = "cost_center:logistics";

API

Rufen Sie die Methode jobs.insert auf und füllen das Attribut query_label für die Auftragskonfiguration connectionProperties aus, um einem Abfragejob in einer Sitzung ein Label hinzuzufügen, wenn Sie eine Abfrage über einen API-Aufruf ausführen.

Nachdem Sie einer Sitzung ein Abfragelabel zugeordnet und Abfragen in dieser Sitzung ausgeführt haben, können Sie Audit-Logs für diese Abfragen erfassen. Weitere Informationen finden Sie in der Referenz zu Audit-Logs für BigQuery.

Reservierung ein Label hinzufügen

Wenn Sie einer Reservierung ein Label hinzufügen, wird es in Ihre Abrechnungsdaten einbezogen. Sie können Labels verwenden, um die Artikelnummer für die Attribution von Analyse-Slots in Ihren Cloud Billing-Daten zu filtern.

In der SKU für die Zuordnung von Analyse-Slots wird nur die Slot-Nutzung erfasst. Kosten für BigQuery Reservation API-SKUs werden nicht erfasst. Reservierungslabels werden nicht als Filter für BigQuery Reservation API-SKUs unterstützt.

Weitere Informationen zur Verwendung von Labels in Ihren Abrechnungsdaten finden Sie unter Daten mit Filtern optimieren.

Erforderliche IAM-Rollen

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle BigQuery-Ressourcenbearbeiter (roles/bigquery.resourceEditor) für das Administrationsprojekt zuzuweisen, um die Berechtigung zu erhalten, die Sie zum Hinzufügen eines Labels zu einer Reservierung benötigen. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Diese vordefinierte Rolle enthält die Berechtigung bigquery.reservations.update, die zum Hinzufügen eines Labels zu einer Reservierung erforderlich ist.

Sie können diese Berechtigung auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

Reservierung ein Label hinzufügen

So fügen Sie einer Reservierung ein Label hinzu:

Console

Rufen Sie in der Google Cloud Console die Seite "BigQuery" auf.

BigQuery aufrufen
Klicken Sie im Navigationsmenü auf Kapazitätsverwaltung.
Klicken Sie auf den Tab Slot-Reservierungen.
Suchen Sie die Reservierung, die Sie aktualisieren möchten.
Maximieren Sie die Option Aktionen.
Klicken Sie auf Bearbeiten.
Klicken Sie zum Erweitern des Abschnitts Erweiterte Einstellungen auf den Erweiterungspfeil.
Klicken Sie auf Label hinzufügen.
Geben Sie das Schlüssel/Wert-Paar in die entsprechenden Felder ein. Klicken Sie auf Label hinzufügen, um weitere Labels anzuwenden.
Klicken Sie auf Speichern.

SQL

Mit der DDL-Anweisung ALTER RESERVATION SET OPTIONS können Sie einer Reservierung ein Label hinzufügen. Durch diese Aktion werden alle vorhandenen Labels für die Reservierung überschrieben. Im folgenden Beispiel wird ein Label für die Reservierung myreservation festgelegt:

Rufen Sie in der Google Cloud Console die Seite BigQuery auf.

BigQuery aufrufen

Geben Sie im Abfrageeditor die folgende Anweisung ein:

ALTER RESERVATION myreservation
SET OPTIONS (
  labels = [('sensitivity', 'high')]);

Klicken Sie auf Ausführen.

Informationen zum Ausführen von Abfragen finden Sie unter Interaktive Abfrage ausführen.

bq

Verwenden Sie zum Hinzufügen eines Labels zu einer Reservierung den Befehl bq update mit den Flags set_label und --reservation. Wiederholen Sie das Flag set_label, um mehrere Labels hinzuzufügen.

bq update --set_label KEY:VALUE --location LOCATION --reservation RESERVATION_NAME

Ersetzen Sie Folgendes:

KEY:VALUE: Das Schlüssel/Wert-Paar für ein Label, das Sie der Reservierung hinzufügen möchten. Der Schlüssel muss eindeutig sein. Schlüssel und Werte dürfen nur Kleinbuchstaben, Ziffern, Unterstriche und Bindestriche enthalten. Alle Zeichen müssen UTF-8-codiert sein. Internationale Zeichen sind zulässig. Um einer Reservierung mehrere Labels hinzuzufügen, wiederholen Sie das Flag --set_label und geben Sie für jedes Label einen eindeutigen Schlüssel an.
LOCATION: Der Standort der Reservierung. Die Markierung location darf nicht am Ende des Befehls stehen, da sonst der Fehler FATAL Flags positioning zurückgegeben wird.
RESERVATION_NAME: der Name der Reservierung.

Label ohne Wert hinzufügen

Ein Label, das einen Schlüssel mit einem leeren Wert hat, wird manchmal als Tag bezeichnet. Dies sollte nicht mit einer Tag-Ressource verwechselt werden. Weitere Informationen finden Sie unter Labels und Tags. Sie können ein neues Label ohne Wert erstellen oder einen Wert aus einem vorhandenen Labelschlüssel entfernen.

Labels ohne Werte sind nützlich, wenn Sie einer Ressource ein Label hinzufügen, das Schlüssel/Wert-Format jedoch nicht benötigt wird. Wenn eine Tabelle beispielsweise Testdaten enthält, die von mehreren Gruppen verwendet werden, z. B. Support oder Entwicklung, können Sie der Tabelle zwecks Identifizierung ein test_data-Label hinzufügen.

So fügen Sie ein Label ohne Wert hinzu:

Console

Wählen Sie in der Google Cloud Console die entsprechende Ressource aus (Dataset, Tabelle oder Ansicht).
Bei Datasets wird automatisch die Seite „Dataset-Details“ geöffnet. Falls Sie eine Tabelle oder Ansicht ausgewählt haben, klicken Sie auf Details, um die Detailseite zu öffnen.
Klicken Sie auf der Detailseite im Abschnitt Labels auf Bearbeiten.
Im Dialogfeld Labels bearbeiten gehen Sie so vor:
- Klicken Sie auf Label hinzufügen.
- Geben Sie einen neuen Schlüssel in das entsprechende Feld ein und lassen Sie das Wertfeld leer. Klicken Sie auf Label hinzufügen, um weitere Labels anzuwenden, und wiederholen Sie den Schritt.
- Um die Änderungen zu speichern, klicken Sie auf Aktualisieren.

SQL

Mit der DDL-Anweisung ALTER TABLE SET OPTIONS können Sie ein Label ohne Wert hinzufügen:

Rufen Sie in der Google Cloud Console die Seite BigQuery auf.

BigQuery aufrufen

Geben Sie im Abfrageeditor die folgende Anweisung ein:

ALTER TABLE mydataset.mytable
SET OPTIONS (
  labels=[("key1", ""), ("key2", "")]);

Klicken Sie auf Ausführen.

Informationen zum Ausführen von Abfragen finden Sie unter Interaktive Abfrage ausführen.

bq

Verwenden Sie den bq update-Befehl mit dem set_label-Flag, um einer vorhandenen Ressource ein Label ohne Wert hinzuzufügen: Geben Sie den Schlüssel gefolgt von einem Doppelpunkt ein, aber keinen Wert.

bq update --set_label KEY: RESOURCE_ID

Dabei gilt:

KEY: ist der Labelschlüssel, den Sie verwenden möchten.
RESOURCE_ID ist ein gültiger Dataset-, Tabellen- oder Ansichtsname. Wenn sich die Ressource in einem anderen Projekt als Ihrem Standardprojekt befindet, geben Sie die Projekt-ID im folgenden Format an: PROJECT_ID:DATASET.

Beispiele:

Mit dem folgenden Befehl erstellen Sie ein test_data-Label für mydataset.mytable. mydataset befindet sich in Ihrem Standardprojekt.

bq update --set_label test_data: mydataset

API

Rufen Sie die Methode datasets.patch oder tables.patch auf und fügen Sie der Dataset-Ressource oder der Tabellenressource Labels mit einem leeren String ("") als Wert hinzu. Um Werte aus vorhandenen Labels zu entfernen, ersetzen Sie ihre Werte durch einen leeren String.

Da Ansichten wie Tabellenressourcen behandelt werden, können Sie mit der Methode tables.patch sowohl Ansichten als auch Tabellen ändern. Da außerdem die Methode tables.update die gesamte Dataset-Ressource ersetzt, sollten Sie stattdessen die Methode tables.patch verwenden.

Nächste Schritte

Labels für BigQuery-Ressourcen ansehen
Labels für BigQuery-Ressourcen aktualisieren
Ressourcen mithilfe von Labels filtern
Labels für BigQuery-Ressourcen löschen
Lesen Sie in der Dokumentation zu Resource Manager, wie Sie Labels verwenden.