read_files 테이블 반환 함수

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

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

읽기JSON, , CSV, XML, TEXTBINARYFILE, PARQUETAVRO및 ORC 파일 형식을 지원합니다. 파일 형식을 자동으로 검색하고 모든 파일에서 통합 스키마를 유추할 수 있습니다.

구문

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

인수

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

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

반품

지정된 path아래에 읽은 파일의 데이터로 구성된 테이블입니다.

파일 검색

read_files 는 제공된 디렉터리에서 개별 파일을 읽거나 파일을 읽을 수 있습니다. read_files는 특정 디렉터리 패턴으로 재귀하도록 지시 read_files 하는 glob가 제공되지 않는 한 제공된 디렉터리 아래의 모든 파일을 재귀적으로 검색합니다.

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 globs를 사용하여 파일을 검색할 때 자동 로더의 엄격한 globber를 사용합니다. 옵션에 의해 구성됩니다 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	예	예

스키마 유추

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

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

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

파티션 스키마 유추

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

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

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

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

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

스트리밍 테이블의 사용량

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

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

옵션

• 기본 옵션
• 일반 옵션
• JSON 옵션
• CSV 옵션
• XML 옵션
• PARQUET 옵션
• AVRO 옵션
• BINARYFILE 옵션
• TEXT 옵션
• ORC 옵션
• 스트리밍 옵션

기본 옵션

옵션
format 유형: String 원본 경로의 데이터 파일 형식입니다. 제공되지 않은 경우 자동 유추됩니다. 허용되는 값은 다음과 같습니다. - avro: Avro 파일 - binaryFile: 이진 파일 - csv: CSV 파일 읽기 - json: JSON 파일 - orc: ORC 파일 - parquet: Azure Databricks로 Parquet 파일 읽기 - text: 텍스트 파일 - xml: XML 파일 읽기 및 쓰기 기본값: 없음
inferColumnTypes 유형: Boolean 스키마 유추를 활용할 때 정확한 열 형식을 유추할지 여부입니다. 기본적으로 열은 JSON 및 CSV 데이터 세트를 유추할 때 유추됩니다. 자세한 내용은 스키마 유추를 참조하세요. 이는 자동 로더의 기본값과 반대입니다. 기본값: true
partitionColumns 유형: String 파일의 디렉터리 구조에서 유추하려는 Hive 스타일 파티션 열의 쉼표로 구분된 목록입니다. Hive 스타일 파티션 열은 같은 같음 기호와 결합된 키-값 쌍입니다. <base-path>/a=x/b=1/c=y/file.format. 이 예에서 파티션 열은 a, b 및 c입니다. 기본적으로 이러한 열은 스키마 유추를 사용하고 데이터를 로드할 <base-path>를 제공하는 경우 스키마에 자동으로 추가됩니다. 스키마를 제공하면 자동 로더는 이러한 열이 스키마에 포함될 것으로 예상합니다. 이러한 열을 스키마의 일부로 사용하지 않으려면 ""를 지정하여 이러한 열을 무시할 수 있습니다. 또한 아래 예와 같이 복잡한 디렉터리 구조에서 열이 파일 경로로 유추되기를 원할 때 이 옵션을 사용할 수 있습니다. <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 cloudFiles.partitionColumns를 year,month,day로 지정하면 반환됩니다. file1.csv는 year=2022이지만 month 및 day 열은 null입니다. month 및 day는 file2.csv 및 file3.csv에 대해 올바르게 구문 분석됩니다. 기본값: 없음
schemaHints 유형: String 스키마 유추 중에 자동 로더에 제공하는 스키마 정보입니다. 자세한 내용은 스키마 힌트를 참조하세요. 기본값: 없음
useStrictGlobber 유형: Boolean Apache Spark에서 다른 파일 원본의 기본 와일드카드 사용 동작과 일치하는 엄격한 globber(글로버)를 사용할지 여부입니다. 자세한 내용은 일반적인 데이터 로드 패턴을 참조하세요. Databricks Runtime 12.2 LTS 이상에서 지원됩니다. 자동 로더의 기본값과는 반대입니다. 기본값: true

일반 옵션

다음 옵션은 모든 파일 형식에 적용됩니다.

