Condividi tramite

read_files funzione con valori di tabella

  • Articolo

Si applica a:segno di spunta sì Databricks SQL segno di spunta sì Databricks Runtime 13.3 LTS e versioni successive

Legge i file in un percorso specificato e restituisce i dati in formato tabulare.

Supporta la lettura dei formati di file JSON, CSV, XML, TEXT, BINARYFILE, PARQUET, AVRO e ORC. Può rilevare automaticamente il formato di file e dedurre uno schema unificato in tutti i file.

Sintassi

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

Argomenti

Questa funzione richiede la chiamata di parametri denominati per le chiavi di opzione.

  • path: un STRING con l'URI dell'ubicazione dei dati. Supporta la lettura da Azure Data Lake Storage Gen2 ('abfss://'), S3 (s3://) e Google Cloud Storage ('gs://'). Può contenere glob. Vedi Scoperta dei file per ulteriori dettagli.
  • option_key: nome dell'opzione da configurare. È necessario usare i backtick () for options that contain dots (.`).
  • option_value: espressione costante su cui impostare l'opzione . Accetta valori letterali e funzioni scalari.

Valori restituiti

Tabella composta dai dati dei file letti sotto il dato specificato path.

Scoperta file

read_files può leggere un singolo file o leggere i file in una directory specificata. read_files individua tutti i file nella directory specificata in modo ricorsivo, a meno che non venga fornito un GLOB , che indica read_files di ripetere il processo in un modello di directory specifico.

Filtro di directory o file usando modelli GLOB

I modelli Glob possono essere usati per filtrare directory e file quando specificati nel percorso.

Modello Descrizione
? Corrisponde a qualsiasi carattere singolo
* Corrisponde a zero o più caratteri
[abc] Trova la corrispondenza di un singolo carattere del set di caratteri {a,b,c}.
[a-z] Trova la corrispondenza di un singolo carattere dall'intervallo di caratteri {a... z}.
[^a] Trova la corrispondenza di un singolo carattere non incluso nel set di caratteri o nell'intervallo {a}. Si noti che il ^ carattere deve essere immediatamente a destra della parentesi aperta.
{ab,cd} Esegue la corrispondenza di una stringa dall'insieme di stringhe {ab, cd}.
{ab,c{de, fh}} Corrisponde a una stringa dal set di stringhe {ab, cde, cfh}.

read_files usa il globber rigido di Auto Loader per individuare i file con i glob. Questa opzione è configurata dall'opzione useStrictGlobber . Quando il globber rigido è disabilitato, le barre finali (/) vengono eliminate e un motivo a stella, /*/ ad esempio, può espandersi per individuare più directory. Vedere gli esempi seguenti per vedere la differenza nel comportamento.

Modello Percorso file Globber rigido disabilitato Strict globber abilitato
/a/b /a/b/c/file.txt Sì Sì
/a/b /a/b_dir/c/file.txt No No
/a/b /a/b.txt No No
/a/b/ /a/b.txt No No
/a/*/c/ /a/b/c/file.txt Sì Sì
/a/*/c/ /a/b/c/d/file.txt Sì Sì
/a/*/d/ /a/b/c/d/file.txt Sì No
/a/*/c/ /a/b/x/y/c/file.txt Sì No
/a/*/c /a/b/c_file.txt Sì No
/a/*/c/ /a/b/c_file.txt Sì No
/a/*/c /a/b/cookie/file.txt Sì No
/a/b* /a/b.txt Sì Sì
/a/b* /a/b/file.txt Sì Sì
/a/{0.txt,1.txt} /a/0.txt Sì Sì
/a/*/{0.txt,1.txt} /a/0.txt No No
/a/b/[cde-h]/i/ /a/b/c/i/file.txt Sì Sì

Inferenza dello schema

Lo schema dei file può essere fornito in modo esplicito a read_files con l'opzione schema . Quando lo schema non viene specificato, read_files tenta di dedurre uno schema unificato tra i file individuati, che richiede la lettura di tutti i file, a meno che non venga usata un'istruzione LIMIT . Anche quando si usa una LIMIT query, potrebbe essere letto un set di file di dimensioni maggiori di quello necessario per restituire uno schema più rappresentativo dei dati. Databricks aggiunge automaticamente un'istruzione LIMIT per le query SELECT nei notebook e nell'editor SQL se l'utente non ne ha fornita una.

L'opzione schemaHints può essere usata per correggere i subset dello schema dedotto. Vedere Oltrepassare l'inferenza dello schema con suggerimenti di schema per ulteriori dettagli.

Un rescuedDataColumn oggetto viene fornito per impostazione predefinita per salvare tutti i dati che non corrispondono allo schema. Per altri dettagli, vedere Che cos'è la colonna di dati salvata? È possibile eliminare rescuedDataColumn impostando l'opzione schemaEvolutionMode => 'none'.

Inferenza dello schema di partizione

può anche dedurre le colonne di partizionamento se i file sono archiviati in directory partizionate in stile Hive , cioè . Se un schema viene specificato, le colonne di partizione individuate utilizzano i tipi forniti in schema. Se le colonne di partizione non fanno parte dell'oggetto specificato schema, le colonne di partizione dedotte vengono ignorate.

Se esiste una colonna sia nello schema di partizione che nelle colonne di dati, viene usato il valore letto dal valore della partizione anziché il valore di dati. Se si desidera ignorare i valori provenienti dalla directory e usare la colonna di dati, è possibile fornire l'elenco di colonne di partizione in un elenco delimitato da virgole con l'opzione partitionColumns .

L'opzione partitionColumns può essere usata anche per indicare read_files sulle colonne individuate da includere nello schema dedotto finale. Se si specifica una stringa vuota, tutte le colonne di partizione vengono ignorate.

È possibile specificare anche l'opzione schemaHints per sovrascrivere lo schema dedotto per una colonna di partizione.

I TEXT formati e BINARYFILE hanno uno schema fisso, ma read_files tenta anche di dedurre il partizionamento per questi formati, quando possibile.

Utilizzo nelle tabelle di streaming

read_files può essere usato nelle tabelle di streaming per inserire file in Delta Lake. read_files utilizza Auto Loader in modo efficace quando viene impiegato in una query di una tabella di streaming. È necessario usare la STREAM parola chiave con read_files. Per altri dettagli, vedere Che cos'è il caricatore automatico?

Se usato in una query di streaming, read_files usa un esempio di dati per dedurre lo schema e può evolvere lo schema man mano che elabora più dati. Per altri dettagli, vedere Configurare l'inferenza e l'evoluzione dello schema in Caricamento automatico.

Opzioni

Opzioni standard

Opzione
format
Tipo: String
Formato del file di dati nel percorso di origine. Dedotto automaticamente se non specificato. I valori consentiti includono:

Valore predefinito: Nessuno
inferColumnTypes
Tipo: Boolean
Stabilisce se dedurre tipologie esatte di colonna quando si sfrutta l'inferenza dello schema. Per impostazione predefinita, le colonne vengono dedotte durante l'inferenza di set di dati JSON e CSV. Per altri dettagli, vedere Inferenza dello schema. Si noti che questo è l'opposto dell'impostazione predefinita di Auto Loader.
Valore predefinito: true
partitionColumns
Tipo: String
Elenco delimitato da virgole di colonne di partizione di stile Hive che si desidera dedurre dalla struttura di directory dei file. Le colonne di partizione dello stile Hive sono coppie chiave-valore combinate da un segno di uguaglianza, ad esempio
<base-path>/a=x/b=1/c=y/file.format. In questo esempio le colonne di partizione sono a, b e c. Per impostazione predefinita, queste colonne verranno aggiunte automaticamente allo schema se si utilizza l'inferenza dello schema, fornendo il <base-path> da cui caricare i dati. Se si specifica uno schema, il caricatore automatico prevede che queste colonne vengano incluse nello schema. Se non si desidera che queste colonne facciano parte dello schema, è possibile specificare "" per ignorare queste colonne. Inoltre, è possibile usare questa opzione quando si vuole dedurre il percorso del file in strutture di directory complesse, come nell'esempio seguente:
<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
Specificando cloudFiles.partitionColumns come year,month,day, questo restituirà
year=2022 per file1.csv, ma le colonne month e day saranno null.
month e day verranno analizzati correttamente per file2.csv e file3.csv.
Valore predefinito: Nessuno
schemaHints
Tipo: String
Informazioni sullo schema fornite ad Auto Loader durante l'inferenza dello schema. Vedere hint di schema per maggiori dettagli.
Valore predefinito: Nessuno
useStrictGlobber
Tipo: Boolean
Indica se usare un globber rigoroso che si allinei con il comportamento globbing predefinito di altre risorse di file in Apache Spark. Per altri dettagli, vedere Modelli di caricamento dei dati comuni. Disponibile in Databricks Runtime 12.2 LTS e versioni successive. Si noti che si tratta dell'opposto dell'impostazione predefinita per Il caricatore automatico.
Valore predefinito: true

Opzioni generiche

Le opzioni seguenti si applicano a tutti i formati di file.

Opzione
ignoreCorruptFiles
Tipo: Boolean
Indica se ignorare i file danneggiati. Se true, i processi Spark continueranno a essere eseguiti quando si verificano file danneggiati e il contenuto letto verrà comunque restituito. Osservabile come numSkippedCorruptFiles nella
colonna operationMetrics della cronologia di Delta Lake. Disponibile in Databricks Runtime 11.3 LTS e versioni successive.
Valore predefinito: false
ignoreMissingFiles
Tipo: Boolean
Indica se ignorare i file mancanti. Se true, i processi Spark continueranno a essere eseguiti quando vengono rilevati file mancanti e il contenuto letto verrà comunque restituito. Disponibile in Databricks Runtime 11.3 LTS e versioni successive.
Valore predefinito: false per il caricatore automatico, true per COPY INTO (legacy)
modifiedAfter
Tipo: Timestamp String, per esempio, 2021-01-01 00:00:00.000000 UTC+0
Timestamp facoltativo per inserire file con un timestamp di modifica dopo il timestamp specificato.
Valore predefinito: Nessuno
modifiedBefore
Tipo: Timestamp String, per esempio, 2021-01-01 00:00:00.000000 UTC+0
Timestamp facoltativo per inserire file con un timestamp di modifica prima del timestamp specificato.
Valore predefinito: Nessuno
pathGlobFilter oppure fileNamePattern
Tipo: String
Un potenziale modello glob da fornire per la selezione dei file. Equivalente a
PATTERN in COPY INTO (versione precedente). fileNamePattern può essere usato in read_files.
Valore predefinito: Nessuno
recursiveFileLookup
Tipo: Boolean
Questa opzione esegue ricerche nelle directory annidate anche se i nomi non seguono uno schema di denominazione di partizione come date=2019-07-01.
Valore predefinito: false

Opzioni JSON

Opzione
allowBackslashEscapingAnyCharacter
Tipo: Boolean
Indica se consentire alle barre rovesciate di eseguire l'escape di qualsiasi carattere che abbia esito positivo. Se non è abilitata, solo i caratteri specificatamente elencati dalla specifica JSON possono essere sottoposti a escape.
Valore predefinito: false
allowComments
Tipo: Boolean
Indica se consentire o meno l'uso dei commenti di stile Java, C e C++ ('/', '*' e '//' ) all'interno del contenuto analizzato.
Valore predefinito: false
allowNonNumericNumbers
Tipo: Boolean
Indica se consentire il set di token non numerici (NaN) come valori numerici mobili legali.
Valore predefinito: true
allowNumericLeadingZeros
Tipo: Boolean
Indica se consentire ai numeri integrali di iniziare con zeli aggiuntivi (ignorabili), (ad esempio 000001).
Valore predefinito: false
allowSingleQuotes
Tipo: Boolean
Indica se consentire l'uso di virgolette singole (apostrofo, carattere '\') per citare stringhe (nomi e valori String).
Valore predefinito: true
allowUnquotedControlChars
Tipo: Boolean
Indica se consentire alle stringhe JSON di contenere caratteri di controllo senza caratteri di escape (caratteri ASCII con valore minore di 32, inclusi caratteri di tabulazioni e avanzamento riga) o meno.
Valore predefinito: false
allowUnquotedFieldNames
Tipo: Boolean
Indica se consentire l'uso di nomi di campo senza virgolette (consentiti da JavaScript, ma non dalla specifica JSON).
Valore predefinito: false
badRecordsPath
Tipo: String
Percorso per archiviare i file per registrare le informazioni sui record JSON non validi.
Valore predefinito: Nessuno
columnNameOfCorruptRecord
Tipo: String
Colonna per la memorizzazione di record che sono malformati e non analizzabili. Se il parametro per l'analisi mode è impostato su DROPMALFORMED, la colonna sarà vuota.
Valore predefinito: _corrupt_record
dateFormat
Tipo: String
Formato per l'analisi delle stringhe di data.
Valore predefinito: yyyy-MM-dd
dropFieldIfAllNull
Tipo: Boolean
Indica se ignorare le colonne composte interamente da valori Null o matrici e strutture dati vuote durante l'inferenza dello schema.
Valore predefinito: false
encoding oppure charset
Tipo: String
Nome della codifica dei file JSON. Vedere java.nio.charset.Charset per l'elenco delle opzioni. Non è possibile usare UTF-16 e UTF-32 quando multiline è true.
Valore predefinito: UTF-8
inferTimestamp
Tipo: Boolean
Indica se provare a dedurre stringhe di timestamp come TimestampType. Se impostato su
true, l'inferenza dello schema potrebbe richiedere molto più tempo. È necessario abilitare cloudFiles.inferColumnTypes per l’uso con il caricatore automatico.
Valore predefinito: false
lineSep
Tipo: String
Una stringa tra due record JSON consecutivi.
Valore predefinito: nessuno, che copre \r, \r\n e \n
locale
Tipo: String
Un identificatore java.util.Locale. Influenza il parsing predefinito di date, timestamp e decimali all'interno del JSON.
Valore predefinito: US
mode
Tipo: String
Modalità parser per la gestione di record malformati. Uno di 'PERMISSIVE',
'DROPMALFORMED', o 'FAILFAST'.
Valore predefinito: PERMISSIVE
multiLine
Tipo: Boolean
Indica se i record JSON si estendono su più righe.
Valore predefinito: false
prefersDecimal
Tipo: Boolean
Tenta di dedurre stringhe come DecimalType invece di tipo float o double, quando possibile. Devi anche usare l'inferenza dello schema, ad esempio abilitando
inferSchema o usando cloudFiles.inferColumnTypes con il caricatore automatico.
Valore predefinito: false
primitivesAsString
Tipo: Boolean
Stabilisce se dedurre tipi primitivi quali numeri e booleani tramite StringType.
Valore predefinito: false
readerCaseSensitive
Tipo: Boolean
Specifica il comportamento di distinzione tra maiuscole e minuscole quando rescuedDataColumn è abilitato. Se è vero, salva le colonne di dati i cui nomi differiscono per il caso rispetto allo schema; altrimenti, leggi i dati senza distinzione di maiuscole e minuscole. Disponibile in Databricks Runtime
13.3 o superiore.
Valore predefinito: true
rescuedDataColumn
Tipo: String
Indicare se raccogliere tutti i dati che non possono essere esaminati a causa di una mancata corrispondenza del tipo di dati o di una mancata corrispondenza dello schema (compresa la distinzione tra maiuscole e minuscole) in una colonna separata. Questa colonna è inclusa per impostazione predefinita quando si usa il caricatore automatico. Per altre informazioni, vedere Che cos'è la colonna di dati salvata?
COPY INTO (legacy) non supporta la colonna di dati salvata perché non è possibile impostare manualmente lo schema usando COPY INTO. Databricks consiglia di usare il caricatore automatico per la maggior parte degli scenari di inserimento.
Valore predefinito: Nessuno
singleVariantColumn
Tipo: String
Indica se inserire l'intero documento JSON, analizzato in una singola colonna Variant con la stringa specificata come nome della colonna. Se disattivato, i campi JSON verranno inseriti nelle proprie colonne.
Valore predefinito: Nessuno
timestampFormat
Tipo: String
Formato per l'analisi delle stringhe di timestamp.
Valore predefinito: yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]
timeZone
Tipo: String
Oggetto java.time.ZoneId da utilizzare durante l'analisi di timestamp e date.
Valore predefinito: Nessuno

