Crear notebooks

En este documento se describe cómo administrar notebooks de Colab Enterprise en BigQuery. Los notebooks son recursos de código de BigQuery Studio con tecnología de Dataform.

Antes de comenzar

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

Permisos necesarios

Configura los permisos adecuados para crear, editar o ver notebooks.

Todos los usuarios con el rol Administrador de Dataform (roles/dataform.admin) tienen acceso de propietario a todos los notebooks creados en el proyecto.

Para obtener más información sobre Identity and Access Management (IAM) de BigQuery, consulta Control de acceso con IAM.

Permisos para crear notebooks

Para obtener los permisos que necesitas para crear y ejecutar notebooks, pídele a tu administrador que te otorgue los siguientes roles de IAM:

• Usuario de sesión de lectura de BigQuery (roles/bigquery.readSessionUser)

• Usuario de BigQuery Studio (roles/bigquery.studioUser) El rol de usuario de BigQuery Studio combina los siguientes roles de IAM:

  • Usuario de trabajo de BigQuery (roles/bigquery.jobUser)
  • Usuario del entorno de ejecución del notebook (roles/aiplatform.notebookRuntimeUser)

  • Creador de código (roles/dataform.codeCreator)

    Nota: Los usuarios con el rol Creador de código en un proyecto pueden enumerar los nombres de los elementos de código de ese proyecto mediante la API de Dataform o la interfaz de línea de comandos (CLI) de Dataform. Los usuarios que no son administradores que usan BigQuery Studio solo pueden ver los elementos de código que crearon o que se compartieron con ellos.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido. Para ver los permisos exactos que se requieren para crear y ejecutar notebooks, expande la sección Permisos requeridos:

Permisos necesarios

• bigquery.config.get
• bigquery.jobs.create
• bigquery.readsessions.create
• bigquery.readsessions.getData
• bigquery.readsessions.update
• resourcemanager.projects.get
• resourcemanager.projects.list
• dataform.locations.get
• dataform.locations.list
• dataform.repositories.create
Nota: Los usuarios que tienen el permiso dataform.repositories.create pueden ejecutar el código con la cuenta de servicio predeterminada de Dataform y todos los permisos otorgados a esa cuenta de servicio. Para obtener más información, consulta Consideraciones de seguridad para los permisos de Dataform.
• dataform.repositories.list
• dataform.collections.create
• dataform.collections.list
• aiplatform.notebookRuntimeTemplates.apply
• aiplatform.notebookRuntimeTemplates.get
• aiplatform.notebookRuntimeTemplates.list
• aiplatform.notebookRuntimeTemplates.getIamPolicy
• aiplatform.notebookRuntimes.assign
• aiplatform.notebookRuntimes.get
• aiplatform.notebookRuntimes.list
• aiplatform.operations.list

Roles para editar notebooks

Para editar y ejecutar notebooks, necesitas los siguientes roles de IAM:

• Usuario de trabajo de BigQuery (roles/bigquery.jobUser)
• Usuario de sesión de lectura de BigQuery (roles/bigquery.readSessionUser)
• Usuario del entorno de ejecución del notebook (roles/aiplatform.notebookRuntimeUser)
• Editor de código (roles/dataform.codeEditor)

Roles para ver notebooks

Para ver y ejecutar notebooks, necesitas los siguientes roles de IAM:

• Usuario de trabajo de BigQuery (roles/bigquery.jobUser)
• Usuario de sesión de lectura de BigQuery (roles/bigquery.readSessionUser)
• Usuario del entorno de ejecución del notebook (roles/aiplatform.notebookRuntimeUser)
• Visualizador de código (roles/dataform.codeViewer)

Crear notebooks

Usa las siguientes secciones para aprender a crear un notebook.

Configura la región predeterminada para los elementos de código

Si es la primera vez que creas un recurso de código, debes configurar la región predeterminada para los recursos de código. No puedes cambiar la región de un recurso de código después de crearlo.

Nota: Si creas un notebook y eliges una región predeterminada diferente de la que usaste para los recursos de código (por ejemplo, si eliges us-west1, pero antes estuviste usando us-central1), el notebook y todos los recursos de código que crees posteriormente usarán esa nueva región de forma predeterminada. Los recursos de código existentes siguen usando la región que se les asignó cuando se crearon.