옵션
ignoreCorruptFiles 유형: Boolean 손상된 파일을 무시할지 여부를 나타냅니다. true인 경우 손상된 파일이 발견될 때 Spark 작업이 계속 실행되고 읽은 내용이 계속 반환됩니다. numSkippedCorruptFiles로 관찰 가능 Delta Lake 기록의 operationMetrics 열. Databricks Runtime 11.3 LTS 이상에서 지원됩니다. 기본값: false
ignoreMissingFiles 유형: Boolean 누락된 파일을 무시할지 여부를 나타냅니다. true인 경우 누락된 파일이 있는 경우 Spark 작업이 계속 실행되고 읽은 내용이 계속 반환됩니다. Databricks Runtime 11.3 LTS 이상에서 지원됩니다. 기본값: false(COPY INTO의 경우 true)
modifiedAfter 형식: Timestamp String(예: 2021-01-01 00:00:00.000000 UTC+0) 제공된 타임스탬프 다음에 수정 타임스탬프가 있는 파일을 수집하는 선택적 타임스탬프입니다. 기본값: 없음
modifiedBefore 형식: Timestamp String(예: 2021-01-01 00:00:00.000000 UTC+0) 제공된 타임스탬프 이전의 수정 타임스탬프가 있는 파일을 수집하기 위한 선택적 타임스탬프입니다. 기본값: 없음
pathGlobFilter 또는 fileNamePattern 유형: String 파일 선택을 위해 제공할 잠재적인 glob 패턴입니다. 다음과 동일합니다: COPY INTO의 PATTERN. fileNamePattern은 read_files에서 사용할 수 있습니다. 기본값: 없음
recursiveFileLookup 유형: Boolean 스키마 유추 중에 파티션 유추를 건너뛸지 여부입니다. 로드되는 파일에는 영향을 주지 않습니다. 기본값: false

JSON 옵션

