Configurar tuberías

Configurar la configuración básica de una canalización, incluido el código fuente, el catálogo y el esquema de destino, los recursos de cómputo y el modo de canalización, en la interfaz de usuario del espacio de trabajo.

Databricks recomienda desarrollar nuevas canalizaciones sin servidor. Para obtener instrucciones de configuración para canalizaciones sin servidor, consulte Configuración de una canalización sin servidor.

Las instrucciones de configuración de esta página usan el catálogo de Unity. Para obtener instrucciones sobre cómo configurar canalizaciones con metastore heredado de Hive, consulte Usar canalizaciones de Lakeflow con metastore heredado de Hive.

En esta página se describe la funcionalidad del modo de publicación predeterminado actual para las canalizaciones. Las canalizaciones creadas antes del 5 de febrero de 2025 podrían usar el modo de publicación heredado y el esquema virtual LIVE. Consulte el esquema LIVE (heredado).

Nota:

La interfaz de usuario tiene una opción para mostrar y editar los ajustes en JSON. Puede configurar la mayoría de las opciones de configuración con la interfaz de usuario o una especificación JSON. Algunas opciones avanzadas solo están disponibles mediante la configuración JSON.

Los archivos de configuración JSON también son útiles al implementar canalizaciones en nuevos entornos o al usar la CLI o la API de REST.

Para obtener una referencia completa a las opciones de configuración json de canalización, consulte Configuraciones de canalización.

Configuración de la canalización

La configuración de canalización se divide en dos categorías:

• Código fuente: colección de archivos que declaran conjuntos de datos mediante la sintaxis de canalización. Consulte Configuración del código fuente.
• Infraestructura: configuración que controla el proceso, cómo se procesan las actualizaciones y dónde se almacenan las tablas.

La mayoría de las opciones de configuración tienen valores predeterminados razonables, pero dos requieren atención antes de ejecutarse en producción:

• Catálogo y esquema de destino: para que los datos estén disponibles fuera de la canalización, declare un catálogo y un esquema de destino. Los datos se publican en el Catálogo de Unity de forma predeterminada. Consulte Definir el catálogo y el esquema de destino.
• Acceso a datos: el proceso usado para la ejecución debe tener permisos configurados para los orígenes de datos y, si se especifica, una ubicación de almacenamiento.

Configuración de una nueva canalización

Para configurar una nueva canalización, haga lo siguiente:

1. En la parte superior de la barra lateral, haga clic en Nuevo y seleccione Canalización de ETL.

2. En la parte superior, asigne un nombre único a la canalización.

3. Debajo del nombre, puede ver el catálogo y el esquema predeterminados que se han elegido para usted. Cambie estos valores para proporcionar a la canalización valores predeterminados diferentes.

   El catálogo predeterminado y el esquema predeterminado son donde se leen o escriben conjuntos de datos cuando no se califican los conjuntos de datos con un catálogo o esquema en el código. Consulte Objetos de base de datos en Azure Databricks para más información.

4. Seleccione la opción preferida para crear una canalización:

   • Comience con el código de ejemplo en SQL para crear una nueva estructura de canalización y carpeta, incluido el código de ejemplo en SQL.
   • Comience con código de ejemplo en Python para crear una nueva estructura de canalización y carpeta, incluido el código de ejemplo en Python.
   • Comience con una sola transformación para crear una nueva estructura de canalización y carpeta, con un nuevo archivo de código en blanco.
   • Agregue recursos existentes para crear una canalización que pueda asociar a los archivos de código existentes en el área de trabajo.
   • Cree un proyecto controlado por código fuente para crear una canalización con un nuevo proyecto de agrupaciones de Automatización declarativa o para agregar la canalización a un lote existente.

   Puede tener archivos de código fuente de SQL y Python en la canalización de ETL. Al crear una nueva canalización y elegir un idioma para el código de ejemplo, el lenguaje solo es para el código de ejemplo incluido en la canalización de forma predeterminada.

5. Al realizar la selección, se le redirigirá a la canalización recién creada.

   La canalización de ETL se crea con la siguiente configuración predeterminada:

   • Catálogo de Unity
   • Canal actual
   • Computación sin servidor

   Esta configuración se recomienda para muchos casos de uso, incluido el desarrollo y las pruebas, y es adecuado para cargas de trabajo de producción que se deben ejecutar según una programación. Para obtener más información sobre la programación de canalizaciones, consulte Tarea de canalización para trabajos.

   Puede ajustar esta configuración desde la barra de herramientas de canalización.

