`cloud_files_state` función con valores de tabla

2025-06-19

Se aplica a: casilla marcada como sí Databricks SQL Databricks Runtime 11.3 LTS y versiones posteriores

Devuelve el estado a nivel de archivo de un flujo de Auto Loader o read_files.

Sintaxis

cloud_files_state( { TABLE ( table_name ) | checkpoint } )

Argumentos

table_name: el identificador de la tabla de streaming a la que read_files está escribiendo. El nombre no debe incluir una especificación temporal. Disponible en Databricks Runtime 13.3 LTS y versiones posteriores.
checkpoint: un literal STRING. Directorio de punto de control de una secuencia mediante el origen del cargador automático. Consulte ¿Qué es Auto Loader?.

Devoluciones

Devuelve una tabla con el esquema siguiente:

path STRING NOT NULL PRIMARY KEY

Ruta de acceso de un archivo.
size BIGINT NOT NULL

Tamaño de un archivo en bytes.
create_time TIMESTAMP NOT NULL

Hora de creación de un archivo.
discovery_time TIMESTAMP NOT NULL

Se aplica a: Databricks SQL Databricks Runtime 16.4 y versiones posteriores

La hora a la que se detectó un archivo.
processed_time TIMESTAMP NOT NULL

Se aplica a: Databricks SQL Databricks Runtime 16.4 y versiones posteriores cuando cloudFiles.cleanSource está habilitado. Consulte Opciones del cargador automático.

Hora en que se procesó un archivo. Si un lote encuentra un error y se reintenta, es posible que un archivo se procese varias veces. Cuando se producen reintentos, este campo contiene el tiempo de procesamiento más reciente.
commit_time TIMESTAMP

Se aplica a: Databricks SQL Databricks Runtime 16.4 y versiones posteriores cuando cloudFiles.cleanSource está habilitado. Consulte Opciones del cargador automático.

Hora a la que se confirmó un archivo en el punto de control después del procesamiento. NULL si el archivo aún no se ha procesado. No hay ninguna latencia garantizada para marcar un archivo como confirmado; Es posible que un archivo se procese pero se marque como confirmado arbitrariamente más adelante. Marcar el archivo como confirmado significa que Auto Loader no requiere el archivo para volver a procesarlo.
archive_time TIMESTAMP

Se aplica a: Databricks SQL Databricks Runtime 16.4 y versiones posteriores cuando cloudFiles.cleanSource está habilitado. Consulte Opciones del cargador automático.

Hora a la que se archivó un archivo. NULL si el archivo no se ha archivado.
archive_mode STRING

Se aplica a: Databricks SQL Databricks Runtime 16.4 y versiones posteriores cuando cloudFiles.cleanSource está habilitado. Consulte Opciones del cargador automático.

MOVE si cloudFiles.cleanSource se estableció en MOVE cuando se ha archivado el archivo.

DELETE si cloudFiles.cleanSource se estableció en DELETE cuando se ha archivado el archivo.

NULL si cloudFiles.cleanSource se estableció en OFF (valor predeterminado).
move_location STRING

Se aplica a: Databricks SQL Databricks Runtime 16.4 y versiones posteriores cuando cloudFiles.cleanSource está habilitado. Consulte Opciones del cargador automático.

Ruta de acceso completa a la que se movió el archivo durante la operación de archivado cuando cloudFiles.cleanSource se estableció en MOVE.

NULL si el archivo no se ha archivado o cloudFiles.cleanSource es uno de DELETE o OFF.
source_id STRING

Identificador del origen de Auto Loader en la consulta de streaming. Este valor es '0' para las secuencias que ingieren desde una única ubicación del almacén de objetos en la nube.
flow_name STRING

Se aplica a: Databricks SQL Databricks Runtime 13.3 y versiones posteriores

Representa un flujo específico de streaming en las canalizaciones declarativas de Lakeflow que contienen uno o varios orígenes de archivos en la nube. NULL si no se ha dado ningún table_name.
ingestion_state STRING

Se aplica a: Databricks SQL Databricks Runtime 16.4 y versiones posteriores cuando cloudFiles.cleanSource está habilitado. Consulte Opciones del cargador automático.

Indica si el archivo se ha ingerido, indicado por uno de los estados siguientes:
- NULL: el archivo aún no se ha procesado o el estado del archivo no se puede determinar mediante el cargador automático.
- PROCESSING: el archivo se está procesando.
- SKIPPED_CORRUPTED: el archivo no se ingerió porque estaba dañado.
- SKIPPED_MISSING: el archivo no se ingerió porque no se encontró durante el procesamiento.
- INGESTED: El proceso receptor ha procesado el archivo al menos una vez. Podría ser procesado de nuevo por receptores no idempotentes, como foreachBatch, en caso de errores en la secuencia. Solo los archivos con un campo no nulo commit_time que se encuentran en el estado INGESTED han completado el procesamiento.
- NOT_RECOGNIZED_BY_DBR: reservado para la compatibilidad de versiones. Este estado se mostrará para los estados introducidos en versiones posteriores de Databricks Runtime no reconocidas por versiones anteriores de Databricks Runtime.

Permisos

Debe tener:

Privilegios de OWNER en la tabla de streaming si usa un identificador de tabla de streaming.
Privilegios de READ FILES en la ubicación del punto de control si proporciona un punto de control en una ubicación externa.

Ejemplos

-- Simple example from checkpoint
> SELECT path FROM CLOUD_FILES_STATE('/some/checkpoint');
  /some/input/path
  /other/input/path

-- Simple example from source subdir
> SELECT path FROM CLOUD_FILES_STATE('/some/checkpoint/sources/0');
  /some/input/path
  /other/input/path

-- Simple example from streaming table
> SELECT path FROM CLOUD_FILES_STATE(TABLE(my_streaming_table));
  /some/input/path
  /other/input/path

Limitaciones

La función con valores de tabla no se puede usar en una canalización ETL para leer el estado a nivel de archivo de una tabla de streaming generada por otra canalización.
Una consulta no puede hacer referencia a más de una cloud_files_state función con valores de tabla en tablas de streaming diferentes.

Para solucionar la primera limitación, puede crear un trabajo de Databricks y usar la función con valores de tabla en una tarea de cuaderno para extraer y cargar el estado de nivel de archivo de una tabla de streaming. Por ejemplo:

En la barra lateral del área de trabajo, haga clic en Trabajos y canalizaciones.
Haga clic en una oferta de trabajo.

Cree una nueva tarea Pipeline que genere una tabla de transmisión de datos. Por ejemplo:

CREATE OR REFRESH STREAMING LIVE TABLE <table-name>
AS SELECT <select clause expressions>
FROM STREAM read_files('/path/to/files', format => '<format>', ...)

Cree una nueva tarea Notebook que lea el estado de nivel de archivo de la tabla de streaming mediante la cloud_files_state función con valores de tabla y cárguelo en una tabla. Por ejemplo:
```
spark
  .sql("""SELECT * FROM cloud_files_state(TABLE(<table-name>)""")
  .write
  .saveAsTable('<table-file-state>')
```
Configure el campo Depende de de la tarea Cuaderno y seleccione la tarea Pipeline.

Compartir vía

cloud_files_state función con valores de tabla