옵션
allowBackslashEscapingAnyCharacter 유형: Boolean 백래시가 성공하는 모든 문자를 이스케이프할 수 있도록 허용할지 여부입니다. 사용하도록 설정하지 않으면 JSON 사양에 의해 명시적으로 나열된 문자만 이스케이프할 수 있습니다. 기본값: false
allowComments 유형: Boolean 구문 분석된 콘텐츠 내에서 Java, C, C++ 스타일 주석('/', '*' 및 '//' 변형)을 사용하도록 허용할지 여부입니다. 기본값: false
allowNonNumericNumbers 유형: Boolean 숫자가 아닌(NaN) 토큰 집합을 유효한 부동 숫자 값으로 허용할지 여부입니다. 기본값: true
allowNumericLeadingZeros 유형: Boolean 정수를 추가(무시할 수 있는) 0으로 시작할 수 있는지 여부(예: 000001)입니다. 기본값: false
allowSingleQuotes 유형: Boolean 작은따옴표(아포스트로피, 문자 '\')를 따옴표 문자열(이름 및 문자열 값)에 사용하도록 허용할지 여부입니다. 기본값: true
allowUnquotedControlChars 유형: Boolean JSON 문자열에 캡슐화되지 않은 컨트롤 문자(탭 및 줄 바꿈 문자를 포함하여 값이 32보다 작은 ASCII 문자)를 포함하도록 허용할지 여부입니다. 기본값: false
allowUnquotedFieldNames 유형: Boolean 따옴표가 지정되지 않은 필드 이름(JavaScript에서 허용되지만 JSON 사양에서는 허용되지 않음)의 사용을 허용할지 여부입니다. 기본값: false
badRecordsPath 유형: String 잘못된 JSON 레코드에 대한 정보를 기록하기 위한 파일을 저장하는 경로입니다. 기본값: 없음
columnNameOfCorruptRecord 유형: String 형식이 잘못되어 구문을 분석할 수 없는 레코드를 저장하기 위한 열입니다. 구문 분석에 대한 mode가 DROPMALFORMED로 설정되면 이 열은 비어 있습니다. 기본값: _corrupt_record
dateFormat 유형: String 날짜 문자열을 구문 분석하기 위한 형식입니다. 기본값: yyyy-MM-dd
dropFieldIfAllNull 유형: Boolean 스키마 유추 중에 모든 Null 값 또는 빈 배열 및 구조체의 열을 무시할지 여부입니다. 기본값: false
encoding 또는 charset 유형: String JSON 파일 인코딩의 이름입니다. 옵션 목록은 java.nio.charset.Charset을 참조하세요. multiline이 true이면 UTF-16 및 UTF-32를 사용할 수 없습니다. 기본값: UTF-8
inferTimestamp 유형: Boolean 타임스탬프 문자열을 TimestampType으로 유추할지 여부입니다. 다음으로 설정된 경우 - true: 스키마 추론이 눈에 띄게 오래 걸릴 수 있습니다. 자동 로더와 함께 사용하려면 cloudFiles.inferColumnTypes를 설정해야 합니다. 기본값: false
lineSep 유형: String 연속된 두 JSON 레코드 사이의 문자열입니다. 기본값: 없음(\r, \r\n, \n 포함)
locale 유형: String java.util.Locale 식별자입니다. JSON 내의 기본 날짜, 타임스탬프, 10진수 구문 분석에 영향을 줍니다. 기본값: US
mode 유형: String 잘못된 형식의 레코드를 처리하는 파서 모드입니다. 다음 중 하나입니다. 'PERMISSIVE' 'DROPMALFORMED' 또는 'FAILFAST'입니다. 기본값: PERMISSIVE
multiLine 유형: Boolean JSON 레코드가 여러 줄에 걸쳐 있는지 여부입니다. 기본값: false
prefersDecimal 유형: Boolean 가능하면 문자열 DecimalType 을 float 또는 double 형식 대신 유추하려고 시도합니다. 또한 다음을 활성화해서 스키마 유추를 사용해야 합니다: inferSchema를 활성화하거나 자동 로더에서 cloudFiles.inferColumnTypes 사용. 기본값: false
primitivesAsString 유형: Boolean 숫자 및 부울과 같은 기본 형식을 StringType으로 유추할지 여부입니다. 기본값: false
readerCaseSensitive 유형: Boolean rescuedDataColumn이 활성화된 경우 대/소문자 구분 동작을 지정합니다. true이면 스키마와 대/소문자를 구분하여 이름이 다른 데이터 열을 구합니다. 그렇지 않으면 대/소문자를 구분하지 않는 방식으로 데이터를 읽습니다. Databricks Runtime에서 사용 가능합니다. 13.3 이상. 기본값: true
rescuedDataColumn 유형: String 데이터 형식 불일치 또는 스키마 불일치(열 대/소문자 포함)로 인해 구문 분석할 수 없는 모든 데이터를 별도의 열에 수집할지 여부입니다. 이 열은 자동 로더를 사용할 때 기본적으로 포함됩니다. 자세한 내용은 복구된 데이터 열이란?을 참조하세요. 기본값: 없음
singleVariantColumn 유형: String 주어진 문자열을 열 이름으로 하여 전체 JSON 문서를 단일 Variant 열로 파싱하여 수집할지 여부입니다. 비활성화된 경우 JSON 필드가 각각의 열로 수집됩니다. 기본값: 없음
timestampFormat 유형: String 타임스탬프 문자열 구문 분석 형식입니다. 기본값: yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]
timeZone 유형: String 타임스탬프와 날짜를 구문 분석할 때 사용할 java.time.ZoneId입니다. 기본값: 없음

CSV 옵션