Como alternativa, puede crear una canalización de ETL desde el explorador del área de trabajo:

1. Haga clic en Área de trabajo en el panel izquierdo.
2. Seleccione cualquier carpeta, incluidas las carpetas de Git.
3. Haga clic en Crear en la esquina superior derecha y haga clic en Canalización ETL.

También puede crear una canalización de ETL desde la página trabajos y canalizaciones:

1. En el área de trabajo, haga clic en Trabajos y canalizaciones en la barra lateral.
2. En Nuevo, haga clic en Canalización ETL.

Opciones de configuración del proceso

Databricks recomienda usar siempre el Escalado automático mejorado. Los valores predeterminados para otras configuraciones de proceso funcionan bien para muchas canalizaciones.

Las canalizaciones sin servidor eliminan las opciones de configuración de proceso. Para obtener instrucciones de configuración para canalizaciones sin servidor, consulte Configuración de una canalización sin servidor.

Use la siguiente configuración para personalizar las configuraciones de proceso:

• Los administradores del espacio de trabajo pueden configurar una política de clúster. Las políticas de proceso permiten a los administradores controlar las opciones de proceso disponibles para los usuarios. Consulte Selección de una directiva de proceso.
• Opcionalmente, puede configurar el Modo de clúster para que se ejecute con el Tamaño fijo o el Escalado automático heredado. Consulte Optimizar la utilización del clúster de canalización de Lakeflow mediante escalado automático.
• Para cargas de trabajo con escalado automático activado, defina los Trabajadores mínimos y los Trabajadores máximos para fijar los límites de los comportamientos de escalado. Consulte Configurar el cálculo clásico para canalizaciones.
• Opcionalmente, puede desactivar la aceleración Photon. Consulte ¿Qué es Photon?

• Use etiquetas de clúster para ayudar a supervisar los costos asociados a las canalizaciones. Consulte Configuración de etiquetas de proceso.
• Configure Tipos de instancia para especificar el tipo de máquinas virtuales que se usan para ejecutar la canalización. Consulte Selección de tipos de instancia para ejecutar una canalización.
  • Seleccione un Tipo de trabajo optimizado para las cargas de trabajo configuradas en la canalización.
  • Opcionalmente, puede seleccionar un Tipo de controlador que difiere del tipo de trabajo. Esto puede ser útil para reducir los costes en canalizaciones con tipos de trabajadores grandes y una baja utilización del controlador, o para elegir un tipo de controlador más grande con el fin de evitar problemas de memoria insuficiente en cargas de trabajo con muchos trabajadores pequeños.

Establecer el usuario de ejecución

El usuario de ejecución le permite cambiar la identidad que usa una canalización para ejecutarse y la propiedad de las tablas que crea o actualiza. Esto es útil en situaciones en las que el usuario original que creó la canalización se ha desactivado, por ejemplo, si dejó la empresa. En esos casos, la canalización puede dejar de funcionar y las tablas publicadas pueden dejar de estar accesibles para otros usuarios. Al actualizar la canalización para que se ejecute con una identidad diferente, como una entidad de servicio, y reasignar la propiedad de las tablas publicadas, puede recuperar el acceso y garantizar que la canalización siga funcionando. La ejecución de canalizaciones como entidades de servicio se considera un procedimiento recomendado porque no están vinculados a usuarios individuales, por lo que son más seguros, estables y confiables para cargas de trabajo automatizadas.

Permisos necesarios

Para el usuario que realiza el cambio:

• Permisos CAN_MANAGE en la canalización
• Rol CAN_USE en la entidad de servicio (si establece la ejecución como una entidad de servicio)
• Pertenencia al grupo o permiso Asumir sobre el grupo (si se configura ejecutar como para un grupo). Consulta Configurar la identidad de ejecutar como para un grupo.

Para el usuario, la entidad de servicio o el grupo de ejecutar como:

• Acceso al área de trabajo:

  • Permiso de acceso al espacio de trabajo para operar dentro del mismo
  • Permiso Puede usar en las directivas de clúster usadas por la canalización
  • Permiso de creación de proceso en el área de trabajo

• Acceso al código fuente:

  • Permiso Puede leer en todos los cuadernos incluidos en el código fuente de la canalización
  • Permiso Puede leer en los archivos del área de trabajo si la canalización los usa

