`cloud_files_state`-Tabellenwertfunktion

2025-06-07

Gilt für: Häkchen ja Databricks SQL Häkchen bei ja Databricks Runtime 11.3 LTS und höher

Gibt den Status eines Autoloader oder read_files-Streams auf Dateiebene zurück.

Syntax

cloud_files_state( { TABLE ( table_name ) | checkpoint } )

Argumente

table_name: Der Bezeichner der Streamingtabelle, in die von read_files geschrieben wird. Der Name darf keine temporale Spezifikation enthalten. Verfügbar in Databricks Runtime 13.3 LTS und höher.
checkpoint: Ein STRING-Literal Das Prüfpunktverzeichnis für einen Stream, der die AutoLoader-Quelle verwendet Weitere Informationen finden Sie unter "Automatisches Laden".

Gibt zurück

Gibt eine Tabelle mit dem folgenden Schema zurück:

path STRING NOT NULL PRIMARY KEY

Der Pfad einer Datei.
size BIGINT NOT NULL

Die Größe einer Datei in Bytes.
create_time TIMESTAMP NOT NULL

Der Zeitpunkt, zu dem eine Datei erstellt wurde.
discovery_time TIMESTAMP NOT NULL

Gilt für: Databricks SQL Databricks Runtime 16.4 und höher

Der Zeitpunkt, zu dem eine Datei entdeckt wurde.
processed_time TIMESTAMP NOT NULL

Gilt für: Databricks SQL Databricks Runtime 16.4 und höher, wenn cloudFiles.cleanSource aktiviert ist. Weitere Informationen finden Sie unter "Optionen für das automatische Laden".

Die Zeit, zu der eine Datei verarbeitet wurde. Wenn bei einem Batch ein Fehler auftritt und ein Wiederholungsversuch auftritt, wird eine Datei möglicherweise mehrmals verarbeitet. Wenn Wiederholungen auftreten, enthält dieses Feld die letzte Verarbeitungszeit.
commit_time TIMESTAMP

Gilt für: Databricks SQL Databricks Runtime 16.4 und höher, wenn cloudFiles.cleanSource aktiviert ist. Weitere Informationen finden Sie unter "Optionen für das automatische Laden".

Der Zeitpunkt, zu dem eine Datei nach der Verarbeitung an den Prüfpunkt committet wurde. NULL, wenn die Datei noch nicht verarbeitet wurde. Es gibt keine garantierte Latenz zum Markieren einer Datei als zugesichert; eine Datei kann verarbeitet, aber später willkürlich als zugesichert gekennzeichnet werden. Wenn eine Datei als committet markiert wird, bedeutet dies, dass der AutoLoader die Datei nicht mehr zur Verarbeitung benötigt.
archive_time TIMESTAMP

Gilt für: Databricks SQL Databricks Runtime 16.4 und höher, wenn cloudFiles.cleanSource aktiviert ist. Weitere Informationen finden Sie unter "Optionen für das automatische Laden".

Der Zeitpunkt, zu dem eine Datei archiviert wurde. NULL, wenn die Datei nicht archiviert wurde.
archive_mode STRING

Gilt für: Databricks SQL Databricks Runtime 16.4 und höher, wenn cloudFiles.cleanSource aktiviert ist. Weitere Informationen finden Sie unter "Optionen für das automatische Laden".

MOVE, wenn cloudFiles.cleanSource beim Archivieren der Datei auf MOVE festgelegt wurde.

DELETE, wenn cloudFiles.cleanSource beim Archivieren der Datei auf DELETE festgelegt wurde.

NULL wenn cloudFiles.cleanSource auf OFF (Standardeinstellung) festgelegt wurde.
move_location STRING

Gilt für: Databricks SQL Databricks Runtime 16.4 und höher, wenn cloudFiles.cleanSource aktiviert ist. Weitere Informationen finden Sie unter "Optionen für das automatische Laden".

Der vollständige Pfad, zu dem die Datei während des Archivierungsvorgangs verschoben wurde, als cloudFiles.cleanSource auf MOVE gesetzt war.