Todos los recursos de código en BigQuery Studio usan la misma región predeterminada. Para configurar la región predeterminada de los recursos de código, sigue estos pasos:

1. Ve a la página de BigQuery.

   Ir a BigQuery

2. En el panel Explorador, busca el proyecto en el que habilitaste los elementos de código.

3. Haz clic en Ver acciones junto al proyecto y, luego, en Cambiar mi región de código predeterminada.

4. En Región, selecciona la región que deseas usar para los recursos de código.

5. Haz clic en Seleccionar.

Para obtener una lista de las regiones admitidas, consulta Ubicaciones de BigQuery Studio.

Crea un notebook con la galería de notebooks

Vista previa

Esta función está sujeta a las “Condiciones de la Oferta de la Fase Previa a la DG” en la sección Condiciones del Servicio Generales de las Condiciones Específicas del Servicio. Las funciones de la fase previa a la DG están disponibles "sin modificaciones" y pueden tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Nota: Para enviar comentarios o solicitar mejoras del producto, comunícate con [e-mail].

La galería de notebooks en la consola de Google Cloud BigQuery es tu centro central para descubrir y usar plantillas de notebooks prediseñadas.

Para crear un notebook a partir de una plantilla en la galería de notebooks, sigue estos pasos:

1. Ve a la página de BigQuery.

   Ir a BigQuery

2. Para abrir la galería, en la barra de pestañas del panel del editor, haz clic en la flecha junto a Consulta en SQL y, luego, en Notebook > Todas las plantillas.

3. En la galería de notebooks, selecciona una plantilla. Por ejemplo, puedes seleccionar Introducción a BigQuery DataFrames.

   Se abrirá el notebook nuevo, el cual contiene celdas que muestran consultas de ejemplo en el conjunto de datos públicos bigquery-public-data.ml_datasets.penguins.

4. Como alternativa, puedes hacer clic en la flecha junto a Consulta SQL y, luego, en Notebook > Notebook vacío, Notebook > Plantilla de BigQuery o Notebook > Plantilla de Spark para abrir estas plantillas específicas.

5. Para crear un notebook ejecutable a partir de la plantilla, haz clic en Usar esta plantilla.

6. Opcional: Para ver los detalles del notebook o el historial de versiones, agregar comentarios nuevos, responder a un comentario existente o obtener un vínculo a él, usa la siguiente barra de herramientas:

   

   Las funciones de la barra de herramientas Detalles, Historial de versiones y Comentarios están en versión preliminar. Para enviar comentarios o solicitar asistencia para estas funciones, envía un correo electrónico a [e-mail].

7. Opcional: En la barra de herramientas, puedes usar el panel Referencia para obtener una vista previa de los detalles del esquema de tablas, instantáneas, vistas o vistas materializadas, o bien abrirlos en una pestaña nueva. El panel también tiene una lista de recursos recientes y destacados.

Crea un notebook a partir de una tabla

Para crear un notebook que contenga una consulta predeterminada para una tabla específica, sigue estos pasos:

1. Ve a la página de BigQuery.

   Ir a BigQuery

2. En el panel de la izquierda, haz clic en Explorar:

   

   Si no ves el panel izquierdo, haz clic en Expandir panel izquierdo para abrirlo.

3. En el panel Explorador, expande tu proyecto, haz clic en Conjuntos de datos y, luego, en tu conjunto de datos.

4. Haz clic en Descripción general > Tablas y busca la tabla que deseas consultar.

5. Junto a la tabla, haz clic en Acciones y, luego, en Abrir en > notebook de Python.

   Se abrirá el notebook nuevo que contiene celdas que muestran consultas de ejemplo en la tabla seleccionada.

Crea un notebook para explorar el conjunto de resultados de una consulta

Para crear un notebook que explore el conjunto de resultados de una consulta, sigue estos pasos:

1. Ve a la página de BigQuery.

   Ir a BigQuery

2. En el panel del editor, ejecuta una consulta que genere un resultado.

3. En el panel Resultados de la consulta, haz clic en Abrir en > Notebook.

   Se abrirá el notebook nuevo, que contiene celdas con código para devolver el SQL de la consulta y los resultados de la consulta.

