Crear cuadernos

En este documento se describe cómo crear cuadernos de Colab Enterprise en BigQuery. Los cuadernos son recursos de código de BigQuery Studio basados en Dataform.

Antes de empezar

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 obligatorios

Define los permisos adecuados para crear, editar o ver cuadernos.

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

Para obtener más información sobre Gestión de Identidades y Accesos (IAM) de BigQuery, consulta el artículo Control de acceso con IAM.

Permisos para crear cuadernos

Para obtener los permisos que necesitas para crear y ejecutar cuadernos, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos:

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

• Usuario de BigQuery Studio (roles/bigquery.studioUser) El rol Usuario de BigQuery Studio combina los siguientes roles de gestión de identidades y accesos:

  • Usuario de trabajo de BigQuery (roles/bigquery.jobUser)
  • Usuario de tiempo de ejecución de cuaderno (roles/aiplatform.notebookRuntimeUser)

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

    Nota: Los usuarios a los que se les haya asignado el rol Creador de código en un proyecto pueden consultar los nombres de los recursos de código de ese proyecto mediante la API Dataform o la interfaz de línea de comandos (CLI) de Dataform. Los usuarios que no sean administradores y usen BigQuery Studio solo podrán ver los recursos de código que hayan creado o que se hayan compartido con ellos.

También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos. Para ver los permisos exactos que se necesitan para crear y ejecutar cuadernos, despliega la sección Permisos necesarios:

Permisos obligatorios

• 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 tengan el permiso dataform.repositories.create pueden ejecutar código con la cuenta de servicio predeterminada de Dataform y todos los permisos concedidos a esa cuenta de servicio. Para obtener más información, consulta Consideraciones de seguridad sobre 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 cuadernos

Para editar y ejecutar cuadernos, necesitas los siguientes roles de gestión de identidades y accesos:

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

Roles para ver cuadernos

Para ver y ejecutar cuadernos, necesitas los siguientes roles de gestión de identidades y accesos:

• Usuario de trabajo de BigQuery (roles/bigquery.jobUser)
• Usuario de sesión de lectura de BigQuery (roles/bigquery.readSessionUser)
• Usuario de tiempo de ejecución de cuaderno (roles/aiplatform.notebookRuntimeUser)
• Visor de código (roles/dataform.codeViewer)

Crear cuadernos

En las siguientes secciones se explica cómo crear un cuaderno.

Definir la región predeterminada de los recursos de código

Si es la primera vez que creas un recurso de código, debes definir 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 cuaderno y eliges una región predeterminada distinta de la que has estado usando para los recursos de código (por ejemplo, us-west1 en lugar de us-central1), ese cuaderno y todos los recursos de código que crees después usarán esa nueva región de forma predeterminada. Los recursos de código que ya tengas seguirán usando la región que se les asignó cuando se crearon.

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

1. Ve a la página BigQuery.

   Ir a BigQuery

2. En el panel Explorador, busca el proyecto en el que hayas habilitado los recursos de código.

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

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

5. Haz clic en Seleccionar.

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

Crear un cuaderno con la galería de cuadernos

Vista previa

Esta función está sujeta a los "Términos de las Ofertas de Acceso Previo a la Disponibilidad General" de la sección Términos Generales de los Servicios de los Términos Específicos de los Servicios. Las funciones previas a la disponibilidad general están disponibles tal cual y pueden tener una compatibilidad y asistencia limitadas. Para obtener más información, consulta las descripciones de las fases de lanzamiento.

Nota: Para enviar comentarios o solicitar mejoras del producto, ponte en contacto con [e-mail].

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

Para crear un cuaderno a partir de una plantilla de la galería de cuadernos, sigue estos pasos:

1. Ve a la página 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 situada junto a Consulta SQL y, a continuación, en Notebook > Todas las plantillas.

3. En la galería de cuadernos, selecciona una plantilla. Por ejemplo, puedes seleccionar Primeros pasos con los DataFrames de BigQuery.

   Se abrirá un nuevo cuaderno que contiene celdas con consultas de ejemplo en el conjunto de datos público bigquery-public-data.ml_datasets.penguins.

4. También puedes hacer clic en la flecha junto a Consulta SQL y, a continuación, en Cuaderno > Cuaderno vacío, Cuaderno > Plantilla de BigQuery o Cuaderno > Plantilla de Spark para abrir estas plantillas específicas.

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

6. Opcional: Para ver los detalles del cuaderno o el historial de versiones, añadir comentarios, responder a un comentario o conseguir un enlace a un comentario, 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 sobre estas funciones, envía un correo a [e-mail].

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