• Permisos de Unity Catalog (para canalizaciones con Unity Catalog):

  • USE CATALOG en el catálogo de destino
  • USE SCHEMA y CREATE TABLE en el esquema de destino
  • Permiso MODIFY en las tablas existentes que actualiza la canalización
  • CREATE SCHEMA permiso si la canalización crea nuevos esquemas

• Permisos del metastore de Hive heredado (para canalizaciones que usan el metastore de Hive):

  • Permisos SELECT y MODIFY en bases de datos y tablas de destino

• Acceso adicional al almacenamiento en la nube (si procede):

  • Permisos para leer desde ubicaciones de almacenamiento de origen
  • Permisos para escribir en ubicaciones de almacenamiento de destino

Cómo establecer el usuario de ejecución

Puede establecer el usuario run-as mediante la configuración de la canalización desde la página de supervisión de la canalización o el editor de canalizaciones. Para cambiar el usuario desde la página de supervisión de la tubería:

1. Haga clic en Trabajos y canalizaciones para abrir la lista de canalizaciones y seleccione el nombre de la canalización que desea editar.
2. En la página de supervisión del pipeline, haz clic en Configuración.
3. En la barra lateral Configuración de canalización, haga clic en Editar junto a Ejecutar como.
4. En el widget de edición, seleccione una de las siguientes opciones:
   • Su propia cuenta de usuario
   • Una entidad de servicio para la que tiene el permiso CAN_USE
   • Un grupo de cuentas del que seas miembro o sobre el que tengas el permiso Asumir. Consulta Configurar la identidad de ejecutar como para un grupo.
5. Haga clic en Guardar para aplicar los cambios.

Cuando actualiza correctamente el usuario de ejecución:

• La identidad del pipeline cambia para utilizar el nuevo usuario, entidad de servicio o grupo en todas las ejecuciones futuras
• En las canalizaciones de Unity Catalog, el propietario de las tablas publicadas por la canalización se actualiza para coincidir con la nueva identidad de ejecución
• Las futuras actualizaciones de la canalización usan los permisos y las credenciales de la nueva identidad de ejecución
• Al igual que cualquier cambio de configuración, la nueva identidad se aplica a la siguiente actualización de canalización: las canalizaciones continuas se reinician automáticamente con la nueva identidad, mientras que las canalizaciones desencadenadas la aplican en su siguiente ejecución. El cambio de ejecución puede interrumpir una actualización activa. Consulte Cómo surten efecto los cambios de configuración.

Nota:

Si se produce un error en la actualización de run-as, recibirá un mensaje de error que explica el motivo del error. Entre los problemas comunes se incluyen permisos insuficientes en la entidad de servicio.

Establecer la identidad de ejecución como un grupo

Establecer la identidad de Ejecutar como de un pipeline en un grupo de cuentas funciona de la misma manera que establecerla en un usuario o una entidad de servicio. Las actualizaciones de la canalización se ejecutan con los permisos del grupo y, en las canalizaciones de Unity Catalog, las tablas que publica la canalización son propiedad del grupo. Utilice un grupo cuando desee que un equipo sea el propietario de una canalización automatizada, en lugar de vincularla a la cuenta de una sola persona, de modo que la canalización siga funcionando aunque cambien los miembros del equipo.

En Azure Databricks, un rol se implementa como un grupo, por lo que un pipeline cuyo Ejecutar como esté configurado en un grupo se ejecuta con ese rol. Consulte Control de acceso basado en rol (RBAC).

Establecer Ejecutar como en un grupo no cambia quién es el propietario del pipeline. La propiedad y la identidad de ejecución son configuraciones independientes. Para cambiar el propietario, consulte Cambiar el propietario del pipeline.

Para configurar Ejecutar como en un grupo, debe:

• Ser miembro del grupo o
• Disponga del permiso Asumir sobre el grupo, si este se utiliza para acceso exclusivo.

El grupo debe ser un grupo de cuentas asignado al espacio de trabajo. Los grupos locales del espacio de trabajo no se pueden utilizar como identidad de ejecución, al igual que los grupos integrados generales admins, users y account users.

Conceda al grupo todos los permisos que necesite el pipeline, tal y como se indican en Permisos necesarios. Dado que las actualizaciones se ejecutan como grupo, no basta con concederte acceso al código fuente y a los datos del pipeline.