옵션
badRecordsPath 유형: String 잘못된 CSV 레코드에 대한 정보를 기록하기 위한 파일을 저장하는 경로입니다. 기본값: 없음
charToEscapeQuoteEscaping 유형: Char 따옴표를 이스케이프하는 데 사용되는 문자를 이스케이프하는 데 사용되는 문자입니다. 예를 들어 [ " a\\", b ] 레코드의 경우 다음과 같습니다. - '\'를 이스케이프할 문자가 정의되지 않으면 레코드가 구문 분석되지 않습니다. 파서에서 [a],[\],["],[,],[ ],[b] 문자를 읽고 닫는 따옴표를 찾을 수 없으므로 오류를 throw합니다. - '\'를 이스케이프할 문자가 '\'로 정의되면 레코드가 [a\] 및 [b]의 2개의 값으로 읽힙니다. 기본값: '\0'
columnNameOfCorruptRecord > [!참고] >> 자동 로더에서 지원됩니다. COPY INTO에서 지원되지 않습니다. 유형: String 형식이 잘못되어 구문을 분석할 수 없는 레코드를 저장하기 위한 열입니다. 구문 분석에 대한 mode가 DROPMALFORMED로 설정되면 이 열은 비어 있습니다. 기본값: _corrupt_record
comment 유형: Char 텍스트 줄의 시작 부분에 있는 줄 주석을 나타내는 문자를 정의합니다. 주석 건너뛰기를 사용하지 않도록 설정하려면 '\0'을 사용합니다. 기본값: '\u0000'
dateFormat 유형: String 날짜 문자열을 구문 분석하기 위한 형식입니다. 기본값: yyyy-MM-dd
emptyValue 유형: String 빈 값의 문자열 표현입니다. 기본값: ""
encoding 또는 charset 유형: String CSV 파일 인코딩 이름입니다. 옵션 목록은 java.nio.charset.Charset을 참조하세요. multiline이 true이면 UTF-16 및 UTF-32를 사용할 수 없습니다. 기본값: UTF-8
enforceSchema 유형: Boolean 지정된 스키마 또는 유추된 스키마를 CSV 파일에 강제로 적용할지 여부입니다. 옵션을 사용하도록 설정하면 CSV 파일의 머리글이 무시됩니다. 이 옵션은 자동 로더를 사용하여 데이터를 복구하고 스키마 개선을 허용하는 경우 기본값으로 무시됩니다. 기본값: true
escape 유형: Char 데이터를 구문 분석할 때 사용할 이스케이프 문자입니다. 기본값: '\'
header 유형: Boolean CSV 파일에 머리글이 포함되어 있는지 여부입니다. 자동 로더는 스키마를 유추할 때 파일에 머리글이 있다고 가정합니다. 기본값: false
ignoreLeadingWhiteSpace 유형: Boolean 구문 분석된 각 값의 선행 공백을 무시할지 여부입니다. 기본값: false
ignoreTrailingWhiteSpace 유형: Boolean 구문 분석된 각 값의 후행 공백을 무시할지 여부입니다. 기본값: false
inferSchema 유형: Boolean 구문 분석된 CSV 레코드의 데이터 형식을 유추할지 아니면 모든 열이 StringType이라고 가정할지 여부입니다. true로 설정되면 데이터를 추가로 전달해야 합니다. 자동 로더의 경우 cloudFiles.inferColumnTypes를 대신 사용합니다. 기본값: false
lineSep 유형: String 연속된 두 CSV 레코드 사이의 문자열입니다. 기본값: 없음(\r, \r\n, \n 포함)
locale 유형: String java.util.Locale 식별자입니다. CSV 내에서 기본 날짜, 타임스탬프, 10진수 구문 분석에 영향을 미칩니다. 기본값: US
maxCharsPerColumn 유형: Int 값에서 구문 분석할 최대 문자 수입니다. 메모리 오류를 방지하는 데 사용할 수 있습니다. 기본값은 -1이며 무제한을 의미합니다. 기본값: -1
maxColumns 유형: Int 레코드에 사용할 수 있는 열 수에 대한 하드 한도입니다. 기본값: 20480
mergeSchema 유형: Boolean 여러 파일에서 스키마를 유추하고 각 파일의 스키마를 병합할지 여부입니다. 스키마를 유추할 때 자동 로더에 대해 기본적으로 사용하도록 설정됩니다. 기본값: false
mode 유형: String 잘못된 형식의 레코드를 처리하는 파서 모드입니다. 다음 중 하나입니다. 'PERMISSIVE' 'DROPMALFORMED' 및 'FAILFAST'. 기본값: PERMISSIVE
multiLine 유형: Boolean CSV 레코드가 여러 줄에 걸쳐 있는지 여부입니다. 기본값: false
nanValue 유형: String FloatType 및 DoubleType 열을 구문 분석할 때 숫자가 아닌 값에 대한 문자열 표현입니다. 기본값: "NaN"
negativeInf 유형: String FloatType 또는 DoubleType 열을 구문 분석할 때 음의 무한대에 대한 문자열 표현입니다. 기본값: "-Inf"
nullValue 유형: String Null 값의 문자열 표현입니다. 기본값: ""
parserCaseSensitive(더 이상 사용되지 않음) 유형: Boolean 파일을 읽는 동안 머리글에 선언된 열을 스키마 대/소문자를 구분하여 정렬할지 여부를 결정합니다. 자동 로더의 경우 기본적으로 true입니다. 사용하도록 설정되면 대/소문자가 다른 열이 rescuedDataColumn에서 복구됩니다. readerCaseSensitive를 위하여 이 옵션은 더 이상 사용되지 않습니다. 기본값: false
positiveInf 유형: String FloatType 또는 DoubleType 열을 구문 분석할 때 양의 무한대에 대한 문자열 표현입니다. 기본값: "Inf"
preferDate 유형: Boolean 가능한 경우 문자열을 타임스탬프 대신 날짜로 유추하려고 시도합니다. 또한 스키마 추론을 사용해야 하며, inferSchema를 활성화하거나 자동 로더에서 cloudFiles.inferColumnTypes를 사용해야 합니다. 기본값: true
quote 유형: Char 필드 구분 기호가 값의 일부인 값을 이스케이프하는 데 사용되는 문자입니다. 기본값: "
readerCaseSensitive 유형: Boolean rescuedDataColumn이 활성화된 경우 대/소문자 구분 동작을 지정합니다. true이면 스키마와 대/소문자를 구분하여 이름이 다른 데이터 열을 구합니다. 그렇지 않으면 대/소문자를 구분하지 않는 방식으로 데이터를 읽습니다. 기본값: true
rescuedDataColumn 유형: String 데이터 형식 불일치 및 스키마 불일치(열 대/소문자 포함)로 인해 구문 분석할 수 없는 모든 데이터를 별도의 열에 수집할지 여부입니다. 이 열은 자동 로더를 사용할 때 기본적으로 포함됩니다. 자세한 내용은 복구된 데이터 열이란?을 참조하세요. 기본값: 없음
sep 또는 delimiter 유형: String 열 간 구분 기호 문자열입니다. 기본값: ","
skipRows 유형: Int 무시해야 하는 CSV 파일 시작 부분의 행 수입니다(주석이 추가된 행과 빈 행 포함). header가 true이면 헤더는 건너뛰지 않고 주석 처리되지 않은 첫 번째 행이 됩니다. 기본값: 0
timestampFormat 유형: String 타임스탬프 문자열 구문 분석 형식입니다. 기본값: yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]
timeZone 유형: String 타임스탬프와 날짜를 구문 분석할 때 사용할 java.time.ZoneId입니다. 기본값: 없음
unescapedQuoteHandling 유형: String 이스케이프되지 않은 따옴표를 처리하기 위한 전략입니다. 허용되는 옵션은 다음과 같습니다. - STOP_AT_CLOSING_QUOTE: 이스케이프되지 않은 따옴표가 입력에 있는 경우 닫는 따옴표를 찾을 때까지 따옴표 문자를 누적하고 값을 따옴표로 묶은 값으로 구문 분석합니다. - BACK_TO_DELIMITER: 이스케이프되지 않은 따옴표가 입력에 있는 경우 값을 따옴표가 없는 값으로 간주합니다. 이렇게 하면 sep에 정의된 구분 기호를 찾을 때까지 파서에서 현재 구문 분석된 값의 모든 문자를 누적합니다. 값에 구분 기호가 없으면 구분 기호 또는 줄 끝을 찾을 때까지 파서에서 입력으로부터 문자를 계속 누적합니다. - STOP_AT_DELIMITER: 이스케이프되지 않은 따옴표가 입력에 있는 경우 값을 따옴표가 없는 값으로 간주합니다. 이렇게 하면 입력에서 sep에 정의된 구분 기호 또는 줄 끝을 찾을 때까지 파서에서 모든 문자를 누적합니다. - SKIP_VALUE: 이스케이프되지 않은 따옴표가 입력에 있는 경우 지정된 값에 대해 구문 분석된 내용을 건너뛰고(다음 구분 기호를 찾을 때까지) nullValue에 설정된 값이 대신 생성됩니다. - RAISE_ERROR: 이스케이프되지 않은 따옴표가 입력에 있는 경우 TextParsingException이 throw됩니다. 기본값: STOP_AT_DELIMITER