Crear un cuaderno a partir de una tabla

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

1. Ve a la página BigQuery.

   Ir a BigQuery

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

   

   Si no ves el panel de la izquierda, haz clic en Ampliar panel de la izquierda para abrirlo.

3. En el panel Explorador, despliega tu proyecto, haz clic en Conjuntos de datos y, a continuación, en el conjunto de datos.

4. Haga clic en Resumen > Tablas y busque la tabla que quiera consultar.

5. Junto a la tabla, haz clic en Acciones y, a continuación, en Abrir en > cuaderno de Python.

   Se abrirá un nuevo cuaderno con celdas que muestran consultas de ejemplo en la tabla seleccionada.

Crear un cuaderno para explorar el conjunto de resultados de una consulta

Para crear un cuaderno en el que explorar el conjunto de resultados de una consulta, sigue estos pasos:

1. Ve a la página 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 > cuaderno.

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

Crear un cuaderno a partir de otro

Para abrir cualquier versión de un cuaderno como un cuaderno 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 Explorador:

   

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

4. Selecciona un cuaderno.

5. Haz clic en Historial de versiones.

6. Haz clic en Ver acciones junto a una versión del cuaderno y, a continuación, en Abrir como cuaderno de Python nuevo.

   Se abre una copia del cuaderno como un cuaderno nuevo.

Subir cuadernos

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

Para subir un cuaderno, 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 Explorador:

   

3. En el panel Explorador, despliega tu proyecto y, a continuación, haz una de las siguientes acciones:

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

4. En el cuadro de diálogo Subir cuaderno, en el campo Cuaderno, haz clic en Examinar y, a continuación, selecciona el cuaderno que quieras subir.

5. Opcional: En el campo Nombre del cuaderno, edita el nombre del cuaderno.

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

7. Haz clic en Subir.

Puedes acceder a tu cuaderno a través del panel Explorador.

Conectarse a un entorno de ejecución

Consulta las siguientes secciones para saber cómo conectar un cuaderno a un runtime de Vertex AI. Un tiempo de ejecución es un recurso de computación que ejecuta el código de tu cuaderno. El tiempo de ejecución debe estar en la misma región que el cuaderno.

Para obtener más información sobre los tiempos de ejecución, consulta Tiempos de ejecución y plantillas de tiempo de ejecución.

Nota: Si usas Controles de Servicio de VPC, asegúrate de haber configurado el acceso privado de Google con Controles de Servicio de VPC antes de conectarte a un tiempo 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.

Conectarse al entorno de ejecución predeterminado

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

Para conectarte al tiempo 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 Explorador:

   

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

4. Haz clic en el nombre de una libreta para abrirla.

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

   Si aún no tienes un entorno de ejecución activo, puede que tardes varios minutos en conectarte al entorno de ejecución predeterminado.

Conectarse a un entorno de ejecución no predeterminado

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

Para conectarte a un tiempo 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 Explorador:

   

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

4. Haz clic en el nombre de una libreta para abrirla.

5. En el cuaderno, haz clic en el menú desplegable situado junto a Conectar y, a continuación, en Conectar con un entorno de ejecución.

6. Haz clic en Conectar a un tiempo de ejecución existente.

7. En Runtimes, selecciona el tiempo de ejecución que quieras usar. El tiempo de ejecución debe estar en la misma ubicación que el cuaderno.

8. Haz clic en Conectar.

Conectarse a un nuevo entorno de ejecución

Para conectarte a un nuevo entorno de ejecución, 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 Explorador:

   

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

4. Haz clic en el nombre de una libreta para abrirla.

5. En el cuaderno, haz clic en el menú desplegable situado junto a Conectar y, a continuación, en Conectar con un entorno de ejecución.

6. Haz clic en Crear nuevo tiempo de ejecución.

7. En Plantilla de entorno de ejecución, selecciona la plantilla de entorno de ejecución de Vertex AI que quieras usar.

8. En Nombre de tiempo de ejecución, escriba un nombre para el tiempo de ejecución.

9. Haz clic en Conectar.

Entender las celdas

Un cuaderno está formado por celdas que puedes editar. Se admiten los siguientes tipos de celdas:

• Celda de texto: usa una celda de texto para añadir explicaciones e imágenes a tu cuaderno en Markdown.
• Celda de código: usa una celda de código para añadir Python a tu cuaderno. 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 SQL (vista previa): usa una celda 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 SQL en una sola celda 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 BigQuery DataFrames como tablas en tu consulta incluyendo 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};
  

Conceder acceso a los cuadernos

