Standardkonfigurationen verwalten

In diesem Dokument wird beschrieben, wie Sie Standardkonfigurationseinstellungen auf Organisations- oder Projektebene erstellen und abrufen.

Zur Verwaltung von Jobs können Sie in BigQuery Standardeinstellungen konfigurieren. Einstellungen, die diesen Dienst verwenden, werden auf Organisations- oder Projektebene konfiguriert, können jedoch auf Sitzungs- oder Jobebene überschrieben werden. Standardeinstellungen können Sie in Kombination mit zugehörigen Organisationsrichtlinien konfigurieren, um ein Standardverhalten zu erzwingen.

Preise

Für die Nutzung des BigQuery-Konfigurationsdienstes fallen keine zusätzlichen Gebühren an. Weitere Informationen finden Sie unter Preise.

Standardkonfigurationen

Sie können Standardkonfigurationen für die folgenden Einstellungen angeben:

default_time_zone: Standardzeitzone, die in zeitzonenabhängigen SQL-Funktionen verwendet wird, wenn keine Zeitzone als Argument angegeben ist. Diese Konfiguration gilt nicht für nach Zeiteinheit partitionierte Spalten (die die Zeitzone UTC verwenden), für Übertragungen des Storage Transfer Service oder das Laden von Daten mit dem bq-Befehlszeilentool. Weitere Informationen finden Sie unter Zeitzonen.
default_kms_key_name: Der standardmäßige Cloud Key Management Service-Schlüssel zum Verschlüsseln von Tabellendaten, einschließlich temporärer oder anonymer Tabellen. Weitere Informationen finden Sie unter Vom Kunden verwaltete Cloud KMS-Schlüssel.
default_query_job_timeout_ms: Die Standardzeit, nach der ein Abfragejob das Zeitlimit überschreitet, einschließlich der Zeit, in der der Job in der Warteschlange steht, und der Zeit, in der er ausgeführt wird. Das Zeitlimit muss zwischen fünf Minuten und sechs Stunden liegen.
default_interactive_query_queue_timeout_ms: Die Standardzeit in Millisekunden, in der eine interaktive Abfrage in die Warteschlange gestellt wird. Wenn nicht festgelegt, beträgt der Standardwert sechs Stunden. Der Mindestwert beträgt 1 Millisekunde. Der Höchstwert beträgt 48 Stunden. Wenn Sie die Warteschlange für interaktive Abfragen deaktivieren möchten, setzen Sie den Wert auf -1.
default_batch_query_queue_timeout_ms: Der Standardzeitraum in Millisekunden, in der eine Batchabfrage in die Warteschlange gestellt wird. Wenn nicht festgelegt, beträgt der Standardwert 24 Stunden. Der Mindestwert beträgt 1 Millisekunde. Der Höchstwert beträgt 48 Stunden. Wenn Sie die Warteschlange für Batchabfragen deaktivieren möchten, setzen Sie den Wert auf -1.

Standardkonfigurationen erstellen

In diesem Abschnitt wird beschrieben, wie Sie eine Konfiguration erstellen.

Erforderliche Berechtigungen

Zum Erstellen einer Konfiguration benötigen Sie die IAM-Berechtigung (Identity and Access Management) bigquery.config.update. Die vordefinierte IAM-Rolle roles/bigquery.admin enthält die Berechtigungen, die Sie zum Erstellen einer Konfiguration benötigen.