XML 옵션

옵션	설명	범위
rowTag	행으로 처리할 XML 파일의 행 태그입니다. 예를 들어, XML이 <books> <book><book>...<books> 형태라면, 적절한 값은 book입니다. 필수 옵션입니다.	read
samplingRatio	스키마 유추에 사용되는 행의 비율을 정의합니다. XML 기본 제공 함수는 이 옵션을 무시합니다. 기본값: 1.0.	read
excludeAttribute	요소의 특성을 제외할지 여부입니다. 기본값: false.	read
mode	구문 분석 중 손상된 레코드를 처리하는 모드. PERMISSIVE: 손상된 레코드의 경우 잘못된 문자열을 columnNameOfCorruptRecord로 설정된 필드에 넣고 잘못된 필드들을 null로 설정합니다. 손상된 레코드를 유지하려면 사용자 정의 스키마에서 string 타입의 columnNameOfCorruptRecord라는 필드를 설정할 수 있습니다. 스키마에 필드가 없으면 구문 분석 중에 손상된 레코드를 삭제합니다. 스키마를 유추할 때 파서가 출력 스키마에 columnNameOfCorruptRecord 필드를 암시적으로 추가합니다. DROPMALFORMED: 손상된 레코드를 무시합니다. 이 모드는 XML 기본 제공 함수에 대해 지원되지 않습니다. FAILFAST: 파서가 손상된 레코드를 만나면 예외를 발생시킵니다.	read
inferSchema	true인 경우 각 결과 DataFrame 열에 대해 적절한 유형을 유추하려고 시도합니다. false인 경우 모든 결과 열은 string 유형입니다. 기본값: true. XML 기본 제공 함수는 이 옵션을 무시합니다.	read
columnNameOfCorruptRecord	다음 모드에서 생성된 잘못된 문자열을 포함하는 새로운 필드의 이름을 변경할 수 있습니다: PERMISSIVE 모드. 기본값: spark.sql.columnNameOfCorruptRecord.	read
attributePrefix	특성과 요소를 구별하기 위한 특성의 접두사. 이는 필드 이름의 접두사입니다. 기본값은 _입니다. XML을 읽는 경우 비워 둘 수 있지만 쓰기에는 비워 둘 수 없습니다.	읽기, 쓰기
valueTag	특성 또는 자식 요소도 있는 요소 내의 문자 데이터에 사용되는 태그입니다. 사용자는 스키마에서 valueTag 필드를 지정할 수 있습니다. 또는 문자 데이터가 다른 요소 또는 특성이 있는 요소에 있을 때 스키마 유추 중에 자동으로 추가됩니다. 기본값: _VALUE	읽기, 쓰기
encoding	읽기를 위해 지정된 인코딩 형식으로 XML 파일을 디코드합니다. 쓰기의 경우 저장된 XML 파일의 인코딩(charset)을 지정합니다. XML 기본 제공 함수는 이 옵션을 무시합니다. 기본값: UTF-8.	읽기, 쓰기
ignoreSurroundingSpaces	읽는 값의 주변 공백을 건너뛸지 여부를 정의합니다. 기본값: true. 공백 전용 문자 데이터는 무시됩니다.	read
rowValidationXSDPath	각 행을 개별적으로 검증하기 위해 사용되는 선택적 XSD 파일의 경로입니다. 유효성 검사에 실패한 행은 위와 같이 구문 분석 오류로 처리됩니다. XSD는 제공되거나 유추된 스키마에 달리 영향을 미치지 않습니다.	read
ignoreNamespace	true인 경우 XML 요소 및 특성에 대한 네임스페이스의 접두사는 무시됩니다. 예를 들어 <abc:author> 태그와 <def:author> 태그는 둘 다 <author>로 처리됩니다. 네임스페이스는 rowTag 요소에서 무시할 수 없으며 해당 읽기 자식만 무시할 수 있습니다. XML 파싱은 false여도 네임스페이스를 인식하지 않습니다. 기본값: false.	read
timestampFormat	날짜/시간 형식 패턴을 따르는 사용자 지정 타임스탬프 형식 문자열입니다. 이는 timestamp 형식에 적용됩니다. 기본값: yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX].	읽기, 쓰기
timestampNTZFormat	시간대 없이 타임스탬프를 나타내는 사용자 지정 형식 문자열로 날짜/시간 형식 패턴을 따릅니다. 이는 TimestampNTZType 유형에 적용됩니다. 기본값: yyyy-MM-dd'T'HH:mm:ss[.SSS]	읽기, 쓰기
dateFormat	날짜/시간 형식 패턴을 따르는 사용자 지정 날짜 형식 문자열입니다. 이는 날짜 형식에 적용됩니다. 기본값: yyyy-MM-dd.	읽기, 쓰기
locale	로캘을 IETF BCP 47 형식의 언어 태그로 설정합니다. 예를 들어 날짜 및 타임스탬프를 피싱할 때 locale을 사용합니다. 기본값: en-US.	read
rootTag	XML 파일의 루트 태그입니다. 예를 들어 <books> <book><book>...</books>에서 적절한 값은 books입니다. books foo="bar"와 같은 값을 지정하여 기본 특성을 포함할 수 있습니다. 기본값: ROWS.	쓰기
declaration	모든 출력 XML 파일에서 rootTag 앞에 쓸 XML 선언의 내용입니다. 예를 들어 foo 값을 설정하면 <?xml foo?>가 작성됩니다. 비어 있는 문자열로 설정하여 억제할 수 있습니다. 기본값: version="1.0" encoding="UTF-8" standalone="yes".	쓰기
arrayElementName	배열 값을 가진 열의 각 요소를 쓸 때 둘러싸는 XML 요소의 이름입니다. 기본값: item.	쓰기
nullValue	Null 값의 문자열 표현을 설정합니다. 기본값: String null. 이 값이 null인 경우 필드의 특성 및 요소를 쓰지 않습니다.	읽기, 쓰기
compression	파일에 저장할 때 사용할 압축 코드입니다. 이는 대소문자를 구분하지 않는 none, bzip2, gzip, lz4, snappy, deflate). XML 기본 제공 함수는 이 옵션을 무시합니다. 기본값: none.	쓰기
validateName	true인 경우 XML 요소 이름 유효성 검사 실패에 대한 오류가 발생합니다. 예를 들어 SQL 필드 이름에는 공백이 있을 수 있지만 XML 요소 이름에는 공백이 있을 수 없습니다. 기본값: true.	쓰기
readerCaseSensitive	rescuedDataColumn이 활성화된 경우 대소문자 구분 동작을 지정합니다. true이면 스키마와 대/소문자를 구분하여 이름이 다른 데이터 열을 구합니다. 그렇지 않으면 대/소문자를 구분하지 않는 방식으로 데이터를 읽습니다. 기본값: true.	read
rescuedDataColumn	데이터 유형 불일치 및 스키마 불일치(열 대소문자 포함)로 인해 파싱할 수 없는 모든 데이터를 별도의 열로 수집할지 여부입니다. 이 열은 자동 로더를 사용할 때 기본적으로 포함됩니다. 자세한 내용은 복구된 데이터 열(Rescued Data Column)이란?을 참조하세요. 기본값: None.	read

