read_files funkcja wartości tabeli

Dotyczy: Databricks SQL Databricks Runtime 13.3 LTS i nowsze

Odczytuje pliki w podanej lokalizacji i zwraca dane w postaci tabelarycznej.

Obsługuje odczytywanie formatów plików JSON, CSV, XML, TEXT, BINARYFILE, PARQUET, AVRO i ORC. Umożliwia automatyczne wykrywanie formatu pliku i wnioskowanie o ujednoliconym schemacie we wszystkich plikach.

Uwaga / Notatka

Dostępny w wersji beta, ustawiony format => 'file' tak, aby zwracał referencję FILE dla każdego pliku zamiast czytać jego zawartość. Zobacz FILE pliki typu i Ingest jako typ PLIKU.

Składnia

read_files(path [, option_key => option_value ] [...])

Argumenty

Ta funkcja wymaga użycia wywołania z nazwanymi parametrami dla kluczy opcji.

• path: A STRING z URI lokalizacji danych. Obsługuje odczyt z Azure Data Lake Storage ('abfss://'), S3 (s3://) i Google Cloud Storage ('gs://'). Może zawierać globy. Aby uzyskać więcej informacji, zobacz Odnajdywanie plików.
• option_key: nazwa opcji do skonfigurowania. Należy użyć znaku `backtick` () for options that contain dots (.`).
• option_value: wyrażenie stałe, aby ustawić opcję. Akceptuje literały i funkcje skalarne.

Zwraca

Tabela zawierająca dane z plików odczytanych w danym pathobiekcie . Schemat zależy od formatu pliku:

• BINARYFILE: Zwraca stały schemat:

  Kolumna	Typ	opis
  path	STRING	Pełna ścieżka, w której ma być wyszukiwany plik.
  modificationTime	TIMESTAMP	Czas ostatniej modyfikacji pliku.
  length	LONG	Rozmiar pliku w bajtach.
  content	BINARY	Zawartość binarna pliku. Użyj polecenia * EXCEPT (content) , aby wykluczyć zawartość binarną podczas wykonywania zapytań dotyczących metadanych pliku.

• TEXT: Zwraca stały schemat z jedną value kolumną (STRING).

• Wszystkie inne formaty (JSON, CSV, XML, PARQUET, AVRO, ORC): schemat jest wywnioskowany z zawartości pliku lub udostępniany jawnie przy użyciu schema opcji .

_metadata Kolumna

read_files Uwidacznia kolumnę _metadata z metadanymi na poziomie pliku. Ta kolumna nie jest uwzględniona w SELECT * wynikach i musi zostać jawnie wybrana. Zawiera następujące pola:

Pole	Typ	opis
file_path	STRING	Pełna ścieżka do pliku źródłowego.
file_name	STRING	Nazwa pliku źródłowego.
file_size	LONG	Rozmiar pliku źródłowego w bajtach.
file_modification_time	TIMESTAMP	Czas ostatniej modyfikacji pliku źródłowego.
file_block_start	LONG	Początek bloku odczytywanego pliku.
file_block_length	LONG	Długość bloku odczytywanego pliku.

Aby uwzględnić _metadata wyniki, wybierz ją jawnie:

SELECT * EXCEPT (content), _metadata
FROM read_files('/Volumes/my_catalog/my_schema/my_volume', format => 'binaryFile');

Odnajdywanie plików

read_files może odczytywać pojedynczy plik lub odczytywać pliki w podanym katalogu. read_files wyszukuje wszystkie pliki w podanym katalogu rekurencyjnie, chyba że podano element glob, co nakazuje read_files rekurencyjne przeszukanie konkretnego wzorca katalogu.

Filtrowanie katalogów lub plików przy użyciu wzorców glob

Wzorce globu mogą służyć do filtrowania katalogów i plików, jeśli są zawarte w ścieżce.

Wzorzec	opis
?	Dopasowuje dowolny pojedynczy znak
*	Dopasowuje zero lub więcej znaków
[abc]	Dopasuje pojedynczy znak z zestawu znaków {a,b,c}.
[a-z]	Dopasuje pojedynczy znak z zakresu znaków {a... z}.
[^a]	Dopasuje pojedynczy znak, który nie pochodzi z zestawu znaków lub zakresu {a}. Należy pamiętać, że ^ znak musi występować natychmiast po prawej stronie nawiasu otwierającego.
{ab,cd}	Dopasuje ciąg z zestawu ciągów {ab, cd}.
{ab,c{de, fh}}	Dopasuje ciąg z zestawu ciągów {ab, cde, cfh}.

read_files używa ścisłego globberu narzędzia Auto Loader podczas odnajdywania plików z globsami. Jest to konfigurowane przez useStrictGlobber opcję . Gdy ścisły mechanizm globowania jest wyłączony, końcowe ukośniki (/) są pomijane, a wzorzec gwiazdy, taki jak /*/, może posłużyć do odnajdywania wielu katalogów. Zapoznaj się z poniższymi przykładami, aby zobaczyć różnicę w zachowaniu.

Wzorzec	Ścieżka pliku	Ścisłe globber wyłączone	Włączono ścisłe dopasowywanie wzorców (globber)
/a/b	/a/b/c/file.txt	Tak	Tak
/a/b	/a/b_dir/c/file.txt	Nie	Nie
/a/b	/a/b.txt	Nie	Nie
/a/b/	/a/b.txt	Nie	Nie
/a/*/c/	/a/b/c/file.txt	Tak	Tak
/a/*/c/	/a/b/c/d/file.txt	Tak	Tak
/a/*/d/	/a/b/c/d/file.txt	Tak	Nie
/a/*/c/	/a/b/x/y/c/file.txt	Tak	Nie
/a/*/c	/a/b/c_file.txt	Tak	Nie
/a/*/c/	/a/b/c_file.txt	Tak	Nie
/a/*/c	/a/b/cookie/file.txt	Tak	Nie
/a/b*	/a/b.txt	Tak	Tak
/a/b*	/a/b/file.txt	Tak	Tak
/a/{0.txt,1.txt}	/a/0.txt	Tak	Tak
/a/*/{0.txt,1.txt}	/a/0.txt	Nie	Nie
/a/b/[cde-h]/i/	/a/b/c/i/file.txt	Tak	Tak

Wnioskowanie schematu

Schemat plików można jawnie udostępnić read_files za pomocą opcji schema. Gdy schemat nie zostanie podany, read_files próbuje wywnioskować ujednolicony schemat między odnalezionymi plikami, co wymaga odczytania wszystkich plików, chyba że zostanie użyta LIMIT instrukcja. Nawet w przypadku użycia zapytania LIMIT może zostać odczytany większy zestaw plików niż jest to konieczne, aby zwrócić bardziej reprezentatywny schemat danych. Usługa Databricks automatycznie dodaje instrukcję LIMIT dla zapytań SELECT w notesach i edytorze SQL, jeśli użytkownik nie podał jej samodzielnie.

Opcja schemaHints może być użyta do naprawienia podzbiorów wywnioskowanego schematu. Aby uzyskać więcej informacji, zapoznaj się z Zastępowanie inferencji schematu za pomocą wskazówek schematu.

Element A rescuedDataColumn jest domyślnie udostępniany do ratowania wszystkich danych, które nie są zgodne ze schematem. Aby uzyskać więcej informacji, zobacz Co to jest uratowana kolumna danych? Możesz usunąć tę rescuedDataColumn opcję, ustawiając opcję schemaEvolutionMode => 'none'.

Wnioskowanie schematu partycji

read_files może również wywnioskować kolumny partycjonowania, jeśli pliki są przechowywane w katalogach podzielonych na partycje w stylu Hive'a, czyli /column_name=column_value/. Jeśli podano schema, odnalezione kolumny partycji używają typów podanych w schema. Jeśli kolumny partycji nie są częścią podanej wartości schema, wnioskowane kolumny partycji są ignorowane.

Jeśli kolumna istnieje zarówno w schemacie partycji, jak i w kolumnach danych, wartość odczytywana z wartości partycji jest używana zamiast wartości danych. Jeśli chcesz zignorować wartości pochodzące z katalogu i użyć kolumny danych, możesz podać listę kolumn partycji na liście rozdzielanej przecinkami z opcją partitionColumns .

Opcję partitionColumns można również użyć, aby poinstruować read_files które odnalezione kolumny mają zostać uwzględnione w końcowym schemacie wnioskowanym. Podanie pustego ciągu ignoruje wszystkie kolumny partycji.

schemaHints Można również podać opcję zastąpienia wnioskowanego schematu dla kolumny partycji.

Formaty TEXT i BINARYFILE mają stały schemat, ale read_files także próbuje wywnioskować partycjonowanie dla tych formatów, gdy jest to możliwe.

Uwierzytelnianie dla magazynu w chmurze

read_files odczytuje pliki z lokalizacji zewnętrznych wykazu aparatu Unity lub woluminów wykazu aparatu Unity (zarządzanych i zewnętrznych). Musisz mieć READ FILES uprawnienia do lokalizacji zewnętrznej lub READ VOLUME uprawnienia na woluminie zawierającym pliki, które chcesz odczytać. Zobacz Nawiązywanie połączenia z magazynem obiektów w chmurze przy użyciu wykazu aparatu Unity lub Co to są woluminy wykazu aparatu Unity?.

Użycie w tabelach streamingowych

read_files można używać w tabelach strumieniowych do wczytywania plików do Delta Lake. read_files korzysta z Auto Loader, gdy jest używany w zapytaniu tabeli strumieniowej. Należy użyć słowa kluczowego STREAM wraz z read_files. Aby uzyskać więcej informacji, zobacz Co to jest moduł automatycznego ładowania?

W przypadku użycia w zapytaniu read_files przesyłanym strumieniowo używa próbki danych do wnioskowania schematu i może rozwijać schemat w miarę przetwarzania większej ilości danych. Aby uzyskać więcej informacji, zobacz Konfigurowanie wnioskowania schematu i ewolucji w module automatycznego ładowania .

Opcje

• Opcje podstawowe
• Opcje specyficzne dla formatu
• Opcje przesyłania strumieniowego

Opcje podstawowe

Opcja	Typ	opis	Wartość domyślna
format	String	Format pliku danych w ścieżce źródłowej. Automatycznie wywnioskowane, jeśli pominięcie. Dozwolone wartości obejmują , , , ( file Beta), json, orc, parquet, text, oraz xml. csvbinaryFileavro	Żadne
schema	String	Schemat plików do odczytania. Określ ciąg schematu w formacie DDL, na przykład 'id int, ts timestamp, event string'. Jeśli zostanie pominięty, read_files próbuje wywnioskować jednolity schemat w odkrytych plikach.	Żadne
inferColumnTypes	Boolean	Czy wywnioskować dokładne typy kolumn podczas korzystania z wnioskowania schematu. Domyślnie kolumny są wnioskowane podczas wnioskowania zestawów danych JSON i CSV. To jest przeciwieństwo domyślnego zachowania Auto Loadera. Zobacz wnioskowanie schematu.	true
partitionColumns	String	Lista kolumn partycji w stylu Hive oddzielona przecinkami, służąca do wnioskowania ze struktury katalogów plików. Kolumny partycji w stylu Hive to pary klucz-wartość połączone znakiem równości, takim jak <base-path>/a=x/b=1/c=y/file.format. W tym przykładzie kolumny partycji to a, bi c. Jeśli użyjesz wnioskowania schematu i przekażesz dane <base-path> do ładowania, te kolumny są automatycznie dodawane do schematu. Jeśli określisz schemat, moduł automatycznego ładowania oczekuje, że te kolumny zostaną uwzględnione w schemacie. Jeśli nie chcesz, aby te kolumny były częścią schematu, określ "" , aby je ignorować. Możesz także użyć tej opcji do wnioskowania kolumn ze ścieżki pliku w złożonych strukturach katalogów. Na przykład dla następujących plików, określając cloudFiles.partitionColumns jako zwraca year,month,dayyear=2022 dla file1.csv, ale kolumny month i są day .null month day i są poprawnie analizowane dla file2.csv i file3.csv: <base-path>/year=2022/week=1/file1.csv <base-path>/year=2022/month=2/day=3/file2.csv <base-path>/year=2022/month=2/day=4/file3.csv	Żadne
schemaHints	String	Informacje o schematach, które przekazujesz do Auto Loadera podczas wnioskowania schematu. Aby uzyskać więcej szczegółów, zobacz wskazówki dotyczące schematu.	Żadne
useStrictGlobber	Boolean	Czy używać restrykcyjnego wzorca globowania, który odpowiada domyślnemu zachowaniu globbingu innych źródeł plików w Apache Spark. Aby uzyskać więcej informacji, zobacz Typowe wzorce ładowania danych. Dostępne w środowisku Databricks Runtime 12.2 LTS lub nowszym. To przeciwieństwo domyślnego ustawienia w Auto Loader.	true

Opcje specyficzne dla formatu

Aby uzyskać opcje specyficzne dla każdego formatu pliku (JSON, CSV, XML, Parquet, Avro, text, ORC i binary), zobacz Opcje elementu DataFrameReader.

Opcje przesyłania strumieniowego

Te opcje mają zastosowanie w przypadku używania read_filestabeli przesyłania strumieniowego lub zapytania przesyłania strumieniowego.

Opcja	Typ	opis	Wartość domyślna
allowOverwrites	Boolean	Czy przetworzyć pliki, które zmieniły się po odkryciu dowodów. Podczas odświeżania read_files plik jest ponownie przetwarzany, jeśli został on zmodyfikowany po ostatnim udanym odświeżeniu.	false
includeExistingFiles	Boolean	Czy dołączyć istniejące pliki do ścieżki wejściowej przetwarzania strumienia, czy tylko przetworzyć nowe pliki przychodzące po wstępnej konfiguracji. Ta opcja jest oceniana tylko wtedy, gdy uruchamiasz strumień po raz pierwszy. Zmiana tej opcji po ponownym uruchomieniu strumienia nie ma żadnego wpływu.	true
maxBytesPerTrigger	Byte String	Maksymalna liczba nowych bajtów do przetworzenia w każdym wyzwalaczu. Można określić ciąg bajtów, taki jak 10g, aby ograniczyć każdą mikropartię do 10 GB danych. Jest to łagodne maksimum. Jeśli masz pliki o rozmiarze 3 GB, Azure Databricks przetwarza 12 GB w mikrobajtach. W przypadku użycia razem z maxFilesPerTrigger Azure Databricks zużywa do niższego limitu maxFilesPerTrigger lub maxBytesPerTrigger, w zależności od tego, co zostanie osiągnięte jako pierwsze. Dla tabel streamingowych tworzonych w serwerowych magazynach SQL nie ustawiaj tej opcji ani maxFilesPerTrigger, aby wykorzystać dynamiczną kontrolę przyjęć.	Żadne
maxFilesPerTrigger	Integer	Maksymalna liczba nowych plików do przetworzenia w każdym wyzwalaczu. W przypadku użycia razem z maxBytesPerTrigger Azure Databricks zużywa do niższego limitu maxFilesPerTrigger lub maxBytesPerTrigger, w zależności od tego, co zostanie osiągnięte jako pierwsze. Dla tabel streamingowych tworzonych w serwerowych magazynach SQL nie ustawiaj tej opcji ani maxBytesPerTrigger, aby wykorzystać dynamiczną kontrolę przyjęć.	1000
schemaEvolutionMode	String	Tryb ewolucji schematu w miarę odnajdowania nowych kolumn w danych. Domyślnie kolumny są wnioskowane jako ciągi podczas wnioskowania zestawów danych JSON. Zobacz ewolucję schematu, aby uzyskać więcej szczegółów. Ta opcja nie ma zastosowania do plików text i binaryFile.	"addNewColumns"Inaczej bez schematu. "none"
schemaLocation	String	Lokalizacja do przechowywania wywnioskowanych schematów i kolejnych zmian. Aby uzyskać więcej informacji, zobacz wnioskowanie schematu. Lokalizacja schematu nie jest wymagana podczas zapytania do tabeli strumieniowej.	Żadne

Przykłady

-- Reads the files available in the given path. Auto-detects the format and schema of the data.
> SELECT * FROM read_files('abfss://container@storageAccount.dfs.core.windows.net/base/path');

-- Reads the headerless CSV files in the given path with the provided schema.
> SELECT * FROM read_files(
    's3://bucket/path',
    format => 'csv',
    schema => 'id int, ts timestamp, event string');

-- Infers the schema of CSV files with headers. Because the schema is not provided,
-- the CSV files are assumed to have headers.
> SELECT * FROM read_files(
    's3://bucket/path',
    format => 'csv')

-- Reads files that have a csv suffix.
> SELECT * FROM read_files('s3://bucket/path/*.csv')

-- Reads a single JSON file
> SELECT * FROM read_files(
    'abfss://container@storageAccount.dfs.core.windows.net/path/single.json')

-- Reads JSON files and overrides the data type of the column `id` to integer.
> SELECT * FROM read_files(
    's3://bucket/path',
    format => 'json',
    schemaHints => 'id int')

-- Reads files that have been uploaded or modified yesterday.
> SELECT * FROM read_files(
    'gs://my-bucket/avroData',
    modifiedAfter => date_sub(current_date(), 1),
    modifiedBefore => current_date())

-- Creates a Delta table and stores the source file path as part of the data
> CREATE TABLE my_avro_data
  AS SELECT *, _metadata.file_path
  FROM read_files('gs://my-bucket/avroData')

-- Creates a streaming table that processes files that appear only after the table's creation.
-- The table will most likely be empty (if there's no clock skew) after being first created,
-- and future refreshes will bring new data in.
> CREATE OR REFRESH STREAMING TABLE avro_data
  AS SELECT * FROM STREAM read_files('gs://my-bucket/avroData', includeExistingFiles => false);

Praca z plikami bez struktury

W poniższych przykładach używany jest BINARYFILE format do odczytywania i filtrowania plików bez struktury przechowywanych w woluminach wykazu aparatu Unity oraz łączenia się read_files z funkcjami sztucznej inteligencji w celu przetwarzania zawartości pliku.

Wyświetl listę wszystkich plików w woluminie: użyj polecenia * EXCEPT (content) , aby zwrócić metadane pliku bez ładowania zawartości binarnej, a następnie wybierz _metadata jawnie, aby uwzględnić pola metadanych na poziomie pliku.

SELECT
  * EXCEPT (content),
  _metadata
FROM read_files(
  '/Volumes/<catalog>/<schema>/<volume>',
  format => 'binaryFile'
);

Wyświetlanie listy plików obrazów filtrowanych według rozmiaru: służy fileNamePattern do określania docelowych typów plików obrazów i filtrowania, _metadata.file_size aby zwracać tylko pliki w danym zakresie rozmiaru.

SELECT
  * EXCEPT (content),
  _metadata
FROM read_files(
  '/Volumes/my_catalog/my_schema/my_volume',
  format => 'binaryFile',
  fileNamePattern => '*.{jpg,jpeg,png,JPG,JPEG,PNG}'
)
WHERE _metadata.file_size BETWEEN 20000 AND 1000000;

Wyświetl listę plików PDF zmodyfikowanych w ciągu ostatniego dnia: służy fileNamePattern do określania docelowych plików PDF i filtrowania, modificationTime aby zwracać tylko pliki zmienione w ciągu ostatniego dnia.

SELECT
  * EXCEPT (content),
  _metadata
FROM read_files(
  '/Volumes/my_catalog/my_schema/my_volume',
  format => 'binaryFile',
  fileNamePattern => '*.{pdf,PDF}'
)
WHERE modificationTime >= current_timestamp() - INTERVAL 1 DAY;

Uruchamianie funkcji sztucznej inteligencji w plikach obrazów: służy ai_query do przetwarzania plików obrazów odczytywanych ze ścieżki magazynu w chmurze. Filtruj według _metadata pól pod kątem określonych plików.

SELECT
  path AS file_path,
  ai_query(
    'databricks-llama-4-maverick',
    'Describe this image in ten words or less: ',
    files => content
  ) AS result
FROM read_files(
  's3://my-s3-bucket/path/to/images/',
  format => 'binaryFile',
  fileNamePattern => '*.{jpg,jpeg,png,JPG,JPEG,PNG}'
)
WHERE _metadata.file_size < 1000000
  AND _metadata.file_name LIKE '%robots%';

Analizowanie dokumentów pasujących do wzorca nazwy pliku: służy ai_parse_document do wyodrębniania zawartości ustrukturyzowanej z plików PDF i obrazów. Filtruj według _metadata.file_name , aby kierować do określonych plików.

SELECT
  path AS file_path,
  ai_parse_document(
    content,
    map('version', '2.0')
  ) AS result
FROM read_files(
  '/Volumes/main/public/my_files/',
  format => 'binaryFile',
  fileNamePattern => '*.{jpg,jpeg,pdf,png}'
)
WHERE _metadata.file_name ILIKE '%receipt%';

Dołączanie plików z tabelą ustrukturyzowaną: przepływy pracy bez struktury często wymagają scalania danych ustrukturyzowanych przechowywanych w tabelach z plikami bez struktury. Poniższy przykład łączy pliki w ścieżce magazynu w chmurze z dwiema tabelami ustrukturyzowanymi, filtrując według rozmiaru pliku i atrybutu użytkownika. Sprzężenie za user_files pomocą polecenia jest wykonywane przez wyodrębnienie identyfikatora pliku ze ścieżki pliku przy użyciu polecenia split i element_at.

SELECT
  users.user_id,
  user_files.file_id,
  files._metadata.file_name AS file_name,
  files.* EXCEPT (content),
  ai_parse_document(files.content, map('version', '2.0')) AS parsed_document
FROM read_files(
  's3://my-bucket-name/files/',
  format => 'binaryFile',
  fileNamePattern => '*.{pdf,doc,docx,ppt,pptx,png,jpg,jpeg}'
) AS files
JOIN user_files
  ON user_files.file_id = element_at(split(files.path, '/'), -2)
JOIN users
  ON users.user_id = user_files.user_id
WHERE users.email LIKE '%@databricks.com'
  AND files._metadata.file_size < 10000000;

Funkcje pokrewne

• list_files funkcja zwracająca wartości tabeli

Powiązane artykuły

• CREATE STREAMING TABLE
• read_kafka funkcja zwracająca wartości tabeli