Labels zu Ressourcen hinzufügen

Auf dieser Seite wird beschrieben, wie Sie Ihre BigQuery-Ressourcen mit Labels versehen.

Hinweis

Weisen Sie IAM-Rollen (Identity and Access Management) zu, die Nutzern die erforderlichen Berechtigungen zum Ausführen der einzelnen Aufgaben in diesem Dokument gewähren. Alle Berechtigungen, die zum Ausführen einer Aufgabe erforderlich sind, werden im Abschnitt „Erforderliche IAM-Rollen“ der Aufgabe aufgeführt.

Labels zu Datasets 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. Derzeit können Sie einem Dataset, wenn es mit der Google Cloud Console erstellt wird, kein Label hinzufügen.

Auf dieser Seite wird beschrieben, wie Sie einem Dataset nach seiner Erstellung ein Label hinzufügen. Weitere Informationen zum Hinzufügen eines Labels beim Erstellen eines Datasets finden Sie unter Dataset erstellen.

So kann nach dem Erstellen eines Datasets ein Label hinzugefügt werden:

Google Cloud Console verwenden
DDL-Anweisungen von SQL verwenden
Den Befehl bq update des bq-Befehlszeilentools verwenden
Durch Aufrufen der API-Methode datasets.patch
Mit den Clientbibliotheken

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

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

Erforderliche IAM-Rollen

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle BigQuery-Datenbearbeiter (roles/bigquery.dataEditor) zuzuweisen, um die Berechtigung zu erhalten, die Sie benötigen, um ein Label zu einem vorhandenen Dataset hinzuzufügen. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff 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.

Label zu einem Dataset hinzufügen

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

Console

Wählen Sie in der Google Cloud Console das Dataset aus.
Klicken Sie auf der Seite "Dataset-Details" auf das Stiftsymbol rechts neben Labels.
Gehen Sie im Dialogfeld Labels bearbeiten so vor:
- Klicken Sie auf Label hinzufügen.
- Geben Sie den Schlüssel und den Wert 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 das Festlegen von Labels werden alle vorhandenen Labels im Dataset überschrieben. Im folgenden Beispiel wird ein Label für das Dataset mydataset festgelegt:

Öffnen Sie in der Google Cloud Console die Seite BigQuery.

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 führen Sie den Befehl bq update mit dem Flag set_label aus. Wiederholen Sie das Flag, um mehrere Labels hinzuzufügen.

Wenn sich das Dataset in einem anderen Projekt als Ihrem Standardprojekt befindet, fügen Sie dem Dataset die Projekt-ID im Format PROJECT_ID:DATASET hinzu.

bq update --set_label KEY:VALUE PROJECT_ID:DATASET

Dabei gilt:

KEY:VALUE ist ein 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, geben Sie den Befehl bq update ein und legen Sie department als Labelschlüssel fest. Wenn Sie in Ihrem Standardprojekt beispielsweise ein Label department:shipping zu mydataset hinzufügen möchten, geben Sie Folgendes ein:

    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, geben Sie Folgendes ein:

    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, ist die Methode datasets.patch zu bevorzugen.

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

Labels zu Tabellen und Ansichten hinzufügen

So kann beim Erstellen einer Tabelle oder Ansicht ein Label hinzugefügt werden:

Mit dem Befehl bq mk des bq-Befehlszeilentools
Durch Aufrufen der API-Methode tables.insert

Auf dieser Seite 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.

So kann nach dem Erstellen einer Tabelle oder Ansicht ein Label hinzugefügt werden:

Google Cloud Console verwenden
Den Befehl bq update des bq-Befehlszeilentools verwenden
Durch Aufrufen der API-Methode tables.patch
Mit den Clientbibliotheken

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

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 verwalten.

Diese vordefinierte Rolle enthält die Berechtigungen, die zum Hinzufügen eines Labels zu einer vorhandenen Tabelle oder Ansicht erforderlich sind. Erweitern Sie den Abschnitt Erforderliche Berechtigungen, um die erforderlichen 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.

Label zu einer Tabelle oder Ansicht 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 auf das Stiftsymbol rechts neben Labels.
Gehen Sie im Dialogfeld Labels bearbeiten so vor:
- Klicken Sie auf Add Label (Label hinzufügen).
- Geben Sie den gewünschten Schlüssel und Wert ein, um ein Label hinzuzufügen. 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 Labels werden vorhandene Labels für die Tabelle oder Ansicht überschrieben. Im folgenden Beispiel werden zwei Labels für die Tabelle mytable festgelegt:

Öffnen Sie in der Google Cloud Console die Seite BigQuery.

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 ein Label zu einer vorhandenen Tabelle oder Ansicht 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, fügen Sie dem Dataset die Projekt-ID im Format project_id:dataset hinzu.

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

Dabei gilt:

KEY:VALUE ist ein 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, geben Sie den Befehl bq update ein und geben department als Labelschlüssel an. Wenn Sie in Ihrem Standardprojekt beispielsweise ein Label department:shipping zu mytable hinzufügen möchten, geben Sie Folgendes ein:

    bq update --set_label department:shipping mydataset.mytable

Geben Sie den Befehl bq update ein 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, geben Sie Folgendes ein:

    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, geben Sie Folgendes ein:

    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 sowohl Ansichten als auch Tabellen mit der Methode tables.patch ändern.

Da die Methode tables.update die gesamte Dataset-Ressource ersetzt, ist die Methode tables.patch zu bevorzugen.

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}.")

Labels zu Jobs 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 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.

Label einem Job 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 --nouse_legacy_sql zeigt an, dass Ihre Abfrage die GoogleSQL-Syntax aufweist.

bq query --label KEY:VALUE --nouse_legacy_sql 'QUERY'

Dabei gilt:

KEY:VALUE ist ein 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 \
    --nouse_legacy_sql \
    '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 \
    --nouse_legacy_sql \
    '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.

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 ist ein Schlüssel/Wert-Paar für das Label, das allen zukünftigen Abfragen in der Sitzung zugewiesen werden soll. 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 innerhalb der Sitzung ausgeführt haben, können Sie Audit-Logs für Abfragen mit diesem Abfragelabel erfassen. Weitere Informationen finden Sie in der Referenz zu Audit-Logs für BigQuery.

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 können in Situationen nützlich sein, in denen Sie einer Ressource ein Label hinzufügen, das Schlüssel/Wert-Format jedoch nicht benötigt wird. Beispiel: Wenn eine Tabelle 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" angezeigt. Wenn Sie eine Tabelle oder Ansicht ausgewählt haben, klicken Sie auf Details, um die Detailseite zu öffnen.
Klicken Sie auf der Detailseite auf das Stiftsymbol rechts neben Labels.
Gehen Sie im Dialogfeld Labels bearbeiten so vor:
- Klicken Sie auf Add Label (Label hinzufügen).
- Geben Sie einen neuen Schlüssel ein und lassen Sie den Wert 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:

Öffnen Sie in der Google Cloud Console die Seite BigQuery.

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, fügen Sie die Projekt-ID im Format PROJECT_ID:DATASET hinzu.

Beispiele:

Mit folgendem 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 sowohl Ansichten als auch Tabellen mit der Methode tables.patch ändern. Da außerdem die Methode tables.update die gesamte Dataset-Ressource ersetzt, wird die Methode tables.patch bevorzugt.

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.