Crea un notebook a partir de uno ya existente

Para abrir cualquier versión de un notebook existente como nuevo, sigue estos pasos:

1. En la consola de Google Cloud , ve a la página BigQuery.

   Ir a BigQuery

2. En el panel de la izquierda, haz clic en Explorar:

   

3. En el panel Explorador, expande tu proyecto y haz clic en Notebooks.

4. Selecciona un notebook

5. Haz clic en Historial de versiones.

6. Haz clic en Ver acciones junto a la versión de un notebook y, luego, en Abrir como notebook nuevo de Python.

   Se abrirá una copia del notebook como un notebook nuevo.

Subir notebooks

Puedes subir un notebook local para usarlo en BigQuery Studio. El notebook subido se puede ver en la página de BigQuery de la Google Cloud consola.

Para borrar un notebook, sigue estos pasos:

1. En la consola de Google Cloud , ve a la página BigQuery.

   Ir a BigQuery

2. En el panel de la izquierda, haz clic en Explorar:

   

3. En el panel Explorador, expande tu proyecto y, luego, realiza una de las siguientes acciones:

   • Junto a Notebooks, haz clic en Ver acciones > Subir a Notebooks.
   • Junto al nombre del proyecto Google Cloud , haz clic en Ver acciones > Subir al proyecto > Notebook.

4. En el cuadro de diálogo Subir notebook, en el campo Seleccionar notebook, haz clic en Explorar y selecciona el notebook que deseas subir.

5. En el campo Nombre del notebook, edita el nombre del archivo de notebook (opcional).

6. En el campo Región, selecciona la región en la que deseas subir tu notebook.

7. Haz clic en Subir.

Se puede acceder a tu notebook a través del panel Explorador.

Conéctate a un entorno de ejecución

Usa las siguientes secciones para aprender a conectar un notebook a un entorno de ejecución de Vertex AI. Un entorno de ejecución es un recurso de procesamiento que ejecuta el código en tu notebook. El entorno de ejecución debe estar en la misma región que tu notebook.

Para obtener más información sobre los entornos de ejecución, consulta Entornos de ejecución y plantillas de entorno de ejecución.

Nota: Si usas los Controles del servicio de VPC, asegúrate de haber configurado el Acceso privado a Google con los Controles del servicio de VPC antes de conectarte a un entorno de ejecución. De lo contrario, el servicio devuelve el error Failed to connect to Runtime Network projects/projectid/global/networks/default' was not found.
.

Conéctate al entorno de ejecución predeterminado

El entorno de ejecución predeterminado es un entorno de ejecución preestablecido que requiere una configuración mínima.

Para conectarte al entorno de ejecución predeterminado, sigue estos pasos:

1. En la consola de Google Cloud , ve a la página BigQuery.

   Ir a BigQuery

2. En el panel de la izquierda, haz clic en Explorar:

   

3. En el panel Explorador, expande tu proyecto y haz clic en Notebooks.

4. Haz clic en el nombre de un notebook para abrirlo.

5. En el notebook, haz clic en Conectar o ejecuta cualquier celda.

   Es posible que la conexión al entorno de ejecución predeterminado tarde varios minutos si aún no tienes un entorno de ejecución activo.

Conéctate a un entorno de ejecución no predeterminado

Si deseas usar un entorno de ejecución que no sea el predeterminado, primero debes crear ese entorno de ejecución adicional en Vertex AI.

Para conectarte al entorno de ejecución no predeterminado, sigue estos pasos:

1. En la consola de Google Cloud , ve a la página BigQuery.

   Ir a BigQuery

2. En el panel de la izquierda, haz clic en Explorar:

   

3. En el panel Explorador, expande tu proyecto y haz clic en Notebooks.

4. Haz clic en el nombre de un notebook para abrirlo.

5. En el notebook, haz clic en el menú desplegable junto a Conectar y, luego, en Conectar a un entorno de ejecución.

6. Haz clic en Conéctate a un entorno de ejecución existente.

7. En Entornos de ejecución, selecciona el entorno de ejecución que deseas usar. El entorno de ejecución debe estar en la misma ubicación que el notebook.

8. Haz clic en Conectar.

