read_files 테이블 값 반환 함수

적용 대상: Databricks SQL Databricks Runtime 13.3 LTS 이상

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

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

구문

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 * 않으며 명시적으로 선택해야 합니다. 여기에는 다음 필드가 포함됩니다.

결과에 포함 _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 패턴을 사용하여 디렉터리 및 파일을 필터링할 수 있습니다.

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

스키마 유추

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 VOLUME 읽을 파일이 포함된 볼륨에 대한 권한이 있어야 합니다READ FILES. Unity 카탈로그를 사용하여 클라우드 개체 스토리지에 연결 또는 Unity 카탈로그 볼륨이란?을 참조하세요.

스트리밍 테이블의 사용량

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

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

옵션

• 기본 옵션
• 서식 관련 옵션
• 스트리밍 옵션

기본 옵션

서식 관련 옵션

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

스트리밍 옵션

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

예제

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

관련된 문서

• CREATE STREAMING TABLE
• read_kafka 테이블 값 반환 함수