read_files 테이블 값 반환 함수

적용 대상:예로 체크됨 Databricks SQL 예로 체크됨 Databricks Runtime 13.3 LTS 이상

제공된 위치에서 파일을 읽고 테이블 형식으로 데이터를 반환합니다.

다음 파일 형식을 읽을 수 있습니다: JSON, CSV, XML, TEXT, BINARYFILE, PARQUET, AVRO, 및 ORC. 파일 형식을 자동으로 검색하고 모든 파일에서 통합 스키마를 유추할 수 있습니다.

메모

베타 버전으로, 파일 내용을 읽는 대신 각 파일에 대한 참조를 FILE 반환하도록 설정 format => 'file' 되어 있습니다. 파일 타입과 인제스트 파일을 FILE 형식으로 참고 FILE 하세요.

구문

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

논쟁

이 함수에는 옵션 키에 대한 명명된 매개 변수 호출 이 필요합니다.

  • path: 데이터 위치의 URI가 있는 A STRING 입니다. Azure Data Lake Storage('abfss://'), S3(s3://) 및 Google Cloud Storage('gs://')에서 읽기를 지원합니다. 글롭을 포함할 수 있습니다. 자세한 내용은 파일 검색을 참조하세요.
  • option_key: 구성할 옵션의 이름입니다. 백틱() for options that contain dots (`)을 사용해야 합니다.
  • option_value: 옵션을 설정할 상수 식 입니다. 리터럴 및 스칼라 함수를 허용합니다.

반품

지정된 path아래에 읽은 파일의 데이터가 들어 있는 테이블입니다. 스키마는 파일 형식에 따라 달라집니다.

  • BINARYFILE: 고정 스키마를 반환합니다.

    칼럼 유형 설명
    path STRING 파일의 전체 경로입니다.
    modificationTime TIMESTAMP 파일의 마지막 수정 시간입니다.
    length LONG 파일의 크기입니다(바이트).
    content BINARY 파일의 이진 콘텐츠입니다. 파일 메타데이터를 쿼리할 때 이진 콘텐츠를 제외하는 데 사용합니다 * EXCEPT (content) .

  • TEXT: 단일 value (STRING) 열이 있는 고정 스키마를 반환합니다.

  • 다른 모든 형식(JSON, CSV, XML, PARQUET, AVRO, ORC): 스키마는 파일 내용에서 유추되거나 옵션을 사용하여 schema 명시적으로 제공됩니다.

_metadata 열

read_files 는 파일 수준 메타데이터가 있는 _metadata 열을 노출합니다. 이 열은 결과에 포함되지 SELECT * 않으며 명시적으로 선택해야 합니다. 여기에는 다음 필드가 포함됩니다.

분야 유형 설명
file_path STRING 원본 파일의 전체 경로입니다.
file_name STRING 원본 파일의 이름입니다.
file_size LONG 소스 파일의 크기(바이트)입니다.
file_modification_time TIMESTAMP 원본 파일의 마지막 수정 시간입니다.
file_block_start LONG 읽는 파일 블록의 시작입니다.
file_block_length LONG 읽을 파일 블록의 길이입니다.

결과에 포함 _metadata 하려면 명시적으로 선택합니다.

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

파일 검색

read_files는 개별 파일을 읽을 수 있으며, 제공된 디렉터리 내의 파일들 또한 읽을 수 있습니다. read_files는 제공된 디렉터리 아래의 모든 파일을 재귀적으로 탐색합니다. glob이 제공되면, read_files는 지정된 디렉토리 패턴에 따라 재귀적으로 들어갑니다.

GLOB 패턴을 사용하여 디렉터리 또는 파일 필터링

경로에 제공되는 경우 GLOB 패턴을 사용하여 디렉터리 및 파일을 필터링할 수 있습니다.

패턴 설명
? 임의의 단일 문자와 일치합니다.
* 0개 이상의 문자와 일치합니다.
[abc] 문자 집합 {a,b,c}의 단일 문자와 일치합니다.
[a-z] 문자 범위 {a…z}의 단일 문자와 일치합니다.
[^a] 문자 집합 또는 범위 {a}가 아닌 단일 문자와 일치합니다. ^ 문자는 왼쪽 괄호 바로 오른쪽에 있어야 합니다.
{ab,cd} 문자열 집합 {ab, cd}의 문자열과 일치합니다.
{ab,c{de, fh}} 문자열 집합 {ab, cde, cfh}의 문자열과 일치합니다.

read_files 글롭을 사용하여 파일을 검색할 때 Auto Loader의 엄격한 글로버를 사용합니다. useStrictGlobber 옵션에 의해 구성됩니다. 엄격한 글로버가 비활성화되면, 후행 슬래시(/)가 제거되고, 별 패턴(예: /*/)을 사용하여 여러 디렉터리를 발견할 수 있도록 확장됩니다. 동작의 차이를 보려면 아래 예제를 참조하세요.

패턴 파일 경로 Strict globber 사용 안 함 Strict globber 활성화됨
/a/b /a/b/c/file.txt 예 예
/a/b /a/b_dir/c/file.txt 아니요 아니요
/a/b /a/b.txt 아니요 아니요
/a/b/ /a/b.txt 아니요 아니요
/a/*/c/ /a/b/c/file.txt 예 예
/a/*/c/ /a/b/c/d/file.txt 예 예
/a/*/d/ /a/b/c/d/file.txt 예 아니요
/a/*/c/ /a/b/x/y/c/file.txt 예 아니요
/a/*/c /a/b/c_file.txt 예 아니요
/a/*/c/ /a/b/c_file.txt 예 아니요
/a/*/c /a/b/cookie/file.txt 예 아니요
/a/b* /a/b.txt 예 예
/a/b* /a/b/file.txt 예 예
/a/{0.txt,1.txt} /a/0.txt 예 예
/a/*/{0.txt,1.txt} /a/0.txt 아니요 아니요
/a/b/[cde-h]/i/ /a/b/c/i/file.txt 예 예

스키마 유추

read_files 옵션을 사용하여 schema 파일의 스키마를 명시적으로 제공할 수 있습니다. 스키마가 제공되지 않으면 read_files 검색된 파일에서 통합 스키마를 유추하려고 시도하며, LIMIT 문을 사용하지 않는 한 모든 파일을 읽어야 합니다. LIMIT 쿼리를 사용하는 경우에도 데이터의 보다 대표적인 스키마를 반환하기 위해 필요한 것보다 큰 파일 집합을 읽을 수 있습니다. Databricks는 사용자가 제공하지 않은 경우 Notebook 및 SQL 편집기의 쿼리에 대해 LIMIT 문을 자동으로 추가합니다 SELECT.

schemaHints 옵션을 사용하여 유추된 스키마의 하위 집합을 수정할 수 있습니다. 자세한 내용은 스키마 힌트를 사용한 스키마 유추 재정의에 대해 참조하세요.

스키마와 일치하지 않는 모든 데이터를 복구하기 위해 기본적으로 A rescuedDataColumn 가 제공됩니다. 복구된 데이터 열에 대한 자세한 내용은 참조하십시오. 옵션 rescuedDataColumn을 설정하여 schemaEvolutionMode => 'none'를 제거할 수 있습니다.

파티션 스키마 유추

read_files은(는) 파일이 Hive 스타일로 분할된 디렉터리 아래에 저장되는 경우, 즉 분할 열을 유추할 수도 있습니다. schema 제공된 경우 검색된 파티션 열은 schema제공된 형식을 사용합니다. 파티션 열이 제공된 schema속하지 않으면 유추된 파티션 열은 무시됩니다.

파티션 스키마와 데이터 열에 열이 있는 경우 파티션 값에서 읽은 값은 데이터 값 대신 사용됩니다. 디렉터리에서 오는 값을 무시하고 데이터 열을 사용하려는 경우 쉼표로 구분된 목록의 파티션 열 목록에 partitionColumns 옵션을 제공할 수 있습니다.

partitionColumns 옵션을 사용하여 최종 유추 스키마에 포함할 검색된 열을 read_files에게 지시할 수 있습니다. 빈 문자열을 제공하면 모든 파티션 열이 무시됩니다.

schemaHints 옵션을 제공하여 파티션 열에 대해 유추된 스키마를 재정의할 수도 있습니다.

TEXT 및 BINARYFILE 형식에는 고정된 스키마가 있지만 read_files 가능한 경우 이러한 형식에 대한 분할을 유추하려고 시도합니다.

클라우드 스토리지에 대한 인증

read_files 는 Unity 카탈로그 외부 위치 또는 Unity 카탈로그 볼륨(관리 및 외부 모두)에서 파일을 읽습니다. 외부 위치에 대한 권한 또는 READ FILES 읽을 파일이 포함된 볼륨에 대한 권한이 있어야 합니다READ VOLUME. Unity 카탈로그를 사용하여 클라우드 개체 스토리지에 연결 또는 Unity 카탈로그 볼륨이란?을 참조하세요.

스트리밍 테이블의 사용량

read_files 스트리밍 테이블에서 사용하여 Delta Lake로 파일을 수집할 수 있습니다. read_files 스트리밍 테이블 쿼리에서 사용될 때 자동 로더를 활용합니다. STREAM과 함께 read_files 키워드를 사용해야 합니다. 자세한 내용은 자동 로더란?

스트리밍 쿼리에서 사용되는 경우 read_files 데이터 샘플을 사용하여 스키마를 유추하고 더 많은 데이터를 처리할 때 스키마를 발전할 수 있습니다. 자세한 내용은 자동 로더 스키마 유추 및 진화 구성을 참조하세요.

옵션

기본 옵션

옵션 유형 설명 기본값
format String 원본 경로의 데이터 파일 형식입니다. 누락 시 자동 추론. 허용되는 값은 , , binaryFile, (베타), json, textorcparquet그리고 xml다음과 같습니다avro. filecsv 없음
schema String 읽을 파일의 스키마입니다. 예를 'id int, ts timestamp, event string'들어 DDL 형식으로 스키마 문자열을 지정하세요. 생략할 경우, read_files 발견된 파일 전반에 걸쳐 통일된 스키마를 추론 하려는 시도입니다. 없음
inferColumnTypes Boolean 스키마 유추를 활용할 때 정확한 열 형식을 유추할지 여부입니다. 기본적으로 열은 JSON 및 CSV 데이터 세트를 유추할 때 유추됩니다. 이는 자동 로더의 기본 동작과는 반대입니다. 스키 마 추론을 참조하세요. true
partitionColumns String 파일의 디렉터리 구조를 바탕으로 추론할 수 있는 쉼표로 구분된 하이브 스타일 파티션 열의 목록입니다. 하이브 스타일 분할 열은 등호로 결합된 키-값 쌍으로, 예: <base-path>/a=x/b=1/c=y/file.format. 이 예제에서 파티션 열은 a, b그리고 c입니다. 스키마 추론을 사용하고 데이터를 로드하는 데 전달 <base-path> 하면, 이 열들이 자동으로 스키마에 추가됩니다. 스키마를 지정하는 경우 자동 로더는 이러한 열이 스키마에 포함될 것으로 예상합니다. 이 열들을 스키마에 포함시키고 싶지 않다면, 무시하도록 지정 "" 하세요. 이 옵션을 사용하면 복잡한 디렉터리 구조의 파일 경로에서 열을 추론할 수도 있습니다. 예를 들어, 다음 파일들에 대해, 에 대한 반환 year=2022file1.csv을 지정 cloudFiles.partitionColumnsyear,month,day 하지만month, 와 day 열은 null입니다. month 와 day 는 올바르게 file2.csvfile3.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		 없음
schemaHints String 스키마 추론 중에 Auto Loader에 전달하는 스키마 정보입니다. 자세한 내용은 스키마 힌트 참조하세요. 없음
useStrictGlobber Boolean Apache Spark에서 다른 파일 원본의 기본 패턴 매칭 동작과 일치하도록 엄격한 패턴 매칭 기능을 사용할지 여부입니다. 자세한 내용은 일반적인 데이터 로드 패턴을 참조하세요. Databricks Runtime 12.2 LTS 이상에서 지원됩니다. 이것은 자동 로더의 기본 설정과는 반대입니다. true

서식 관련 옵션

각 파일 형식(JSON, CSV, XML, Parquet, Avro, 텍스트, ORC 및 이진)과 관련된 옵션은 DataFrameReader 옵션을 참조하세요.

스트리밍 옵션

이러한 옵션은 read_files 또는 스트리밍 쿼리 내에서 사용할 때 적용됩니다.

옵션 유형 설명 기본값
allowOverwrites Boolean 발견 후 변경된 파일을 재처리할지 여부. 새로고침 시, read_files 마지막 성공적인 갱신 후에 수정된 파일을 재처리합니다. false
includeExistingFiles Boolean 스트림 처리 입력 경로에 기존 파일을 포함할지 아니면 초기 설정 후에 도착하는 새 파일만 처리할지 여부입니다. 이 옵션은 스트림을 처음 시작할 때만 평가됩니다. 스트림을 다시 시작한 후 이 옵션을 변경해도 효과가 없습니다. true
maxBytesPerTrigger Byte String 각 트리거에서 처리할 최대 새로운 바이트 수. 각 마이크로배치를 10GB의 데이터로 제한하도록 10g 같은 바이트 문자열을 지정할 수 있습니다. 이는 소프트 최대값입니다. 각각 3GB인 파일이 있는 경우 Azure Databricks 마이크로배치에서 12GB를 처리합니다. maxFilesPerTrigger 함께 사용하는 경우 Azure Databricks 먼저 도달하는 maxFilesPerTrigger 또는 maxBytesPerTrigger 하한까지 사용합니다. 서버리스 SQL 웨어하우스에서 생성된 스트리밍 테이블의 경우, 동적 접근 제어를 활용하기 위해 이 옵션이나 maxFilesPerTrigger를 설정하지 마세요. 없음
maxFilesPerTrigger Integer 각 트리거에서 처리할 최대 신규 파일 수. maxBytesPerTrigger 함께 사용하는 경우 Azure Databricks 먼저 도달하는 maxFilesPerTrigger 또는 maxBytesPerTrigger 하한까지 사용합니다. 서버리스 SQL 웨어하우스에서 생성된 스트리밍 테이블의 경우, 동적 접근 제어를 활용하기 위해 이 옵션이나 maxBytesPerTrigger를 설정하지 마세요. 1000
schemaEvolutionMode String 데이터에서 새 열이 검색될 때 스키마를 발전시키는 모드입니다. 기본적으로 열은 JSON 데이터 세트를 유추할 때 문자열로 유추됩니다. 자세한 내용은 스키마 진화 참조하세요. 이 옵션은 text 및 binaryFile 파일에 적용되지 않습니다. "addNewColumns" 그렇지 않으면 스키마 "none" 가 없을 것이다.
schemaLocation String 유추된 스키마 및 후속 변경 내용을 저장할 위치입니다. 자세한 내용은 스키마 유추 참조하세요. 스트리밍 테이블 쿼리에서 스키마 위치가 필수는 아닙니다. 없음

예제

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

구조화되지 않은 파일 작업

다음 예제에서는 형식을 사용하여 BINARYFILE Unity 카탈로그 볼륨에 저장된 구조화되지 않은 파일을 읽고 필터링하고 AI 함수와 결합하여 read_files 파일 콘텐츠를 처리합니다.

볼륨의 모든 파일 나열: * EXCEPT (content) 이진 콘텐츠를 로드하지 않고 파일 메타데이터를 반환하고 파일 수준 메타데이터 필드를 포함하도록 명시적으로 선택합니다 _metadata .

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

크기별로 필터링된 이미지 파일 나열: 특정 이미지 파일 형식을 대상으로 지정하고 필터링 fileNamePattern 하여 지정된 크기 범위 내의 파일만 반환하는 데 사용합니다_metadata.file_size.

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;

지난 날 내에 수정된 PDF 파일 나열: PDF 파일을 대상으로 지정하고 필터링 fileNamePattern 하여 지난 날 내에 변경된 파일만 반환하는 데 사용합니다modificationTime.

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;

이미지 파일에서 AI 함수 실행: 클라우드 스토리지 경로에서 읽은 이미지 파일을 처리하는 데 사용합니다 ai_query . _metadata 필드를 필터링하여 특정 파일을 대상으로 지정합니다.

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%';

파일 이름 패턴과 일치하는 문서 구문 분석: PDF 및 이미지에서 구조화된 콘텐츠를 추출하는 데 사용합니다 ai_parse_document . _metadata.file_name 특정 파일을 대상으로 필터링합니다.

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%';

구조화된 테이블을 사용하여 파일 조인: 구조화되지 않은 워크플로에서는 테이블에 저장된 구조화된 데이터를 구조화되지 않은 파일과 병합해야 하는 경우가 많습니다. 다음 예제에서는 파일 크기 및 사용자 특성별로 필터링하여 두 개의 구조적 테이블을 사용하여 클라우드 스토리지 경로의 파일을 조인합니다. 조 user_files 인은 다음을 사용하여 split 파일 경로에서 파일 ID를 추출하여 수행됩니다 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;
  • Last updated on