Share via

read_files テーブル値関数

  • [アーティクル]

適用対象:check marked yes Databricks SQL Databricks Runtime 13.3 LTS 以降

指定された場所にあるファイルを読み取り、表形式でデータを返します。

JSON、CSV、XML、TEXT、BINARYFILE、PARQUET、AVRO、および ORC ファイル形式の読み取りをサポートします。 ファイル形式を自動的に検出し、すべてのファイルで統合スキーマを推論できます。

構文

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

引数

この関数には、オプション キーの名前付きパラメーター呼び出しが必要です。

  • path: データの場所の URI を持つ STRING。 Azure Data Lake Storage Gen2 ('abfss://')、S3 (s3://)、Google Cloud Storage ('gs://') からの読み取りをサポートします。 glob を含めることができます。 詳細については、「ファイルの検出」を参照してください。
  • option_key: 構成するオプションの名前。 ドット (.) を含むオプションには、バッククウォート (`) を使用する必要があります。
  • option_value: オプションを設定する定数式。 リテラルとスカラー関数を受け入れます。

返品

指定された path の下で読み取られたファイルのデータで構成されるテーブル。

ファイルの検出

read_files では、個々のファイルを読み取ったり、指定されたディレクトリの下にあるファイルを読み取ったりできます。 read_files は、glob が指定されていない限り、指定されたディレクトリ内のすべてのファイルを再帰的に検出します。これは、read_files を特定のディレクトリ パターンに再帰するように指示します。

glob パターンを使用したディレクトリまたはファイルのフィルター処理

glob パターンは、パスに指定されているときに、ディレクトリとファイルのフィルター処理に使用できます。

Pattern 説明
? 任意の 1 文字と一致します
* 0 個以上の文字と一致します
[abc] 文字セット {a, b, c} の 1 文字と一致します。
[a-z] 文字範囲 {a…z} の 1 文字と一致します。
[^a] 文字セットまたは範囲 {a} からのものではない 1 文字と一致します。 ^ 文字は左角かっこのすぐ右側に表示されることに注意してください。
{ab,cd} 文字列セット {ab, cd} の文字列と一致します。
{ab,c{de, fh}} 文字列セット {ab, cde, cfh} の文字列と一致します。

read_files では、glob を使用してファイルを検出する場合に、自動ローダーの厳密な globber が使用されます。 これは、useStrictGlobber オプションで構成されます。 厳密な globber を無効にすると、末尾のスラッシュ (/) が削除され、/*/ などの star パターンが複数のディレクトリを検出するように拡張できます。 動作の違いについては、以下の例を参照してください。

パターン [ファイル パス] 厳密な globber が無効 厳密な 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 は、ユーザーがクエリを指定していない場合、ノートブックと SQL エディターの SELECT クエリの LIMIT ステートメントを自動的に追加します。

schemaHints オプションは、推論されたスキーマのサブセットの修正に使用できます。 詳細については、「スキーマヒントを使用してスキーマ推論をオーバーライドする」を参照してください。

既定では、rescuedDataColumn は、スキーマに一致しないデータを復旧するために指定されます。 詳細については、「復旧されたデータ列とは」を参照してください。 オプション schemaEvolutionMode => 'none' を設定して、rescuedDataColumn を削除できます。

パーティション スキーマの推論

read_files では、ファイルが Hive スタイルのパーティション分割されたディレクトリ (/column_name=column_value/) の下に格納されている場合、パーティション分割列を推論することもできます。 schema が指定されている場合、検出されたパーティション列では、schema で提供される型が使用されます。 パーティション列が指定された schema の一部でない場合、推論されるパーティション列は無視されます。

パーティション スキーマとデータ列の両方に列が存在する場合は、データ値の代わりにパーティション値から読み取られた値が使用されます。 ディレクトリから生成される値を無視してデータ列を使用する場合は、partitionColumns オプションを使用してコンマ区切りリスト内のパーティション列の一覧を指定できます。

partitionColumns オプションは、最終的に推論されたスキーマに含める検出された列で read_files を指示するために使用することもできます。 空の文字列を指定すると、すべてのパーティション列が無視されます。

パーティション列の推論されたスキーマをオーバーライドする schemaHints オプションを指定することもできます。

TEXT および BINARYFILE 形式には固定スキーマがありますが、可能な場合は、read_files でこれらの形式のパーティション分割の推論も試行されます。

ストリーミング テーブルでの使用状況

read_files は、Delta Lake にファイルを取り込むためのストリーミング テーブルで使用できます。 read_files は、ストリーミング テーブル クエリで使用される場合に自動ローダーを利用します。 read_files で STREAM キーワードを使用する必要があります。 詳細については、「自動ローダーとは」を参照してください。

ストリーミング クエリで使用する場合、read_files ではデータのサンプルを使用してスキーマを推論し、より多くのデータを処理するスキーマを進化させることができます。 詳細については、「自動ローダーでのスキーマの推論と展開の構成」を参照してください。

[オプション]

[基本] オプション

オプション
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 になります。
file2.csv および file3.csv の month および day は正しく解析されます。

既定値: なし
schemaHints

型: String

スキーマの推論中に自動ローダーに提供するスキーマ情報。 詳細については、スキーマ ヒントに関するページを参照してください。

既定値: なし
useStrictGlobber

型: Boolean

Apache Spark の他のファイル ソースの既定のグロビング動作に一致する厳密な globber を使用するかどうか。 詳細については、「一般的なデータ読み込みパターン」を参照してください。 Databricks Runtime 12.2 LTS 以降で使用できます。 これは、自動ローダーの既定値とは逆であることに注意してください。

既定値:true

共通オプション

次のオプションは、すべてのファイル形式に適用されます。

オプション
ignoreCorruptFiles

型: Boolean

破損したファイルを無視するかどうか。 true の場合、破損したファイルが検出されても Spark ジョブは引き続き実行され、読み取られた内容は引き続き返されます。 次のように numSkippedCorruptFiles として観察可能です。
operationMetrics Delta Lake 履歴の列。 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。 read_files では fileNamePattern を使用できます。

既定値: なし
recursiveFileLookup

型: Boolean

スキーマ推論中にパーティションの推論をスキップするかどうかを指定します。 これは、どのファイルを読み込むかには影響しません。

既定値:false

JSON のオプション

オプション
allowBackslashEscapingAnyCharacter

型: Boolean

バックスラッシュを使用して、後続の任意の 1 文字をエスケープすることを許可するかどうか。 有効にしない場合は、JSON の仕様に明示されている文字のみをエスケープできます。

既定値:false
allowComments

型: Boolean

解析対象のコンテンツ内で Java、C、および C++ スタイルのコメント ('/'、'*'、および '//' の種類) の使用を許可するかどうか。

既定値:false
allowNonNumericNumbers

型: Boolean

非数値 (NaN) トークンのセットを有効な浮動小数点数値として許可するかどうか。

既定値:true
allowNumericLeadingZeros

型: Boolean

追加の (無視できる) ゼロで始まる整数値を許可するかどうか (例: 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

連続する 2 つの 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

可能な場合は float 型や double 型の代わりに DecimalType として文字列を推論しようとします。 また、以下によりスキーマ推論も使う必要があります
inferSchema を有効にするか、Auto Loader で cloudFiles.inferColumnTypes を使います。

既定値:false
primitivesAsString

型: Boolean

数値やブール値などのプリミティブ型を StringType として推論するかどうか。

既定値:false
readerCaseSensitive

型: Boolean

rescuedDataColumn が有効な場合、大文字と小文字の区別の動作を指定します。 true の場合、スキーマと大文字と小文字が異なる名前のデータ列を取り出します。それ以外の場合は、大文字と小文字を区別しない方法でデータを読み込みます。 Databricks Runtime
13.3 以上で使用できます。

既定値:true
rescuedDataColumn

型: String

データ型の不一致またはスキーマの不一致 (列の大文字と小文字の区別を含む) が原因で解析できないすべてのデータを別の列に収集するかどうか。 自動ローダーを使用する場合、この列は既定で含まれます。 詳細については、「復旧されたデータ列とは」を参照してください。

既定値: なし
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]) が読み取られ、終了引用符が見つからないためエラーがスローされます。
* '\' をエスケープする文字を '\' と定義した場合、このレコードから 2 つの値 ([a\] と [b]) が読み取られます。

既定値:'\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

連続する 2 つの 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 がスローされます。

既定値:STOP_AT_DELIMITER

XML オプション

オプション 説明 スコープ
rowTag 行として扱う XML ファイルの行タグ。 XML <books> <book><book>...<books> の例では、適切な値は book です。 これは必須オプションです。 読み取り
samplingRatio スキーマ推論に使用される行の割合を定義します。 XML 組み込み関数はこのオプションを無視します。 既定値: 1.0。 読み取り
excludeAttribute 要素内の属性を除外するかどうか。 既定値: false。 読み取り
mode 解析中に破損したレコードを処理するモードを許可します。

PERMISSIVE: 破損したレコードの場合は、columnNameOfCorruptRecord によって構成されたフィールドに形式に誤りがある文字列を格納し、形式に誤りがあるフィールドを null に設定します。 破損したレコードを保持するには、ユーザー定義スキーマで columnNameOfCorruptRecord という名前の string 型フィールドを設定できます。 スキーマにこのフィールドがない場合、破損したレコードは解析中に削除されます。 スキーマを推論すると、パーサーは出力スキーマに columnNameOfCorruptRecord フィールドを暗黙的に追加します。

DROPMALFORMED: 破損したレコードを無視します。 このモードは XML 組み込み関数ではサポートされていません。

FAILFAST: パーサーが破損したレコードに合致する場合に、例外をスローします。		 読み取り
inferSchema true の場合は、結果として得られる各データフレーム列に対して適切な型を推論しようとします。 false の場合、結果の列はすべて string 型です。 既定:
true XML 組み込み関数はこのオプションを無視します。		 読み取り
columnNameOfCorruptRecord 次のモードで作成された形式に誤りがある文字列を含む新しいフィールドの名前を変更できるようにします:
PERMISSIVE モード。 既定値: spark.sql.columnNameOfCorruptRecord。		 読み取り
attributePrefix 属性と要素を区別するための属性のプレフィックス。 これはフィールド名のプレフィックスになります。 既定値は _ です。 XML の読み取り時は空にすることができますが、書き込み時は空にすることはできません。 読み取り、書き込み
valueTag 属性または子要素の要素も持つ要素内の文字データに使用されるタグ。 ユーザーがスキーマで valueTag フィールドを指定することもできますが、文字データが他の要素や属性と一緒に要素に存在する場合、スキーマ推論中に自動的に追加されます。 既定値: _VALUE 読み取り、書き込み
encoding 読み取りの場合は、指定されたエンコードの種類で XML ファイルをデコードします。 書き込みの場合は、保存される XML ファイルのエンコード (文字セット) を指定します。 XML 組み込み関数はこのオプションを無視します。 既定値: UTF-8。 読み取り、書き込み
ignoreSurroundingSpaces 読み取られる値の周囲の空白をスキップするかどうかを定義します。 既定値: true。 空白のみの文字データは無視されます。 読み取り
rowValidationXSDPath 各行の省略可能な XML を個別に検証するために使用される XSD ファイルへのパス。 検証に失敗した行は、上記のように解析エラーと同様に処理されます。 XSD から、指定または推論されたスキーマにそれ以外の影響は及びません。 読み取り
ignoreNamespace true の場合、XML 要素と属性の名前空間プレフィックスは無視されます。 たとえば、タグ <abc:author> と <def:author> は、どちらも単なる <author> として扱われます。 rowTag 要素では名前空間を無視できず、その子の読み取りのみを無視できることに注意してください。 false の場合でも、XML 解析は名前空間を認識しません。 既定値: false。 読み取り
timestampFormat datetime パターン形式に従ったカスタム タイムスタンプ形式の文字列。 これは timestamp 型に適用されます。 既定値: yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]。 読み取り、書き込み
timestampNTZFormat datetime パターン形式に従った、タイムゾーンを含まないカスタム形式の文字列。 これは TimestampNTZType 型に適用されます。 既定:
yyyy-MM-dd'T'HH:mm:ss[.SSS]		 読み取り、書き込み
dateFormat datetime パターン形式に従ったカスタム日付形式の文字列。 これは、date 型に適用されます。 既定値: yyyy-MM-dd。 読み取り、書き込み
locale IETF BCP 47 形式の言語タグとしてロケールを設定します。 たとえば、locale は日付とタイムスタンプの解析中に使用されます。 既定値: en-US。 読み取り
rootTag XML ファイルのルート タグ。 例えば、<books> <book><book>...</books> では、適切な値は books です。 books foo="bar" のように値を指定することで、基本属性を含めることができます。 既定値: ROWS。 write
declaration rootTag の前のすべての出力 XML ファイルに書き込む XML 宣言のコンテンツ。 たとえば、foo の値を指定すると <?xml foo?> が書き込まれます。 空の文字列に設定すると抑制されます。 既定値: version="1.0"
encoding="UTF-8" standalone="yes"		 write
arrayElementName 配列値列の各要素を囲む XML 要素の名前。 既定値: item。 write
nullValue null 値の文字列表記を設定します。 既定値: 文字列 null。 これが null である場合、パーサーはフィールドの属性と要素を書き込みません。 読み取り、書き込み
compression ファイルに保存するときに使用する圧縮コード。 これは、大文字と小文字は区別されない短縮名 (none、bzip2、gzip、lz4、snappy', and<br>deflate`) のいずれかです。 XML 組み込み関数はこのオプションを無視します。 既定値: none。 write
validateName true の場合、XML 要素名の検証に失敗した場合にエラーをスローします。 たとえば、SQL フィールド名にはスペースを含めることができますが、XML 要素名にはスペースを含めることができません。 既定:
true		 write
readerCaseSensitive rescuedDataColumn が有効な場合、大文字と小文字の区別の動作を指定します。 true の場合、スキーマと大文字と小文字が異なる名前のデータ列を取り出します。それ以外の場合は、大文字と小文字を区別しない方法でデータを読み込みます。 既定値: true。 読み取り
rescuedDataColumn データ型の不一致およびスキーマの不一致 (列の大文字と小文字の区別を含む) が原因で解析できないすべてのデータを別の列に収集するかどうか。 自動ローダーを使用する場合、この列は既定で含まれます。 詳細については、「復旧されたデータ列とは」を参照してください。 既定値: None。 読み取り

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 スキーマと互換性はありますが、異なるものです。 逆シリアル化スキーマは、展開されたスキーマと一致するようになります。 たとえば、既定値がある追加列を 1 つ含む展開されたスキーマを設定した場合、読み取り結果にその新しい列も含まれるようになります。

既定値: なし
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

連続する 2 つのテキスト レコード間の文字列。

既定値: なし。\r、\r\n、\n を対象として含みます
wholeText

型: Boolean

ファイルを単一レコードとして読み取るかどうか。

既定値:false

ORC のオプション

オプション
mergeSchema

型: Boolean

複数のファイル全体でスキーマを推論するか、各ファイルのスキーマをマージするかどうか。

既定値:false

ストリーミング オプション

これらのオプションは、ストリーミング テーブルまたはストリーミング クエリ内で read_files を使用する場合に適用されます。

オプション
allowOverwrites

型: Boolean

検出後に変更されたファイルを再処理するかどうか。 成功した前回の更新クエリの開始時刻以降にファイルが変更された場合、ファイルの利用可能な最新バージョンは更新中に処理されます。

既定値:false
includeExistingFiles

型: Boolean

ストリーム処理入力パスに既存のファイルを含めるか、初期セットアップ後に到着した新しいファイルのみを処理するか。 このオプションは、初めてストリームを開始するときにのみ評価されます。 ストリームの再起動後にこのオプションを変更した場合、効果はありません。

既定値:true
maxBytesPerTrigger

型: Byte String

各トリガーで処理される新しいバイトの最大数。 10g などのバイト文字列を指定して、各マイクロバッチを 10 GB のデータに制限できます。 これはソフト最大値です。 それぞれ 3 GB のファイルがある場合、Azure Databricks は 1 マイクロバッチで 12 GB を処理します。 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);