PARQUET 옵션

옵션
datetimeRebaseMode 유형: String 율리우스력과 그레고리력 사이의 날짜 및 타임스탬프 값 기준 다시 지정을 제어합니다. 허용되는 값: EXCEPTION, LEGACY 및 CORRECTED. 기본값: LEGACY
int96RebaseMode 유형: String 율리우스력과 그레고리력 사이의 INT96 타임스탬프 값 기준 다시 지정을 제어합니다. 허용되는 값: EXCEPTION, LEGACY 및 CORRECTED. 기본값: LEGACY
mergeSchema 유형: Boolean 여러 파일에서 스키마를 유추하고 각 파일의 스키마를 병합할지 여부입니다. 기본값: false
readerCaseSensitive 유형: Boolean rescuedDataColumn이 활성화된 경우 대/소문자 구분 동작을 지정합니다. true이면 스키마와 대/소문자를 구분하여 이름이 다른 데이터 열을 구합니다. 그렇지 않으면 대/소문자를 구분하지 않는 방식으로 데이터를 읽습니다. 기본값: true
rescuedDataColumn 유형: String 데이터 형식 불일치 및 스키마 불일치(열 대/소문자 포함)로 인해 구문 분석할 수 없는 모든 데이터를 별도의 열에 수집할지 여부입니다. 이 열은 자동 로더를 사용할 때 기본적으로 포함됩니다. 자세한 내용은 복구된 데이터 열이란?을 참조하세요. 기본값: 없음