NULL wenn die Datei nicht archiviert wurde oder cloudFiles.cleanSource eine von DELETE oder OFFist.
source_id STRING

Die ID der AutoLoader-Quelle in der Streamingabfrage Dieser Wert lautet '0' für Datenströme, die von einem einzelnen Speicherort für Cloudobjekte erfasst werden.
flow_name STRING

Gilt für: Databricks SQL Databricks Runtime 13.3 und höher

Stellt einen bestimmten Streamingfluss in der Lakeflow Declarative Pipeline dar, die eine oder mehrere Cloud-Dateiquellen enthält. NULL, wenn kein table_name angegeben wurde.
ingestion_state STRING

Gilt für: Databricks SQL Databricks Runtime 16.4 und höher, wenn cloudFiles.cleanSource aktiviert ist. Weitere Informationen finden Sie unter "Optionen für das automatische Laden".

Ob die Datei erfasst wurde, was durch einen der folgenden Zustände angezeigt wird:
- NULL: Die Datei wurde noch nicht verarbeitet, oder der Dateistatus kann nicht vom automatischen Laden bestimmt werden.
- PROCESSING: Die Datei wird verarbeitet.
- SKIPPED_CORRUPTED: Die Datei wurde nicht aufgenommen, weil sie beschädigt war.
- SKIPPED_MISSING: Die Datei wurde nicht aufgenommen, weil sie während der Verarbeitung nicht gefunden wurde.
- INGESTED: Die Datei wurde mindestens einmal von der Senke verarbeitet. Bei Fehlern im Datenstrom kann sie erneut von nicht-idempotenten Senken wie foreachBatch verarbeitet werden. Nur Dateien mit einem Nicht-Null-commit_time-Feld, die sich im INGESTED-Zustand befinden, haben die Verarbeitung abgeschlossen.
- NOT_RECOGNIZED_BY_DBR: Für Versionskompatibilität reserviert. Dieser Zustand wird für Zustände angezeigt, die in späteren Databricks-Runtime-Versionen eingeführt wurden, die von früheren Databricks-Runtime-Versionen nicht erkannt werden.

Berechtigungen

Sie benötigen Folgendes:

OWNER-Berechtigungen für die Streamingtabelle bei Verwendung eines Streamingtabellenbezeichners
READ FILES-Berechtigungen für den Prüfpunktspeicherort, wenn ein Prüfpunkt unter einem externen Speicherort bereitgestellt wird.

Beispiele

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

Einschränkungen

Die Tabellenwertfunktion kann nicht in einer ETL-Pipeline verwendet werden, um den Zustand auf Dateiebene einer Streamingtabelle zu lesen, die von einer anderen Pipeline erzeugt wird.
Eine Abfrage kann nicht mehr als eine einzige cloud_files_state Tabellenwertfunktion auf verschiedenen Streamingtabellen referenzieren.

Um die erste Einschränkung zu umgehen, können Sie einen Databricks-Auftrag erstellen und die Tabellenwertfunktion in einer Notizbuchaufgabe verwenden, um den Zustand auf Dateiebene einer Streamingtabelle zu extrahieren und zu laden. Beispiel:

Klicken Sie in der Randleiste des Arbeitsbereichs auf Aufträge und Pipelines.
Klicken Sie auf eine Aufgabe.

Erstellen Sie eine neue Pipelineaufgabe , die eine Streamingtabelle erzeugt. Beispiel:

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

Erstellen Sie eine neue Notizbuchaufgabe , die den Status der Streamingtabelle auf Dateiebene mithilfe der cloud_files_state Tabellenwertfunktion liest und in eine Tabelle lädt. Beispiel:
```
spark
  .sql("""SELECT * FROM cloud_files_state(TABLE(<table-name>)""")
  .write
  .saveAsTable('<table-file-state>')
```
Konfigurieren Sie das Feld "Abhängig von " der Aufgabe " Notizbuch ", und wählen Sie die Pipelineaufgabe aus.

Freigeben über

cloud_files_state-Tabellenwertfunktion