Para configurar Ejecutar como en un grupo en la interfaz de usuario del espacio de trabajo, sigue los pasos descritos en Cómo configurar el usuario de ejecución y busca el grupo en el widget de edición. Los grupos aparecen junto a los usuarios y las entidades de servicio. Para confirmar el cambio, vuelve a abrir la barra lateral Configuración de la canalización y comprueba que Ejecutar como muestre el grupo.

Para establecer un grupo como identidad de ejecución mediante la API REST, establece run_as.group_name en el nombre del grupo. Para crear un pipeline que se ejecute como grupo, ejecuta lo siguiente:

{
  "name": "sales-etl",
  "run_as": {
    "group_name": "Test Group"
  }
}

Para ver la solicitud completa, consulta Crear un pipeline. Cuando actualices una definición de pipeline existente, establece updated_run_as.group_name en su lugar.

Para establecer un grupo como identidad de ejecución en un paquete de Paquetes de automatización declarativa, establezca group_name en la run_as asignación del recurso de canalización:

resources:
  pipelines:
    sales_etl:
      name: sales-etl
      run_as:
        group_name: Test Group

Una SET OWNER TO instrucción SQL no puede establecer a un grupo como propietario de una vista materializada o tabla de streaming. Utilice la interfaz de usuario del área de trabajo para ello. Consulte Uso ALTER de instrucciones con conjuntos de datos de canalización.

Los trabajos admiten la misma configuración de grupo de ejecución. Consulta Configurar Ejecutar como con un grupo.

Otras consideraciones de configuración

Las siguientes opciones de configuración también están disponibles para las canalizaciones:

• La edición de productos avanzados proporciona acceso a todas las características de canalización. Opcionalmente, puede ejecutar canalizaciones usando las ediciones de producto Pro o Core. Consulte Seleccionar una edición de producto.
• Configura el modo Pipeline para controlar cómo procesa los datos. Consulta Configurar el modo de canalización.
• Para ejecutar una canalización de forma continua en producción, Databricks recomienda incluirla en un trabajo continuo en lugar de usar el modo integrado Continuous de la canalización. Consulte Ejecute una canalización continua con un trabajo continuo.
• Si su área de trabajo no está configurada para Unity Catalog o su carga de trabajo necesita usar el metastore heredado de Hive, consulte Uso de canalizaciones de Lakeflow con el metastore heredado de Hive.
• Agregue Notificaciones para las actualizaciones de correo electrónico en función de las condiciones de éxito o error. Consulte Agregar notificaciones por correo electrónico para eventos de canalización.
• Use el campo Parámetros para declarar pares clave-valor a los que su código fuente SQL puede hacer referencia con la sintaxis de parámetro con nombre, y que pueden invalidarse al iniciar una actualización o desde un trabajo. Consulte Uso de parámetros con canalizaciones.
• Use el campo Configuración para establecer valores de configuración de Spark que controlan el comportamiento de la canalización, como pipelines.enzyme.enabled. Consulte Referencia de propiedades de canalización. Para las canalizaciones de Python que requieren parametrización, el campo Configuración también pone valores a disposición de spark.conf.get(). Consulte Parámetros de referencia mediante el campo de configuración.
• Configure Etiquetas. Las etiquetas son pares clave-valor de la canalización visibles en la lista Trabajos & Canalizaciones. Las etiquetas de tubería no están asociadas a la facturación.
• Usa el canal Vista previa para probar tu canalización con los cambios pendientes en el entorno de ejecución de la canalización y para probar nuevas funciones.

Configura el modo de canalización

La configuración del modo Canalización controla cómo una canalización procesa los datos:

• Desencadenado es la opción predeterminada. La tubería actualiza todas las tablas con los datos disponibles cuando comienza la actualización y luego se detiene, por lo que el cómputo solo se ejecuta durante la duración de la actualización. Ejecute canalizaciones activadas bajo demanda o de forma programada. Consulte Tarea de canalización para trabajos.
• Continuo mantiene las tablas frescas procesando los nuevos datos a medida que llegan a las fuentes. Esto reduce el retraso entre los nuevos datos y los resultados actualizados, a costa de un clúster siempre en funcionamiento. Elige el modo continuo solo cuando tengas un requisito probado de baja latencia.

Para configurar el modo, utiliza la opción de modo Pipeline en la configuración de pipeline cuando crees o edites un pipeline. Para consultar una comparación completa de los dos modos y obtener indicaciones sobre cómo elegir entre ellos, consulte Modo de canalización activado frente a modo de canalización continua.