Opzioni CSV

Opzione
badRecordsPath
Tipo: String
Percorso in cui archiviare i file per registrare le informazioni sui record CSV non validi.
Valore predefinito: Nessuno
charToEscapeQuoteEscaping
Tipo: Char
Carattere utilizzato per sfuggire il carattere usato per sfuggire le virgolette. Ad esempio, per i seguenti record [ " a\\", b ]:
  • Se il carattere di escape per '\' non è definito, il record non verrà analizzato. Il parser leggerà i caratteri: [a],[\],["],[,],[ ],[b] e genererà un errore perché non riesce a trovare un'virgoletta di chiusura.
  • Se il carattere di escape del '\' viene definito come '\', il record verrà letto con 2 valori: [a\] e [b].

Valore predefinito: '\0'
columnNameOfCorruptRecord
Supportato per Auto Loader. Non supportato per COPY INTO (obsoleto).
Tipo: String
Colonna per la memorizzazione di record che sono malformati e non analizzabili. Se il parametro per l'analisi mode è impostato su DROPMALFORMED, la colonna sarà vuota.
Valore predefinito: _corrupt_record
comment
Tipo: Char
Definisce il carattere che rappresenta un commento di riga quando viene trovato all'inizio di una riga di testo. Usare '\0' per disabilitare l'ignoramento dei commenti.
Valore predefinito: '\u0000'
dateFormat
Tipo: String
Formato per l'analisi delle stringhe di data.
Valore predefinito: yyyy-MM-dd
emptyValue
Tipo: String
Rappresentazione in forma di stringa di un valore di vuoto.
Valore predefinito: ""
encoding oppure charset
Tipo: String
Nome della codifica dei file CSV. Vederejava.nio.charset.Charset per l'elenco delle opzioni. UTF-16 e UTF-32 non possono essere usati quando multiline è true.
Valore predefinito: UTF-8
enforceSchema
Tipo: Boolean
Indica se applicare forzatamente lo schema specificato o dedotto ai file CSV. Se l'opzione è abilitata, le intestazioni dei file CSV vengono ignorate. Questa opzione viene ignorata per impostazione predefinita quando si usa il caricatore automatico per salvare i dati e consentire l'evoluzione dello schema.
Valore predefinito: true
escape
Tipo: Char
Carattere di escape da utilizzare durante l'analisi dei dati.
Valore predefinito: '\'
header
Tipo: Boolean
Indica se i file CSV contengono un'intestazione. Auto Loader presuppone che i file abbiano intestazioni quando effettua l'inferenza dello schema.
Valore predefinito: false
ignoreLeadingWhiteSpace
Tipo: Boolean
Indica se ignorare gli spazi vuoti iniziali per ogni valore analizzato.
Valore predefinito: false
ignoreTrailingWhiteSpace
Tipo: Boolean
Indica se ignorare gli spazi vuoti finali per ogni valore analizzato.
Valore predefinito: false
inferSchema
Tipo: Boolean
Stabilire se dedurre i tipi di dati dei record CSV analizzati o assumere che tutte le colonne siano di StringType. Richiede un passaggio aggiuntivo sui dati se impostato su true. Per il caricatore automatico, usare cloudFiles.inferColumnTypes invece.
Valore predefinito: false
lineSep
Tipo: String
Una stringa di testo tra due record CSV consecutivi.
Valore predefinito: nessuno, che copre \r, \r\n e \n
locale
Tipo: String
Un identificatore java.util.Locale. Influenza l'interpretazione delle date, dei timestamp e dei decimali predefinita all'interno del file di tipo CSV.
Valore predefinito: US
maxCharsPerColumn
Tipo: Int
Numero massimo di caratteri previsti da un valore da analizzare. Può essere usato per evitare errori di memoria. Il valore predefinito è -1, ovvero illimitato.
Valore predefinito: -1
maxColumns
Tipo: Int
Limite rigido del numero di colonne che un record può avere.
Valore predefinito: 20480
mergeSchema
Tipo: Boolean
Indica se dedurre lo schema tra più file e unire lo schema di ogni file. Abilitato per impostazione predefinita per Auto Loader durante l'inferenza dello schema.
Valore predefinito: false
mode
Tipo: String
Modalità parser per la gestione di record malformati. Uno di 'PERMISSIVE',
'DROPMALFORMED' e 'FAILFAST'.
Valore predefinito: PERMISSIVE
multiLine
Tipo: Boolean
Indica se i record CSV si estendono su più righe.
Valore predefinito: false
nanValue
Tipo: String
Rappresentazione di stringa di un valore non numerico durante l'analisi delle colonne FloatType e DoubleType.
Valore predefinito: "NaN"
negativeInf
Tipo: String
La rappresentazione sotto forma di stringa dell'infinito negativo durante l'analisi delle colonne FloatType o DoubleType.
Valore predefinito: "-Inf"
nullValue
Tipo: String
Rappresentazione in forma di stringa del valore null.
Valore predefinito: ""
parserCaseSensitive (obsoleto)
Tipo: Boolean
Durante la lettura dei file, se si debbano allineare le colonne dichiarate nell'intestazione tenendo conto della sensibilità alle maiuscole e minuscole dello schema. Questa opzione è true per impostazione predefinita per il caricatore automatico. Le colonne che differiscono per caso verranno salvate nel rescuedDataColumn se abilitato. Questa opzione è stata deprecata a favore di readerCaseSensitive.
Valore predefinito: false
positiveInf
Tipo: String
La rappresentazione in forma di stringa dell'infinito positivo mentre si analizzano le colonne FloatType o DoubleType.
Valore predefinito: "Inf"
preferDate
Tipo: Boolean
Cerca di interpretare le stringhe come date anziché interpretarle come timestamp, quando possibile. È anche necessario usare l'inferenza dello schema, abilitando inferSchema o usando
cloudFiles.inferColumnTypes con caricatore automatico.
Valore predefinito: true
quote
Tipo: Char
Carattere utilizzato per eseguire l'escape dei valori in cui il delimitatore di campo fa parte del valore.
Valore predefinito: "
readerCaseSensitive
Tipo: Boolean
Specifica il comportamento di distinzione tra maiuscole e minuscole quando rescuedDataColumn è abilitato. Se è vero, salva le colonne di dati i cui nomi differiscono per il caso rispetto allo schema; altrimenti, leggi i dati senza distinzione di maiuscole e minuscole.
Valore predefinito: true
rescuedDataColumn
Tipo: String
Indica se raccogliere tutti i dati che non possono essere analizzati a causa di una mancata corrispondenza di tipo di dati o dello schema (incluse le maiuscole) in una colonna separata. Questa colonna è inclusa per impostazione predefinita quando si usa il caricatore automatico. Per altri dettagli, fare riferimento a Che cos'è la colonna di dati salvata?.
COPY INTO (legacy) non supporta la colonna di dati salvata perché non è possibile impostare manualmente lo schema usando COPY INTO. Databricks consiglia di usare il caricatore automatico per la maggior parte degli scenari di inserimento.
Valore predefinito: Nessuno
sep oppure delimiter
Tipo: String
Stringa di separazione tra le colonne.
Valore predefinito: ","
skipRows
Tipo: Int
Numero di righe dall'inizio del file CSV che devono essere ignorate (incluse le righe commentate e vuote). Se header è vero, l'intestazione sarà la prima riga che non sia stata ignorata né commentata.
Valore predefinito: 0
timestampFormat
Tipo: String
Formato per l'analisi delle stringhe di timestamp.
Valore predefinito: yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]
timeZone
Tipo: String
Oggetto java.time.ZoneId da utilizzare durante l'analisi di timestamp e date.
Valore predefinito: Nessuno
unescapedQuoteHandling
Tipo: String
La strategia per il trattamento delle virgolette non scappate. Opzioni consentite:
  • STOP_AT_CLOSING_QUOTE: Se nell'input vengono trovate virgolette senza caratteri di escape, registrare il carattere delle virgolette e procedere ad analizzare il valore come valore tra virgolette, fino a quando non viene trovata una virgoletta di chiusura.
  • BACK_TO_DELIMITER: Se nell'input si trovano virgolette non precedute da caratteri di escape, considerare il valore come un valore non quotato. In questo modo il parser accumula tutti i caratteri del valore analizzato corrente fino a quando non viene trovato il delimitatore definito da sep. Se non viene trovato alcun delimitatore nel valore, il parser continuerà ad accumulare caratteri dall'input fino a quando non viene trovato un delimitatore o una terminazione di riga.
  • STOP_AT_DELIMITER: Se nell'input si trovano virgolette non precedute da caratteri di escape, considerare il valore come un valore non quotato. In questo modo il parser accumula tutti i caratteri fino a quando il delimitatore definito da sep o una fine di riga viene trovata nell'input.
  • SKIP_VALUE: Se vengono trovate virgolette non scappate nell'input, il contenuto analizzato per il valore dato verrà ignorato (finché non si trova il delimitatore successivo) e verrà prodotto invece il valore impostato in nullValue.
  • RAISE_ERROR: se nell'input vengono trovate virgolette senza caratteri di escape,
    TextParsingException verrà lanciato.