AVRO 옵션

옵션
avroSchema 유형: String 사용자가 Avro 형식으로 제공하는 선택적 스키마입니다. Avro를 읽을 때 이 옵션은 실제 Avro 스키마와 호환되지만 다른 개선된 스키마로 설정할 수 있습니다. 역직렬화 스키마는 개선된 스키마와 일치합니다. 예를 들어 기본값이 있는 하나의 추가 열을 포함하는 개선된 스키마를 설정하는 경우 읽기 결과에도 새 열이 포함됩니다. 기본값: 없음
datetimeRebaseMode 유형: String 율리우스력과 그레고리력 사이의 날짜 및 타임스탬프 값 기준 다시 지정을 제어합니다. 허용되는 값: EXCEPTION, LEGACY 및 CORRECTED. 기본값: LEGACY
mergeSchema 유형: Boolean 여러 파일에서 스키마를 유추하고 각 파일의 스키마를 병합할지 여부입니다. Avro에 대한 mergeSchema는 데이터 형식을 완화하지 않습니다. 기본값: false
readerCaseSensitive 유형: Boolean rescuedDataColumn이 활성화된 경우 대/소문자 구분 동작을 지정합니다. true이면 스키마와 대/소문자를 구분하여 이름이 다른 데이터 열을 구합니다. 그렇지 않으면 대/소문자를 구분하지 않는 방식으로 데이터를 읽습니다. 기본값: true
rescuedDataColumn 유형: String 데이터 형식 불일치 및 스키마 불일치(열 대/소문자 포함)로 인해 구문 분석할 수 없는 모든 데이터를 별도의 열에 수집할지 여부입니다. 이 열은 자동 로더를 사용할 때 기본적으로 포함됩니다. 자세한 내용은 복구된 데이터 열이란?을 참조하세요. 기본값: 없음

