Administra la configuración

En este documento, se describe cómo especificar y recuperar la configuración de BigQuery a nivel de la organización o el proyecto.

Por ejemplo, para ayudar a administrar los trabajos, puedes usar este servicio para configurar la configuración predeterminada de los trabajos. Los parámetros de configuración predeterminados se establecen a nivel de organización o de proyecto, pero se pueden anular a nivel de sesión o de trabajo. Puedes definir la configuración predeterminada junto con las políticas de la organización relacionadas para aplicar el comportamiento predeterminado.

Parámetros de configuración

Puedes especificar los siguientes parámetros de configuración:

• default_batch_query_queue_timeout_ms: la cantidad de tiempo predeterminada, en milisegundos, que una consulta por lotes se pone en cola. Si no se configura, el valor predeterminado es 24 horas. El valor mínimo es 1 milisegundo. El valor máximo es de 48 horas. Para desactivar la cola de consultas por lotes, establece el valor en -1.
• default_column_name_character_map: el alcance y el manejo predeterminados de los caracteres en los nombres de las columnas. Si no se configuran, los trabajos de carga que usan caracteres no compatibles en los nombres de las columnas fallarán con un mensaje de error. Es posible que algunas tablas más antiguas se configuren para reemplazar los caracteres no compatibles en los nombres de las columnas. Para obtener más información, consulta load_option_list.
• default_interactive_query_queue_timeout_ms: la cantidad de tiempo predeterminada, en milisegundos, que una consulta interactiva se pone en cola. Si no se configura, el valor predeterminado es seis horas. El valor mínimo es 1 milisegundo. El valor máximo es 48 horas. Para desactivar la cola de consultas interactivas, establece el valor en -1.

• default_kms_key_name: la clave predeterminada de Cloud Key Management Service para encriptar los datos de tablas, incluidas las tablas temporales o anónimas. Para obtener más información, consulta Claves de Cloud KMS administradas por el cliente.

  Nota: Si deseas configurar una clave predeterminada de Cloud KMS, debes otorgar el rol de encriptador/desencriptador a todas las cuentas de servicio de BigQuery que se usan dentro del proyecto o la organización. Si una cuenta de servicio dentro del proyecto o la organización no tiene los permisos adecuados, fallarán todas las consultas que ejecute la cuenta de servicio. Para obtener información sobre cómo asignar el rol de encriptador/desencriptador, consulta Asigna el rol de encriptador/desencriptador. Si configuraste por error una clave predeterminada de Cloud KMS sin asignar primero los roles adecuados, puedes borrar la clave predeterminada si configuras el valor como NULL. Para ver ejemplos, consulta Establece la configuración de la organización y Establece la configuración del proyecto.

• default_query_job_timeout_ms: el tiempo predeterminado después del cual se agota el tiempo de espera de un trabajo de consulta, incluido el tiempo que se pone en cola y el tiempo que se ejecuta. El tiempo de espera debe ser de entre cinco minutos y seis horas. Este tiempo de espera solo se aplica a los trabajos de consulta individuales y a los trabajos secundarios de las secuencias de comandos. Para establecer un tiempo de espera para los trabajos de secuencia de comandos, debes usar el método de API jobs.insert y configurar el campo jobTimeoutMs.

• default_query_optimizer_options: Son las optimizaciones de consultas basadas en el historial. Esta opción puede ser una de las siguientes:

  • 'adaptive=on': Usa optimizaciones de consultas basadas en el historial.
  • 'adaptive=off': No uses optimizaciones de consultas basadas en el historial.
  • NULL (predeterminado): Usa la configuración predeterminada de optimizaciones de consultas basadas en el historial, que es equivalente a 'adaptive=off'.

• default_time_zone: la zona horaria predeterminada que se debe usar en funciones de SQL que dependen de la zona horaria cuando no se especifica una como argumento. Esta configuración no se aplica a las tablas particionadas de columnas de unidades de tiempo (que usan UTC como la zona horaria), las transferencias de programa del Servicio de transferencia de almacenamiento ni la carga de datos con la herramienta de línea de comandos de Para obtener más información, consulta Zonas horarias.

  Nota: Si deseas establecer una zona horaria predeterminada, asegúrate de que las consultas existentes que usan literales DATETIME no se vean afectadas. Esto incluye consultas con la palabra clave DATETIME explícita, literales de cadena convertidos de forma implícita pasados como un parámetro a las funciones de tiempo, como DATETIME_DIFF('2022-10-01', ...), la función PARSE_DATETIME(), etcétera. Por este motivo, es más seguro configurar solo el parámetro default_time_zone en proyectos nuevos.

• default_storage_billing_model: Es el modelo de facturación de almacenamiento predeterminado para conjuntos de datos nuevos. Establece el valor en PHYSICAL para usar bytes físicos cuando se calculan los cambios de almacenamiento, o en LOGICAL para usar bytes lógicos. Ten en cuenta que cambiar el modelo de facturación de almacenamiento predeterminado no afecta a los conjuntos de datos existentes. Para obtener más información, consulta Modelos de facturación de almacenamiento.