Valore predefinito: STOP_AT_DELIMITER

Opzioni XML

Opzione Descrizione Scope
rowTag Il tag di riga dei file XML da trattare come una riga. Nell'esempio XML <books> <book><book>...<books>, il valore appropriato è book. Si tratta di un'opzione obbligatoria. leggere
samplingRatio Definisce una frazione di righe utilizzate per l'inferenza dello schema. Le funzioni predefinite XML ignorano questa opzione. Impostazione predefinita: 1.0. leggere
excludeAttribute Indica se escludere gli attributi negli elementi. Impostazione predefinita: false. leggere
mode Modalità per gestire i record danneggiati durante l'analisi.
PERMISSIVE: per i record danneggiati, inserisce la stringa in formato non valido in un campo configurato da columnNameOfCorruptRecord e imposta i campi in formato non valido su null. Per mantenere i record danneggiati, è possibile impostare un campo di tipo string denominato columnNameOfCorruptRecord in uno schema definito dall'utente. Se il campo non è presente in uno schema, i record danneggiati vengono eliminati durante l'analisi. Quando si deduce uno schema, il parser aggiunge in modo implicito un campo columnNameOfCorruptRecord in uno schema di output.
DROPMALFORMED: ignora i record danneggiati. Questa modalità non è supportata per le funzioni predefinite XML.
FAILFAST: genera un'eccezione quando il parser incontra i record danneggiati.		 leggere
inferSchema Se true, tenta di dedurre un tipo appropriato per ogni colonna DataFrame risultante. Se false, tutte le colonne risultanti sono di tipo string. Impostazione predefinita:
true. Le funzioni predefinite XML ignorano questa opzione.		 leggere
columnNameOfCorruptRecord Consente di rinominare il nuovo campo contenente una stringa in formato non valido creata dalla
modalità PERMISSIVE. Impostazione predefinita: spark.sql.columnNameOfCorruptRecord.		 leggere
attributePrefix Prefisso per gli attributi per distinguere gli attributi dagli elementi. Questo sarà il prefisso per i nomi dei campi. Il valore predefinito è _. Può essere vuoto per la lettura del codice XML, ma non per la scrittura. lettura, scrittura
valueTag Il tag utilizzato per i dati di tipo carattere all'interno di elementi che dispongono anche di attributo/i o elemento/i figlio. L'utente può specificare il campo valueTag nello schema oppure verrà aggiunto automaticamente durante l'inferenza dello schema quando i dati di tipo carattere sono presenti in elementi con altri elementi o attributi. Impostazione predefinita: _VALUE lettura, scrittura
encoding Per la lettura, decodifica i file XML in base al tipo di codifica specificato. Per la scrittura, specifica la codifica (charset) dei file XML salvati. Le funzioni predefinite XML ignorano questa opzione. Impostazione predefinita: UTF-8. lettura, scrittura
ignoreSurroundingSpaces Definisce se gli spazi vuoti circostanti dai valori letti devono essere ignorati. Impostazione predefinita: true. I dati di carattere che contengono solo spazi bianchi vengono ignorati. leggere
rowValidationXSDPath Percorso di un file XSD facoltativo utilizzato per convalidare il codice XML per ogni riga singolarmente. Le righe che non riescono a convalidare vengono considerate come gli errori di analisi come sopra. L'XSD non influisce in caso contrario sullo schema fornito o dedotto. leggere
ignoreNamespace Se true, i prefissi dei namespace su elementi e attributi XML vengono ignorati. I tag <abc:author> e <def:author>, ad esempio, vengono considerati come se entrambi siano solo <author>. I namespaces non possono essere ignorati sull'elemento rowTag, solo sui suoi elementi figli letti. L'analisi XML non è sensibile ai namespace anche se false. Impostazione predefinita: false. leggere
timestampFormat Stringa di formato di timestamp personalizzata che segue il formato del modello datetime. Questo vale per il tipo timestamp. Impostazione predefinita: yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]. lettura, scrittura
timestampNTZFormat Stringa di formato personalizzata per timestamp senza fuso orario che segue il formato del modello datetime. Questo vale per il tipo TimestampNTZType. Impostazione predefinita:
yyyy-MM-dd'T'HH:mm:ss[.SSS]		 lettura, scrittura
dateFormat La stringa del formato data personalizzato che segue il formato del modello datetime. Questo vale per il tipo di data. Impostazione predefinita: yyyy-MM-dd. lettura, scrittura
locale Imposta un'impostazione locale come un tag di lingua nel formato IETF BCP 47. Ad esempio, locale viene usato durante l'analisi di date e timestamp. Impostazione predefinita: en-US. leggere
rootTag Tag radice dei file XML. Per esempio, in <books> <book><book>...</books>, il valore appropriato è books. È possibile includere attributi di base specificando un valore come books foo="bar". Impostazione predefinita: ROWS. scrivi
declaration Contenuto della dichiarazione XML da scrivere all'inizio di ogni file XML di output, prima di rootTag. Ad esempio, un valore di foo causa la scrittura di <?xml foo?>. Imposta su una stringa vuota per sopprimere. Impostazione predefinita: version="1.0"
encoding="UTF-8" standalone="yes".		 scrivi
arrayElementName Nome dell'elemento XML che racchiude ogni elemento di una colonna con valori di matrice durante la scrittura. Impostazione predefinita: item. scrivi
nullValue Imposta la rappresentazione in forma di stringa del valore null. Valore predefinito: string null. Quando si tratta di null, il parser non scrive attributi ed elementi per i campi. lettura, scrittura
compression Codice di compressione da usare per il salvataggio nel file. Può trattarsi di uno dei nomi abbreviati noti insensibili alle maiuscole (none, bzip2, gzip,lz4, snappy e
deflate). Le funzioni predefinite XML ignorano questa opzione. Impostazione predefinita: none.		 scrivi
validateName Se true, genera un errore in caso di errore di convalida del nome dell'elemento XML. Ad esempio, i nomi dei campi SQL possono avere spazi, ma i nomi degli elementi XML non possono. Impostazione predefinita:
true.		 scrivi
readerCaseSensitive Specifica il comportamento di distinzione tra maiuscole e minuscole quando rescuedDataColumn è abilitato. Se è vero, salva le colonne di dati i cui nomi differiscono per il caso rispetto allo schema; altrimenti, leggi i dati senza distinzione di maiuscole e minuscole. Impostazione predefinita: true. leggere
rescuedDataColumn Stabilire se raccogliere tutti i dati che non possono essere analizzati a causa di una mancata corrispondenza dei tipi di dati o dello schema (incluso il formato delle maiuscole dei nomi delle colonne) in una colonna separata. Questa colonna è inclusa per impostazione predefinita quando si usa il caricatore automatico. Per altri dettagli, vedere Che cos'è la colonna di dati salvata?.
COPY INTO (legacy) non supporta la colonna di dati salvata perché non è possibile impostare manualmente lo schema usando COPY INTO. Databricks consiglia di usare il caricatore automatico per la maggior parte degli scenari di inserimento.
Impostazione predefinita: nessuna.		 leggere