Warnung: Wenn Sie einen standardmäßigen Cloud Key Management Service-Schlüssel festlegen möchten, müssen Sie allen BigQuery-Dienstkonten im Projekt oder der Organisation die Rolle „Verschlüsseler/Entschlüsseler“ zuweisen. Wenn ein Dienstkonto innerhalb des Projekts oder der Organisation keine entsprechenden Berechtigungen hat, schlagen alle Abfragen innerhalb des Dienstkontos fehl. Informationen zum Zuweisen der Rolle "Verschlüsseler/Entschlüsseler" finden Sie unter Rolle "Verschlüsseler/Entschlüsseler" zuweisen. Wenn Sie einen standardmäßigen Cloud Key Management Service-Schlüssel festlegen, ohne zuvor die entsprechenden Rollen zuzuweisen, können Sie den Standardschlüssel löschen. Setzen Sie dazu den Wert auf NULL. Beispiele finden Sie in diesem Dokument unter Organisationseinstellungen konfigurieren und Projekteinstellungen konfigurieren. Wenn Sie eine Standardzeitzone festlegen möchten, müssen Sie sicherstellen, dass vorhandenen Abfragen, die DATETIME-Literale verwenden, nicht betroffen sind. Dazu gehören Abfragen mit dem expliziten Schlüsselwort DATETIME, implizit konvertierte Stringliterale, die als Parameter an Zeitfunktionen wie DATETIME_DIFF('2022-10-01', ...) übergeben werden, die Funktion PARSE_DATETIME() und mehr. Aus diesem Grund ist es sicherer, den Parameter default_time_zone nur bei neuen Projekten festzulegen.

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

Standardeinstellungen konfigurieren

Sie können die Standardeinstellungen auf Organisations- oder Projektebene mit den folgenden SQL-Anweisungen konfigurieren. Wenn Sie die Konfiguration erstellen, müssen Sie die Region angeben, in der sie gilt. Sie können nur eine Region für jede Anweisung verwenden.

Organisationseinstellungen konfigurieren

Mit der DDL-Anweisung ALTER ORGANIZATION SET OPTIONS können Sie die Organisationseinstellungen konfigurieren. Im folgenden Beispiel wird die Standardzeitzone auf America/Chicago, der Cloud KMS-Standardschlüssel auf einen benutzerdefinierten Schlüssel, das Standardzeitlimit für Abfragen auf 30 Minuten, das standardmäßige Zeitlimit für interaktive Abfragen auf 10 Minuten und das Standard-Zeitlimit für die Batch-Abfragewarteschlange auf 20 Minuten festgelegt:

ALTER ORGANIZATION
SET OPTIONS (
  `REGION.default_time_zone `= 'America/Chicago',
  -- Ensure all service accounts under the organization have permission to KMS_KEY
  `REGION.default_kms_key_name` = KMS_KEY,
  `REGION.default_query_job_timeout_ms` = 1800000,
  `REGION.default_interactive_query_queue_timeout_ms` = 600000,
  `REGION.default_batch_query_queue_timeout_ms` = 1200000);

Ersetzen Sie Folgendes:

REGION: Die Region, die Ihrem Projekt oder Ihrer Organisation zugeordnet ist. Beispiel: region-us oder region-europe-west6.
KMS_KEY: ein benutzerdefinierter Cloud KMS-Schlüssel. Weitere Informationen zu Cloud KMS-Schlüsseln finden Sie unter Vom Kunden verwaltete Cloud KMS-Schlüssel.

Im folgenden Beispiel werden alle Standardeinstellungen auf Organisationsebene gelöscht.

ALTER ORGANIZATION
SET OPTIONS (
  `REGION.default_time_zone` = NULL,
  `REGION.default_kms_key_name` = NULL,
  `REGION.default_query_job_timeout_ms` = NULL,
  `REGION.default_interactive_query_queue_timeout_ms` = NULL,
  `REGION.default_batch_query_queue_timeout_ms` = NULL);

Projekteinstellungen konfigurieren

Mit der DDL-Anweisung ALTER PROJECT SET OPTIONS können Sie Projekteinstellungen konfigurieren. Die DDL-Anweisung ALTER PROJECT SET OPTIONS akzeptiert optional die Variable project_id. Wenn project_id nicht angegeben ist, wird standardmäßig das aktuelle Projekt verwendet, in dem die Abfrage ausgeführt wird. Im folgenden Beispiel wird die Standardzeitzone auf America/Los_Angeles, der Cloud KMS-Standardschlüssel auf einen Beispielschlüssel, das Standardzeitlimit für Abfragen auf 1 Stunde, das Standard-Zeitlimit für interaktive Abfragen auf 10 Minuten und das Standard-Zeitlimit für die Batch-Abfragewarteschlange auf 20 Minuten festgelegt:

ALTER PROJECT project_id
SET OPTIONS (
  `REGION.default_time_zone` = 'America/Los_Angeles',
  -- Ensure all service accounts under the project have permission to KMS_KEY
  `REGION.default_kms_key_name` = KMS_KEY,
  `REGION.default_query_job_timeout_ms` = 3600000,
  `REGION.default_interactive_query_queue_timeout_ms` = 600000,
  `REGION.default_batch_query_queue_timeout_ms` = 1200000);

Im folgenden Beispiel werden alle Standardeinstellungen auf Projektebene gelöscht. Die Standardeinstellungen verwenden alle Standardeinstellungen auf Organisationsebene, sofern vorhanden. Andernfalls werden alle Standardeinstellungen auf die globale Standardeinstellung festgelegt.

ALTER PROJECT project_id
SET OPTIONS (
  `REGION.default_time_zone` = NULL,
  `REGION.default_kms_key_name` = NULL,
  `REGION.default_query_job_timeout_ms` = NULL,
  `REGION.default_interactive_query_queue_timeout_ms` = NULL,
  `REGION.default_batch_query_queue_timeout_ms` = NULL);

Konfigurationen auf Projektebene überschreiben Konfigurationen auf Organisationsebene. Konfigurationen auf Projektebene können wiederum durch Konfigurationen auf Sitzungsebene überschrieben werden, die wiederum durch Konfigurationen auf Jobebene überschrieben werden können.

Konfigurationswerte abrufen

Sie können die Standardkonfigurationseinstellungen für eine Organisation oder ein Projekt über das Informationsschema aufrufen. Es gibt drei verschiedene Ansichten zum Abfragen:

INFORMATION_SCHEMA.PROJECT_OPTIONS: Die Konfigurationen, die auf ein Projekt angewendet werden
INFORMATION_SCHEMA.EFFECTIVE_PROJECT_OPTIONS: Die effektiven Konfigurationen, die auf ein Projekt angewendet werden. Effektive Konfigurationen umfassen alle Konfigurationen, die auf Projektebene festgelegt wurden, sowie alle Einstellungen, die das Projekt von einer Organisation übernommen hat
INFORMATION_SCHEMA.ORGANIZATION_OPTIONS: Die auf eine Organisation angewendeten Konfigurationen

Es kann einige Minuten dauern, bis neue Konfigurationen wirksam werden und in der INFORMATION_SCHEMA-Ansicht widergespiegelt werden.

Erforderliche Berechtigungen

Zum Abrufen von Konfigurationswerten benötigen Sie die IAM-Berechtigung bigquery.config.get.

Jede der folgenden vordefinierten IAM-Rollen enthält die Berechtigungen, die Sie zum Abrufen der Konfiguration aus der INFORMATION_SCHEMA-Ansicht benötigen:

roles/bigquery.jobUser
roles/bigquery.dataEditor
roles/bigquery.dataUser

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

Beispiele

Führen Sie folgende Abfrage aus, um die Konfigurationen unter einer Organisation in der us-Region anzuzeigen:

SELECT * FROM region-us.INFORMATION_SCHEMA.ORGANIZATION_OPTIONS;

Führen Sie folgende Abfrage aus, um die effektiven Konfigurationen unter Ihrem Standardprojekt in der us-Region aufzurufen:

SELECT * FROM region-us.INFORMATION_SCHEMA.EFFECTIVE_PROJECT_OPTIONS;

Wenn Sie die Konfigurationen unter Ihrem Standardprojekt in der us-Region aufrufen möchten, führen Sie folgende Abfrage aus:

SELECT * FROM region-us.INFORMATION_SCHEMA.PROJECT_OPTIONS;