• default_max_time_travel_hours: Es el período de viaje en el tiempo predeterminado en horas para conjuntos de datos nuevos. Esta duración debe estar entre 48 y 168 horas inclusive, y debe ser divisible por 24. Cambiar las horas de viaje máximas predeterminadas no afecta a los conjuntos de datos existentes. Para obtener más información, consulta Viaje en el tiempo.

Especifica la configuración

En esta sección, se describe cómo especificar un parámetro de configuración.

Permisos necesarios

Para especificar un parámetro de configuración, necesitas el permiso bigquery.config.update de Identity and Access Management (IAM). El rol predefinido de IAM roles/bigquery.admin incluye los permisos que necesitas para especificar una configuración.

Para obtener más información sobre las funciones de IAM y los permisos en BigQuery, consulta Funciones y permisos predefinidos.

Configura ajustes

Puedes configurar los parámetros de configuración a nivel de organización o de proyecto con las siguientes instrucciones de SQL. Cuando especificas la configuración, debes especificar la región en la que se aplica. Solo puedes usar una región para cada instrucción.

Configura los ajustes de la organización

Para establecer la configuración de la organización, usa la declaración DDL ALTER ORGANIZATION SET OPTIONS. En el siguiente ejemplo, se establece la zona horaria predeterminada en America/Chicago, la clave predeterminada de Cloud KMS en una clave definida por el usuario, el tiempo de espera predeterminado de consulta en 30 minutos y el tiempo de espera predeterminado de la cola de consulta interactiva en 10 minutos, y el tiempo de espera predeterminado de la cola de consultas por lotes en 20 minutos:

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

Reemplaza lo siguiente:

• REGION: Es la región asociada con tu organización o proyecto. Por ejemplo, us o europe-west6.
• KMS_KEY es una clave de Cloud KMS definida por el usuario. Para obtener más información sobre las claves de Cloud KMS, consulta Claves de Cloud KMS administradas por el cliente.

En el siguiente ejemplo, se borra toda la configuración predeterminada a nivel de la organización:

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

Define la configuración del proyecto

Para establecer la configuración del proyecto, usa la declaración DDL ALTER PROJECT SET OPTIONS. La declaración DDL ALTER PROJECT SET OPTIONS acepta de forma opcional la variable project_id. Si no se especifica project_id, el valor predeterminado es el proyecto actual en el que se ejecuta la consulta. En el siguiente ejemplo, se establece la zona horaria predeterminada en America/Los_Angeles, la clave predeterminada de Cloud KMS en una clave de ejemplo, el tiempo de espera predeterminado de consulta en 1 hora y el tiempo de espera predeterminado de la cola de consultas interactiva en 10 minutos, y el tiempo de espera predeterminado de la cola de consultas por lotes en 20 minutos:

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

En el siguiente ejemplo, se borra toda la configuración predeterminada a nivel de proyecto. En estos casos, se usa cualquier configuración predeterminada a nivel de organización, si existe una. De lo contrario, toda la configuración predeterminada se establece en el valor predeterminado global.

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

Las configuraciones a nivel de proyecto anulan las configuraciones a nivel de organización. A su vez, las opciones de configuración a nivel de proyecto se pueden anular con las configuraciones a nivel de sesión, que se pueden anular con las configuraciones a nivel de trabajo

Cómo recuperar la configuración

Puedes ver los parámetros de configuración de una organización o un proyecto con las siguientes vistas del esquema de información:

• INFORMATION_SCHEMA.PROJECT_OPTIONS: las opciones de configuración aplicadas a un proyecto.
• INFORMATION_SCHEMA.EFFECTIVE_PROJECT_OPTIONS: las configuraciones efectivas aplicadas a un proyecto. Las configuraciones efectivas incluyen todas las configuraciones establecidas a nivel de proyecto, así como todas las configuraciones heredadas por el proyecto desde una organización.
• INFORMATION_SCHEMA.ORGANIZATION_OPTIONS: las opciones de configuración aplicadas a una organización.

Las nuevas configuraciones pueden tardar unos minutos en entrar en vigor y reflejarse en la vista INFORMATION_SCHEMA.

Permisos necesarios

Para recuperar la configuración, necesitas el permiso bigquery.config.get de IAM para el proyecto especificado.

Cada uno de los siguientes roles predefinidos de IAM incluye los permisos que necesitas para obtener la configuración de la vista INFORMATION_SCHEMA:

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

Para obtener más información sobre los roles de IAM y los permisos en BigQuery, consulta Roles y permisos predefinidos.

Ejemplos

Para ver las configuraciones en una organización en la región us, ejecuta la siguiente consulta:

SELECT * FROM region-us.INFORMATION_SCHEMA.ORGANIZATION_OPTIONS;

Para ver las configuraciones efectivas en tu proyecto predeterminado en la región us, ejecuta la siguiente consulta:

SELECT * FROM region-us.INFORMATION_SCHEMA.EFFECTIVE_PROJECT_OPTIONS;

Para ver las opciones de configuración en tu proyecto predeterminado en la región us, ejecuta la siguiente consulta:

SELECT * FROM region-us.INFORMATION_SCHEMA.PROJECT_OPTIONS;

Precios

No se aplican cargos adicionales por usar el servicio de configuración de BigQuery. Para obtener más información, consulta Precios.