Opzioni PARQUET

Opzione
datetimeRebaseMode
Tipo: String
Controlla la conversione dei valori di data e timestamp tra il calendario giuliano e il calendario gregoriano prolettico. Valori consentiti: EXCEPTION, LEGACY e
CORRECTED.
Valore predefinito: LEGACY
int96RebaseMode
Tipo: String
Controlla la ricalibrazione dei valori di timestamp INT96 tra i calendari Julian e Gregoriano prolettico. Valori consentiti: EXCEPTION, LEGACY e
CORRECTED.
Valore predefinito: LEGACY
mergeSchema
Tipo: Boolean
Indica se dedurre lo schema tra più file e unire lo schema di ogni file.
Valore predefinito: false
readerCaseSensitive
Tipo: Boolean
Specifica il comportamento di distinzione tra maiuscole e minuscole quando rescuedDataColumn è abilitato. Se è vero, salva le colonne di dati i cui nomi differiscono per il caso rispetto allo schema; altrimenti, leggi i dati senza distinzione di maiuscole e minuscole.
Valore predefinito: true
rescuedDataColumn
Tipo: String
Indica se raccogliere tutti i dati che non possono essere analizzati a causa di una mancata corrispondenza di tipo di dati o dello schema (incluse le maiuscole) in una colonna separata. Questa colonna è inclusa per impostazione predefinita quando si usa il caricatore automatico. Per altri dettagli, fare riferimento a Che cos'è la colonna di dati salvata?.
COPY INTO (legacy) non supporta la colonna di dati salvata perché non è possibile impostare manualmente lo schema usando COPY INTO. Databricks consiglia di usare il caricatore automatico per la maggior parte degli scenari di inserimento.
Valore predefinito: Nessuno

