Personaliza funciones de Python para BigQuery DataFrames

BigQuery DataFrames te permite convertir tus funciones personalizadas de Python en artefactos de BigQuery que puedes ejecutar a gran escala en objetos de BigQuery DataFrames. Esta compatibilidad con la extensibilidad te permite realizar operaciones más allá de lo que es posible con las APIs de BigQuery DataFrames y SQL, por lo que puedes aprovechar las bibliotecas de código abierto.

Existen dos variantes de este mecanismo de extensibilidad: funciones definidas por el usuario y funciones remotas.

Roles obligatorios

Para obtener los permisos que necesitas para completar las tareas de este documento, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Funciones definidas por el usuario (UDF)

Con las UDF (versión preliminar), puedes convertir tu función personalizada de Python en una UDF de Python. Para ver un ejemplo de uso, consulta Crea una UDF persistente en Python.

Cuando se crea una UDF en BigQuery DataFrames, se crea una rutina de BigQuery como la UDF de Python en el conjunto de datos especificado. Para obtener un conjunto completo de parámetros admitidos, consulta bigframes.pandas.udf.

Requisitos

Para usar una UDF de BigQuery DataFrames, habilita la API de BigQuery en tu proyecto. Si proporcionas el parámetro bigquery_connection en tu proyecto, también debes habilitar la API de BigQuery Connection.

Realiza una limpieza

Además de limpiar los artefactos de Cloud directamente en la consola de Google Cloud o con otras herramientas, puedes limpiar las UDF de BigQuery DataFrames que se crearon con un argumento de nombre explícito usando el comandobigframes.pandas.get_global_session().bqclient.delete_routine(routine_id).

Limitaciones

  • El código de la UDF debe ser independiente, es decir, no debe contener ninguna referencia a una importación o variable definida fuera del cuerpo de la función.
  • El código de la UDF debe ser compatible con Python 3.11, ya que ese es el entorno en el que se ejecuta el código en la nube.
  • Volver a ejecutar el código de definición de la UDF después de realizar cambios triviales en el código de la función (por ejemplo, cambiar el nombre de una variable o insertar una línea nueva) provoca que se vuelva a crear la UDF, incluso si estos cambios no son importantes para el comportamiento de la función.
  • El código del usuario es visible para los usuarios con acceso de lectura en las rutinas de BigQuery, por lo que debes incluir contenido sensible con precaución.
  • Un proyecto puede tener hasta 1,000 funciones de Cloud Run a la vez en una ubicación de BigQuery.

La UDF de BigQuery DataFrames implementa una función de Python de BigQuery definida por el usuario, y se aplican las limitaciones relacionadas.

Funciones remotas

BigQuery DataFrames te permite convertir tus funciones escalares personalizadas en funciones remotas de BigQuery. Para ver un ejemplo de uso, consulta Crea una función remota. Para obtener un conjunto completo de parámetros admitidos, consulta remote_function.

Cuando se crea una función remota en BigQuery DataFrames, se crea lo siguiente:

  • Una función de Cloud Run

  • Una conexión de BigQuery.

    De forma predeterminada, se usa una conexión llamada bigframes-default-connection. Si lo prefieres, puedes usar una conexión de BigQuery preconfigurada, en cuyo caso se omite la creación de la conexión. A la cuenta de servicio para la conexión predeterminada se le otorga el rol de Cloud Run (roles/run.invoker).

  • Una función remota de BigQuery que usa la función de Cloud Run que se creó con la conexión de BigQuery.

Requisitos

Para usar las funciones remotas de BigQuery DataFrames, debes habilitar las siguientes APIs:

Cuando usas las funciones remotas de BigQuery DataFrames, necesitas el rol de administrador de IAM del proyecto (roles/resourcemanager.projectIamAdmin) si usas una conexión de BigQuery predeterminada o el rol de navegador (roles/browser) si usas una conexión preconfigurada. Para evitar este requisito, configura la opción bigframes.pandas.options.bigquery.skip_bq_connection_check en True, en cuyo caso la conexión (predeterminada o preconfigurada) se usará tal como está sin ninguna existencia o permiso. Si usas la conexión preconfigurada y omites la verificación de conexión, verifica lo siguiente:

  • La conexión se crea en la ubicación correcta.
  • Si usas las funciones remotas de BigQuery DataFrames, la cuenta de servicio tiene el rol de invocador de Cloud Run (roles/run.invoker) en el proyecto.

Cómo ver y administrar conexiones

Las conexiones de BigQuery se crean en la misma ubicación que la sesión de BigQuery DataFrames, con el nombre que proporcionas en la definición de la función personalizada. Para ver y administrar conexiones, haz lo siguiente:

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

    Ir a BigQuery

  2. Selecciona el proyecto en el que creaste la función remota.

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

    Botón destacado del panel Explorador.

  4. En el panel Explorador, expande el proyecto y, luego, haz clic en Conexiones.

Las funciones remotas de BigQuery se crean en el conjunto de datos que especificas o en un conjunto de datos anónimo, que es un tipo de conjunto de datos oculto. Si no estableces un nombre para una función remota durante su creación, BigQuery DataFrames aplica un nombre predeterminado que comienza con el prefijo bigframes. Para ver y administrar funciones remotas creadas en un conjunto de datos especificado por el usuario, haz lo siguiente:

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

    Ir a BigQuery

  2. Selecciona el proyecto en el que creaste la función remota.

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

    Botón destacado del panel Explorador.

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

  5. Haz clic en el conjunto de datos en el que creaste la función remota.

  6. Haz clic en la pestaña Rutinas.

Para ver y administrar las Cloud Run Functions, haz lo siguiente:

  1. Ir a la página Cloud Run.

    Ir a Cloud Run

  2. Selecciona el proyecto en el que creaste la función.

  3. En la lista de servicios disponibles, filtra por Tipo de implementación de función.

  4. Para identificar las funciones creadas por BigQuery DataFrames, busca nombres de funciones con el prefijo bigframes.

Realiza una limpieza

Además de limpiar los artefactos de la nube directamente en la consola de Google Cloud o con otras herramientas, puedes limpiar las funciones remotas de BigQuery que se crearon sin un argumento de nombre explícito y sus funciones asociadas de Cloud Run de las siguientes maneras:

  • Para una sesión de BigQuery DataFrames, usa el comando session.close().
  • Para la sesión predeterminada de BigQuery DataFrames, usa el comando bigframes.pandas.close_session().
  • Para una sesión anterior con session_id, usa el comando bigframes.pandas.clean_up_by_session_id(session_id).

También puedes limpiar las funciones remotas de BigQuery que se crearon con un argumento de nombre explícito y sus funciones asociadas de Cloud Run con el comando bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id).

Limitaciones

  • Las funciones remotas tardan unos 90 segundos en estar disponibles cuando las creas por primera vez. Las dependencias de paquetes adicionales pueden aumentar la latencia.
  • Volver a ejecutar el código de definición de la función remota después de realizar cambios triviales en el código de la función y a su alrededor (por ejemplo, cambiar el nombre de una variable, insertar una línea nueva o insertar una celda nueva en el notebook) puede provocar que se vuelva a crear la función remota, incluso si estos cambios no son importantes para el comportamiento de la función.
  • El código del usuario es visible para los usuarios con acceso de lectura en las funciones de Cloud Run, por lo que debes incluir contenido sensible solo con precaución.
  • Un proyecto puede tener hasta 1,000 funciones de Cloud Run a la vez en una región. Para obtener más información, consulta Cuotas.

¿Qué sigue?