Para dar acceso a otros usuarios a un cuaderno, añádelos al rol de gestión de identidades y accesos adecuado.

Importante: Los usuarios que tengan acceso al cuaderno podrán ver todos los resultados generados por el código del cuaderno, aunque estos resultados contengan datos de tablas a las que no tengan acceso. Para evitar que se comparta el resultado guardado, inhabilita el guardado del resultado del cuaderno.

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 Explorador:

   

   Si no ves el panel de la izquierda, haz clic en Ampliar panel de la izquierda para abrirlo.

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

4. Busca el cuaderno al que quieras dar acceso.

5. Haz clic en Abrir acciones junto al cuaderno y, a continuación, en Compartir.

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

7. En el campo New principals (Nuevos principales), introduce un principal.

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

   • Propietario del código: puede realizar cualquier acción en el cuaderno, como eliminarlo o compartirlo.
   • Editor de código: puede editar el cuaderno.
   • Visor de código: puede ver el cuaderno.
   Nota: La principal también debe tener los roles Usuario de tiempo de ejecución de cuaderno (roles/aiplatform.notebookRuntimeUser) y Usuario de BigQuery (roles/bigquery.user) para ejecutar el cuaderno.

9. Opcional: Para ver una lista completa de roles y ajustes avanzados para compartir, haz clic en Compartir de forma avanzada.

10. Haz clic en Guardar.

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

Compartir cuadernos

Para compartir un cuaderno con otros usuarios, puedes generar y compartir un enlace al cuaderno. Para que otros usuarios puedan ver el cuaderno que compartes, primero debes concederles acceso.

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

Importante: Los usuarios que tengan acceso al cuaderno podrán ver todos los resultados generados por el código del cuaderno, aunque estos resultados contengan datos de tablas a las que no tengan acceso. Para evitar que se comparta el resultado guardado, inhabilita el guardado del resultado del cuaderno.

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 Explorador:

   

   Si no ves el panel de la izquierda, haz clic en Ampliar panel de la izquierda para abrirlo.

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

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

5. Haz clic en Ver acciones junto al cuaderno y, a continuación, en Compartir > Copiar enlace.

6. Comparte el enlace con otros usuarios.

Inhabilitar el guardado de la salida de un cuaderno

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

Si inhabilitas el guardado de la salida de un cuaderno seleccionado, BigQuery eliminará toda la salida guardada en el archivo del cuaderno y no guardará la salida de las ejecuciones posteriores.

Sin embargo, los usuarios que tengan acceso al cuaderno podrán seguir viendo su salida de las siguientes formas:

• Ejecuta el cuaderno para ver su salida actual. Esta salida no se guarda.
• Ver una versión archivada del cuaderno y su salida en el historial de revisiones.

Para inhabilitar el guardado de la salida de un cuaderno 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 Explorador:

   

   Si no ves el panel de la izquierda, haz clic en Ampliar panel de la izquierda para abrirlo.

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

4. Haz clic en el cuaderno para el que quieras inhabilitar el guardado de resultados.

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

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

7. En la ventana Configuración del cuaderno, selecciona Omitir resultado de las celdas de código al guardar este cuaderno.

8. Haz clic en Guardar.

9. Haz clic en Volver a cargar.

Resolver conflictos

Si tú y otro usuario hacéis cambios contradictorios en un cuaderno, el servicio mostrará el error Automatic saving failed. This file was updated remotely or in another tab. y proporcionará un enlace Show diff. Para resolver el conflicto, sigue estos pasos:

1. Haz clic en el enlace Show diff. Se abrirá el cuadro de diálogo Revisar cambios remotos.
2. Opcional: Para comparar el código fuente del cuaderno, selecciona la casilla Fuente sin formato.
3. Opcional: Para comparar las versiones en línea en lugar de en paneles independientes, selecciona la casilla Diferencia en línea.
4. Revisa los cambios y decide cuáles quieres conservar. Si es necesario, revisa tu entrada.
5. Haz clic en Guardar cambios.

Cambiar el nombre de los cuadernos

Para cambiar el nombre de un cuaderno, 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 Explorador:

   

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

4. Haz clic en el cuaderno cuyo nombre quieras cambiar.

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

6. Haz clic en Archivo > Cambiar nombre.

7. En el cuadro de diálogo Cambiar nombre del cuaderno, escribe un nombre para el cuaderno y, a continuación, haz clic en Cambiar nombre.

Solución de problemas

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

Siguientes pasos

• Consulta cómo gestionar cuadernos.
• Consulta cómo programar cuadernos.