Conectar a un nuevo entorno de ejecución

Para conectarte a un entorno de ejecución nuevo, sigue estos pasos:

1. En la consola de Google Cloud , ve a la página BigQuery.

   Ir a BigQuery

2. En el panel de la izquierda, haz clic en Explorar:

   

3. En el panel Explorador, expande tu proyecto y haz clic en Notebooks.

4. Haz clic en el nombre de un notebook para abrirlo.

5. En el notebook, haz clic en el menú desplegable junto a Conectar y, luego, en Conectar a un entorno de ejecución.

6. Haz clic en Crear un nuevo entorno de ejecución.

7. En Plantilla del entorno de ejecución, selecciona la plantilla de entorno de ejecución de Vertex AI para usarla.

8. En Nombre del entorno de ejecución, escribe un nombre para el entorno de ejecución.

9. Haz clic en Conectar.

Información sobre las celdas

Un notebook se compone de celdas que puedes editar. Se admiten los siguientes tipos de celdas:

• Celda de texto: Usa una celda de texto para agregar explicaciones e imágenes a tu notebook en Markdown.
• Celda de código: Usa una celda de código para agregar Python a tu notebook. Puedes ejecutar cada celda de código de forma individual. Una celda de código puede hacer referencia a cualquier variable creada en otra celda que ya hayas ejecutado.

• Celda de SQL (versión preliminar): Usa una celda de SQL para ejecutar consultas de GoogleSQL. El resultado de la consulta se guarda automáticamente como un DataFrame con el mismo nombre que el título de la celda. Puedes ejecutar varias instrucciones de SQL en una sola celda de SQL, pero solo los resultados de la última instrucción se guardan en un DataFrame.

  Puedes hacer referencia a variables de Python en expresiones o usar DataFrames de BigQuery como tablas en tu consulta. Para ello, debes incluir el nombre de la variable entre llaves ({ }):

  # Refer to the Python variable my_threshold in a SQL expression.
  SELECT * FROM my_dataset.my_table WHERE x > {my_threshold};
  
  # Reference previous query results to iterate on your queries.
  SELECT * FROM {df};
  

Otorga acceso a los notebooks

Para otorgar acceso a un notebook a otros usuarios, agrégalos a un rol de IAM adecuada.

Importante: Los usuarios que tienen acceso al notebook pueden ver todos los resultados que generó el código en el notebook, incluso si este resultado contiene datos de tablas que no admiten T debe tener acceso. Para evitar que se comparta el resultado guardado, inhabilita el guardado de resultados del notebook.

1. En la consola de Google Cloud , ve a la página BigQuery.

   Ir a BigQuery

2. En el panel de la izquierda, haz clic en Explorar:

   

   Si no ves el panel izquierdo, haz clic en Expandir panel izquierdo para abrirlo.

3. En el panel Explorador, expande tu proyecto y haz clic en Notebooks.

4. Busca el notebook al que quieres otorgar acceso.

5. Haz clic en Abrir acciones junto al notebook y, luego, en Compartir.

6. En el panel Permisos de uso compartido, haz clic en Agregar usuario o grupo.

7. En el campo Principales nuevas, ingresa una principal.

8. En la lista Rol, selecciona uno de los siguientes roles:

   • Propietario del código: Puede realizar cualquier acción en el notebook, incluida la eliminación o el uso compartido.
   • Editor de código: Puede editar el notebook.
   • Visualizador de código: Puede ver el notebook.
   Nota: La principal también debe tener el Usuario del entorno de ejecución del notebook (roles/aiplatform.notebookRuntimeUser) y Roles de usuario de BigQuery (roles/bigquery.user) para ejecutar el notebook.

9. Opcional: Para ver una lista completa de las funciones y la configuración de uso compartido avanzada, haz clic en Uso compartido avanzado.

10. Haz clic en Guardar.

11. Para volver a la página de información del notebook, haz clic en Cerrar.

Comparte notebooks

Para compartir un notebook con otros usuarios, puedes generar y compartir un vínculo al notebook. Para que otros usuarios vean el notebook que compartes, primero debes otorgar acceso al notebook.

Para ejecutar un notebook, los usuarios deben tener acceso a los datos a los que accede el notebook. Para obtener más información, consulta Otorga acceso a un conjunto de datos.