Opzioni AVRO

Opzione
avroSchema
Tipo: String
Schema facoltativo fornito da un utente in formato Avro. Quando si legge Avro, questa opzione può essere impostata su uno schema evoluto, compatibile ma diverso con lo schema Avro effettivo. Lo schema di deserializzazione sarà coerente con lo schema evoluto. Ad esempio, se si imposta uno schema evoluto contenente una colonna aggiuntiva con un valore predefinito, il risultato di lettura conterrà anche la nuova colonna.
Valore predefinito: Nessuno
datetimeRebaseMode
Tipo: String
Controlla la conversione dei valori di data e timestamp tra il calendario giuliano e il calendario gregoriano prolettico. Valori consentiti: EXCEPTION, LEGACY e
CORRECTED.
Valore predefinito: LEGACY
mergeSchema
Tipo: Boolean
Indica se dedurre lo schema tra più file e unire lo schema di ogni file.
mergeSchema per Avro non modifica i tipi di dati.
Valore predefinito: false
readerCaseSensitive
Tipo: Boolean
Specifica il comportamento di distinzione tra maiuscole e minuscole quando rescuedDataColumn è abilitato. Se è vero, salva le colonne di dati i cui nomi differiscono per il caso rispetto allo schema; altrimenti, leggi i dati senza distinzione di maiuscole e minuscole.
Valore predefinito: true
rescuedDataColumn
Tipo: String
Indica se raccogliere tutti i dati che non possono essere analizzati a causa di una mancata corrispondenza di tipo di dati o dello schema (incluse le maiuscole) in una colonna separata. Questa colonna è inclusa per impostazione predefinita quando si usa il caricatore automatico.
COPY INTO (legacy) non supporta la colonna di dati salvata perché non è possibile impostare manualmente lo schema usando COPY INTO. Databricks consiglia di usare il caricatore automatico per la maggior parte degli scenari di inserimento.
Per altri dettagli, fare riferimento a Che cos'è la colonna di dati salvata?.
Valore predefinito: Nessuno