BINARYFILE 옵션

이진 파일에는 추가 구성 옵션이 없습니다.

TEXT 옵션

옵션
encoding 유형: String 텍스트 파일의 인코딩 이름입니다. 옵션 목록은 java.nio.charset.Charset을 참조하세요. 기본값: UTF-8
lineSep 유형: String 연속된 두 텍스트 레코드 사이의 문자열입니다. 기본값: 없음(\r, \r\n, \n 포함)
wholeText 유형: Boolean 파일을 단일 레코드로 읽을지 여부입니다. 기본값: false

ORC 옵션

옵션
mergeSchema 유형: Boolean 여러 파일에서 스키마를 유추하고 각 파일의 스키마를 병합할지 여부입니다. 기본값: false

스트리밍 옵션

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

옵션
allowOverwrites 유형: Boolean 검색 후 수정된 파일을 다시 처리할지 여부입니다. 마지막으로 성공한 새로 고침 쿼리 시작 시간 이후 수정된 경우 새로 고침 중에 사용 가능한 최신 버전의 파일이 처리됩니다. 기본값: false
includeExistingFiles 유형: Boolean 스트림 처리 입력 경로에 기존 파일을 포함할지 아니면 초기 설정 후에 도착하는 새 파일만 처리할지 여부입니다. 이 옵션은 스트림을 처음 시작할 때만 평가됩니다. 스트림을 다시 시작한 후 이 옵션을 변경해도 효과가 없습니다. 기본값: true
maxBytesPerTrigger 유형: Byte String 모든 트리거에서 처리할 새 바이트의 최대 수입니다. 10g와 같은 바이트 문자열을 지정하여 각 마이크로 일괄 처리를 10GB의 데이터로 제한할 수 있습니다. 이는 소프트 최댓값입니다. 각각 3GB인 파일이 있는 경우 Azure Databricks는 마이크로 일괄 처리에서 12GB를 처리합니다. maxFilesPerTrigger와 함께 사용하면 Azure Databricks는 maxFilesPerTrigger 또는 maxBytesPerTrigger 중 먼저 도달하는 하한까지 소비합니다. 참고: 서버리스 SQL 웨어하우스에서 만든 스트리밍 테이블의 경우 이 옵션은 maxFilesPerTrigger 워크로드 크기 및 서버리스 컴퓨팅 리소스에 따라 확장되는 동적 허용 제어를 활용하여 최상의 대기 시간과 성능을 제공하도록 설정해서는 안 됩니다. 기본값: 없음
maxFilesPerTrigger 유형: Integer 모든 트리거에서 처리할 새 파일의 최대 수입니다. maxBytesPerTrigger와 함께 사용하면 Azure Databricks는 maxFilesPerTrigger 또는 maxBytesPerTrigger 중 먼저 도달하는 하한까지 소비합니다. 참고: 서버리스 SQL 웨어하우스에서 만든 스트리밍 테이블의 경우 이 옵션은 maxBytesPerTrigger 워크로드 크기 및 서버리스 컴퓨팅 리소스에 따라 확장되는 동적 허용 제어를 활용하여 최상의 대기 시간과 성능을 제공하도록 설정해서는 안 됩니다. 기본값: 1000
schemaEvolutionMode 유형: String 데이터에서 새 열이 발견될 때 스키마를 발전시키는 모드입니다. 기본적으로 열은 JSON 데이터 세트를 유추할 때 문자열로 유추됩니다. 자세한 내용은 스키마 진화를 참조하세요. 이 옵션은 파일 및 binaryFile 파일에 적용되지 text 않습니다. 기본값: 스키마가 제공되지 않은 경우 "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);

관련된 문서

• 스트리밍 테이블 생성하기
• read_kafka 테이블 반환 함수