Importante: Los usuarios que tienen acceso al notebook pueden ver todos los resultados que generó el código en el notebook, incluso si este resultado contiene datos de tablas que no admiten T debe tener acceso. Para evitar que se comparta el resultado guardado, inhabilita el guardado de resultados del notebook.

1. En la consola de Google Cloud , ve a la página BigQuery.

   Ir a BigQuery

2. En el panel de la izquierda, haz clic en Explorar:

   

   Si no ves el panel izquierdo, haz clic en Expandir panel izquierdo para abrirlo.

3. En el panel Explorador, expande tu proyecto y haz clic en Notebooks.

4. Busca la carpeta que quieras compartir. Puedes usar la función de búsqueda o los filtros para encontrar tu notebook.

5. Haz clic en Ver acciones junto al notebook y, luego, en Compartir > Copiar vínculo.

6. Comparte el vínculo con otros usuarios.

Inhabilita el guardado de resultados de notebook

Puedes evitar que se comparta el resultado del notebook guardado con otros usuarios que tengan acceso al archivo del notebook si inhabilitas el guardado de resultados del notebook.

Cuando inhabilitas el guardado de resultados para un notebook seleccionado, BigQuery borra todos los resultados guardados en el archivo del notebook y no guarda el resultado de las ejecuciones posteriores.

Sin embargo, los usuarios que tienen acceso al notebook aún pueden ver el resultado de las siguientes maneras:

• Ejecuta el notebook para ver su resultado actual. No se guardó este resultado.
• Visualiza una versión de archivo del notebook y su resultado en el historial de revisión.

Para inhabilitar el guardado de resultados en un notebook seleccionado, sigue estos pasos:

1. En la consola de Google Cloud , ve a la página BigQuery.

   Ir a BigQuery

2. En el panel de la izquierda, haz clic en Explorar:

   

   Si no ves el panel izquierdo, haz clic en Expandir panel izquierdo para abrirlo.

3. En el panel Explorador, expande tu proyecto y haz clic en Notebooks.

4. Haz clic en el notebook en el que deseas inhabilitar el guardado de resultados.

5. Para expandir la barra de menú, haz clic en keyboard_arrow_down Alternar visibilidad del encabezado.

6. Haz clic en Editar > Configuración del notebook.

7. En la ventana Configuración del notebook, selecciona Omitir el resultado de la celda de código cuando guardas este notebook.

8. Haz clic en Guardar.

9. Haz clic en Volver a cargar.

Resolver conflictos

Si tú y otro usuario realizan cambios conflictivos en un notebook, el servicio genera el error Automatic saving failed. This file was updated remotely or in another tab. y proporciona un vínculo Show diff. Para resolver el conflicto, sigue estos pasos:

1. Haz clic en el vínculo Show diff. Se abrirá el cuadro de diálogo Revisa los cambios remotos.
2. Opcional: Para comparar el código fuente del notebook, selecciona la casilla de verificación Fuente sin procesar.
3. Opcional: Para comparar las versiones intercaladas en lugar de en paneles separados, selecciona la casilla de verificación Diferencia intercalada.
4. Revisa los cambios y decide cuáles conservar. Si es necesario, revisa tu entrada.
5. Haz clic en Guardar los cambios.

Cambia el nombre de los notebooks

Para borrar un notebook, sigue estos pasos:

1. En la consola de Google Cloud , ve a la página BigQuery.

   Ir a BigQuery

2. En el panel de la izquierda, haz clic en Explorar:

   

3. En el panel Explorador, expande tu proyecto y haz clic en Notebooks.

4. Haz clic en el notebook al que quieres cambiarle el nombre.

5. Haz clic en keyboard_arrow_down Alternar visibilidad del encabezado para expandir la barra de menú.

6. Haz clic en Archivo > Cambiar nombre.

7. En el cuadro de diálogo Cambiar nombre de notebook, escribe un nombre para el notebook y, luego, haz clic en Cambiar nombre.

Soluciona problemas

Para obtener más información, consulta Soluciona problemas de Colab Enterprise.

¿Qué sigue?

• Obtén más información sobre cómo administrar notebooks.
• Obtén más información para programar notebooks.