Opzioni BINARYFILE

I file binari non dispongono di opzioni di configurazione aggiuntive.

Opzioni TEXT

Opzione
encoding
Tipo: String
Nome della codifica dei file TEXT. Vedere java.nio.charset.Charset per l'elenco delle opzioni.
Valore predefinito: UTF-8
lineSep
Tipo: String
Una stringa tra due record TEXT consecutivi.
Valore predefinito: nessuno, che copre \r, \r\n e \n
wholeText
Tipo: Boolean
Indica se leggere un file come singolo record.
Valore predefinito: false

Opzioni ORC

Opzione
mergeSchema
Tipo: Boolean
Indica se dedurre lo schema tra più file e unire lo schema di ogni file.
Valore predefinito: false

Opzioni di streaming

Queste opzioni si applicano quando si usa read_files all'interno di una tabella di streaming o di una query di streaming.

Opzione
allowOverwrites
Tipo: Boolean
Se rielaborare i file modificati dopo l'individuazione. L'ultima versione disponibile del file verrà elaborata durante un aggiornamento se è stata modificata dopo l'ora di inizio dell'ultima query di aggiornamento completata.
Valore predefinito: false
includeExistingFiles
Tipo: Boolean
Indica se includere file esistenti nel percorso di input di elaborazione del flusso o elaborare solo i nuovi file in arrivo dopo l'installazione iniziale. Questa opzione viene valutata solo quando si avvia uno streaming per la prima volta. La modifica di questa opzione dopo il riavvio del flusso non ha alcun effetto.
Valore predefinito: true
maxBytesPerTrigger
Tipo: Byte String
Numero massimo di nuovi byte da elaborare in ogni trigger. È possibile specificare una stringa di byte, ad esempio 10g per limitare ogni microbatch a 10 GB di dati. Questo è un massimo morbido. Se sono presenti file di 3 GB ciascuno, Azure Databricks elabora 12 GB in un microbatch. Se usato insieme a maxFilesPerTrigger, Azure Databricks consuma fino al limite inferiore di maxFilesPerTrigger o maxBytesPerTrigger, a seconda di quale valore viene raggiunto per primo.
Nota: Per le tabelle di streaming create su SQL Warehouses serverless, questa opzione e maxFilesPerTrigger non devono essere impostati per sfruttare il controllo dinamico dell'ammissione, che si adatta in base alle dimensioni del carico di lavoro e alle risorse di calcolo serverless per garantire la migliore latenza e prestazioni.
Valore predefinito: Nessuno
maxFilesPerTrigger
Tipo: Integer
Numero massimo di nuovi file da elaborare in ogni trigger. Se usato insieme a maxBytesPerTrigger, Azure Databricks consuma fino al limite inferiore di maxFilesPerTrigger o maxBytesPerTrigger, a seconda di quale valore viene raggiunto per primo.
Nota: Per le tabelle di streaming create su SQL Warehouses serverless, questa opzione e maxBytesPerTrigger non devono essere impostati per sfruttare il controllo dinamico dell'ammissione, che si adatta in base alle dimensioni del carico di lavoro e alle risorse di calcolo serverless per garantire la migliore latenza e prestazioni.
Valore predefinito: 1000
schemaEvolutionMode
Tipo: String
La modalità per l'evoluzione dello schema man mano che vengono individuate nuove colonne nei dati. Per impostazione predefinita, le colonne vengono dedotte come stringhe durante l'inferenza di set di dati JSON. Per altri dettagli, vedere Evoluzione dello schema. Questa opzione non si applica ai text file e binaryFile .
Valore predefinito: "addNewColumns" quando non viene fornito uno schema.
In caso contrario, "none".
schemaLocation
Tipo: String
Posizione dove memorizzare lo schema dedotto e le modifiche successive. Per altri dettagli, vedere Inferenza dello schema. Il percorso dello schema non è necessario se usato in una query di tabella di streaming.
Valore predefinito: Nessuno

Esempi

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