Cómo surten efecto los cambios de configuración

Cuando editas y guardas la configuración de una canalización, el cambio se aplica a la siguiente actualización de la canalización. Cuando un trabajo continuo orquesta la canalización, no necesitas reiniciar el trabajo para que la configuración actualizada surta efecto; el trabajo la aplica en la siguiente actualización. El calendario del trabajo determina el modo de ejecución, no la configuración del modo de canalización del pipeline. Consulte Ejecute una canalización continua con un trabajo continuo.

Si usas la configuración integrada de la canalización Pipeline mode en lugar de un trabajo continuo:

• Las canalizaciones continuas se reinician automáticamente con la configuración actualizada. Esto puede interrumpir una actualización activa.
• Al cambiar el tipo de desencadenado a continuo, se inicia automáticamente una nueva actualización con la configuración actualizada. Por el contrario, cambiar el tipo de continuo a activado cancela una actualización activa.

Elija una edición del producto

Seleccione la edición del producto con las mejores características para sus requisitos de canalización. Están disponibles las siguientes ediciones del producto:

• Core para ejecutar cargas de trabajo de ingesta de streaming. Seleccione la edición Core si la canalización no requiere características avanzadas, como la captura de datos modificados (CDC) o las expectativas.
• Pro para ejecutar cargas de trabajo de ingesta de streaming y CDC. La edición Pro del producto admite todas las características de la edición Core, además de la compatibilidad con cargas de trabajo que requieren la actualización de tablas en función de los cambios en los datos de origen.
• Advanced para ejecutar cargas de trabajo de ingesta de streaming, cargas de trabajo de CDC y cargas de trabajo que requieren expectativas. La edición del producto Advanced admite las características de las ediciones Core y Pro e incluye restricciones de calidad de datos con las expectativas.

Puede seleccionar la edición del producto al crear o editar una canalización. Puede elegir una edición diferente para cada canalización. Para más información, incluido un desglose de características más completo por edición, consulte la página del producto Canalizaciones declarativas de Apache Spark™ en Databricks.

Las canalizaciones conservan durante 60 días las actualizaciones anteriores en la interfaz de usuario de canalizaciones y en la Pipelines API.

Las actualizaciones activas (no terminales) siempre aparecen. Si una actualización es anterior a la ventana de retención, Azure Databricks la excluye de las respuestas de lista, pero la mantiene en el registro de eventos subyacente.

Nota: Si la canalización incluye características no admitidas por la edición de producto seleccionada, como las expectativas, recibirá un mensaje de error que explica el motivo del error. Después, puede editar la canalización para seleccionar la edición adecuada.

Configurar el código fuente

Puede usar el explorador de recursos en el Editor de canalizaciones de Lakeflow para configurar el código fuente que define la canalización. El código fuente de la canalización se define en scripts SQL o Python almacenados en archivos del área de trabajo. Al crear o editar la canalización, puede agregar uno o varios archivos. De forma predeterminada, el código fuente de la canalización se encuentra en la carpeta transformations en la carpeta raíz de su canalización.

Dado que las canalizaciones analizan automáticamente las dependencias del conjunto de datos para construir el gráfico de procesamiento, puede agregar recursos de código fuente en cualquier orden.

Para obtener más información sobre el uso del Editor de canalizaciones de Lakeflow, consulte Desarrollo y depuración de canalizaciones de ETL con el Editor de canalizaciones de Lakeflow.

Administración de dependencias externas para canalizaciones que usan Python

Las canalizaciones admiten el uso de dependencias externas, como paquetes y bibliotecas de Python. Para obtener información sobre las opciones y recomendaciones para el uso de dependencias, consulte Administración de dependencias de Python para canalizaciones.

Uso de módulos de Python almacenados en el área de trabajo de Azure Databricks

Además de implementar el código de Python en los archivos de código fuente de canalización, puede usar carpetas de Git de Databricks o archivos de área de trabajo para almacenar el código como módulos de Python. Almacenar el código como módulos de Python es especialmente útil cuando tiene funcionalidad común que desea usar en varias canalizaciones o cuadernos de la misma canalización. Para obtener información sobre cómo usar módulos de Python con las canalizaciones, consulte Importación de módulos de Python desde carpetas de Git o archivos de área de trabajo.