Condividi tramite

Opzioni del caricatore automatico

  • Articolo

Le opzioni di configurazione specifiche dell'origine cloudFiles sono precedute da un prefisso cloudFiles in modo che si trovino in uno spazio dei nomi separato da altre opzioni di origine Structured Streaming.

Opzioni comuni del caricatore automatico

È possibile configurare le opzioni seguenti per l'elenco di directory o la modalità di notifica file.

Opzione
cloudFiles.allowOverwrites
Tipo: Boolean
Indica se consentire modifiche al file della directory di input per sovrascrivere i dati esistenti.
Esistono alcune avvertenze relative all'abilitazione di questa configurazione. Per informazioni dettagliate, vedere Il caricatore automatico elabora nuovamente il file quando il file viene accodato o sovrascritto?.
Valore predefinito: false
cloudFiles.backfillInterval
Tipo: Interval String
Il caricatore automatico può attivare i backfill asincroni a un determinato intervallo,
ad esempio 1 day per il riempimento una volta al giorno o 1 week per il riempimento una volta alla settimana. I sistemi di notifica degli eventi file non garantiscono il 100% del recapito di tutti i file caricati, pertanto è possibile usare i backfill per garantire che tutti i file vengano elaborati, disponibili in Databricks Runtime 8.4 (EoS) e versioni successive.
Valore predefinito: Nessuno
cloudFiles.format
Tipo: String
Formato del file di dati nel percorso di origine. I valori consentiti includono:

Valore predefinito: Nessuno (opzione obbligatoria)
cloudFiles.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 avvii uno streaming per la prima volta. La modifica di questa opzione dopo il riavvio del flusso non ha alcun effetto.
Valore predefinito: true
cloudFiles.inferColumnTypes
Tipo: Boolean
Indica se dedurre tipi esatti di colonna quando si utilizza l'inferenza dello schema. Per impostazione predefinita, le colonne vengono dedotte come stringhe durante l'inferenza di set di dati JSON e CSV. Per altri dettagli, vedere Inferenza dello schema.
Valore predefinito: false
cloudFiles.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 cloudFiles.maxFilesPerTrigger, Azure Databricks usa fino al limite inferiore di cloudFiles.maxFilesPerTrigger o cloudFiles.maxBytesPerTrigger, quello che viene raggiunto per primo. Questa opzione non ha alcun effetto se usata con Trigger.Once() (Trigger.Once() è deprecata).
Valore predefinito: Nessuno
cloudFiles.maxFileAge
Tipo: Interval String
Per quanto tempo viene rilevato un evento di file a scopo di deduplicazione. Databricks sconsiglia di ottimizzare questo parametro a meno che non si stiano inserendo dati nell'ordine di milioni di file all'ora. Per altri dettagli, vedere la sezione relativa alla conservazione degli eventi.
L'ottimizzazione troppo aggressiva di cloudFiles.maxFileAge può causare problemi di qualità dei dati, ad esempio l'inserimento duplicato o i file mancanti. Di conseguenza, Databricks consiglia un'impostazione conservativa per cloudFiles.maxFileAge, ad esempio 90 giorni, che è simile a quella consigliata per le soluzioni di inserimento dati simili.
Valore predefinito: Nessuno
cloudFiles.maxFilesPerTrigger
Tipo: Integer
Numero massimo di nuovi file da elaborare in ogni trigger. Se usato insieme a cloudFiles.maxBytesPerTrigger, Azure Databricks usa fino al limite inferiore di cloudFiles.maxFilesPerTrigger o cloudFiles.maxBytesPerTrigger, quello che viene raggiunto per primo. Questa opzione non ha alcun effetto se usata con Trigger.Once() (deprecato).
Valore predefinito: 1000
cloudFiles.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 e si fornirà il percorso <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 il risultato sarà
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
cloudFiles.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.
Valore predefinito: "addNewColumns" quando non viene fornito uno schema.
In caso contrario, "none".
cloudFiles.schemaHints
Tipo: String
Informazioni sullo schema fornite ad *Auto Loader* nell'ambito dell'inferenza dello schema. Vedere hint di schema per maggiori dettagli.
Valore predefinito: Nessuno
cloudFiles.schemaLocation
Tipo: String
La posizione in cui archiviare lo schema dedotto e le modifiche successive. Per altri dettagli, vedere Inferenza dello schema.
Valore predefinito: Nessuno (obbligatorio quando si deduce lo schema)
cloudFiles.useStrictGlobber
Tipo: Boolean
Se utilizzare un globber rigoroso che corrisponde al comportamento predefinito di globbing di altre fonti 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.
Valore predefinito: false
cloudFiles.validateOptions
Tipo: Boolean
Indica se convalidare le opzioni del caricatore automatico e restituire un errore per opzioni sconosciute o incoerenti.
Valore predefinito: true

Opzioni per l'elenco delle directory

Le opzioni seguenti sono rilevanti per la modalità di elenco della directory.

Opzione
cloudFiles.useIncrementalListing (deprecato)
Tipo: String
Questa funzionalità è stata deprecata. Databricks consiglia di usare la modalità di notifica file anziché
cloudFiles.useIncrementalListing.
Indicare se utilizzare l'elenco incrementale anziché quello completo nella modalità elenco directory. Per impostazione predefinita, il caricatore automatico fa il massimo sforzo per rilevare automaticamente se una determinata directory è applicabile per l'elenco incrementale. È possibile usare in modo esplicito l'elenco incrementale o usare l'elenco completo della directory impostandolo rispettivamente come true o false.
L'abilitazione errata dell'elenco incrementale in una directory non lessicalmente ordinata impedisce al caricatore automatico di individuare nuovi file.
Funziona con Azure Data Lake Storage (abfss://), S3 (s3://) e GCS (gs://).
Disponibile in Databricks Runtime 9.1 LTS e versioni successive.
Valore predefinito: auto
Valori disponibili: auto, true, false

Opzioni di notifica del file

Le opzioni seguenti sono rilevanti per la modalità di notifica dei file.

Opzione
cloudFiles.fetchParallelism
Tipo: Integer
Numero di thread da usare per il recupero di messaggi dal servizio di accodamento.
Valore predefinito: 1
cloudFiles.pathRewrites
Tipo: stringa JSON
Obbligatorio solo se si specifica un queueUrl che riceve notifiche di file da più bucket S3 e si vuole sfruttare i punti di montaggio configurati per l'accesso ai dati in questi contenitori. Usa questa opzione per riscrivere il prefisso del percorso bucket/key con il punto di montaggio. È possibile riscrivere solo i prefissi. Ad esempio, per la configurazione
{"<databricks-mounted-bucket>/path": "dbfs:/mnt/data-warehouse"}, il percorso
s3://<databricks-mounted-bucket>/path/2017/08/fileA.json viene riscritto in dbfs:/mnt/data-warehouse/2017/08/fileA.json.
Valore predefinito: Nessuno
cloudFiles.resourceTag
Tipo: Map(String, String)
Una serie di coppie di tag chiave-valore che consentono di associare e identificare le risorse correlate, ad esempio:
cloudFiles.option("cloudFiles.resourceTag.myFirstKey", "myFirstValue")
.option("cloudFiles.resourceTag.mySecondKey", "mySecondValue")
Per altre informazioni su AWS, vedere Tag di allocazione dei costi di Amazon SQS e Configurazione dei tag per un argomento Amazon SNS. (1)
Per ulteriori informazioni su Azure, vedere Denominazione di code e metadati e la copertura di properties.labels nella sezione Sottoscrizioni di eventi. Il caricatore automatico archivia queste coppie di tag chiave-valore in JSON come etichette. (1)
Per altre informazioni su GCP, vedere Creazione di report sull'utilizzo con le etichette. (1)
Valore predefinito: Nessuno
cloudFiles.useNotifications
Tipo: Boolean
Indica se usare la modalità di notifica file per determinare quando sono presenti nuovi file. Se false, usare la modalità elenco di directory. Vedere Confrontare le modalità di rilevamento dei file del caricatore automatico.
Valore predefinito: false

(1) Il caricatore automatico aggiunge le seguenti coppie di tag chiave-valore per impostazione predefinita:

  • vendor: Databricks
  • path: percorso da cui vengono caricati i dati. Non disponibile in GCP a causa di limitazioni di etichettatura.
  • checkpointLocation: La posizione del checkpoint del flusso. Non disponibile in GCP a causa di limitazioni di etichettatura.
  • streamId: un identificatore univoco globale per il flusso.

Questi nomi chiave sono riservati e non è possibile sovrascrivere i relativi valori.

opzioni di formato file

Con il caricatore automatico è possibile inserire i file JSON, CSV, PARQUET, AVRO, TEXT, BINARYFILE, e ORC.

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 possibile modello di glob da fornire per la scelta 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 questa opzione, solo i caratteri elencati in modo esplicito dalla specifica JSON possono essere escapati.
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 racchiudere stringhe (nomi e valori String).
Valore predefinito: true
allowUnquotedControlChars
Tipo: Boolean
Indica se permettere che le stringhe JSON contengano caratteri di controllo non escape (caratteri ASCII con valore minore di 32, inclusi caratteri di tabulazione 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 l'archiviazione di record malformati e non analizzabili. Se il parametro di analisi mode è impostato su DROPMALFORMED, questa 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 colonne con tutti i valori nulli o matrici e strutture 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 l'analisi predefinita 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. È inoltre necessario usare l'inferenza dello schema, ad esempio abilitando
inferSchema o usando cloudFiles.inferColumnTypes con Auto Loader.
Valore predefinito: false
primitivesAsString
Tipo: Boolean
Stabilisce se dedurre tipi primitivi come i numeri e i booleani sotto forma di StringType.
Valore predefinito: false
readerCaseSensitive
Tipo: Boolean
Specifica il comportamento di distinzione tra maiuscole e minuscole quando rescuedDataColumn è abilitato. Se è vero, recupera le colonne di dati i cui nomi differiscono per maiuscole e minuscole rispetto allo schema; altrimenti, leggi i dati senza distinzione tra maiuscole e minuscole. Disponibile in Databricks Runtime
13.3 o superiore.
Valore predefinito: true
rescuedDataColumn
Tipo: String
Se si debba raccogliere tutti i dati che non possono essere analizzati a causa di una mancata corrispondenza del tipo di dati o dello schema (inclusa la formattazione delle maiuscole/minuscole delle colonne) 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 disabilitati, 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 eseguire l'escape del carattere utilizzato per l'escape delle virgolette. Ad esempio, per i seguenti record [ " a\\", b ]:
  • Se il carattere di escape per il '\' 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 '\' è definito come '\', il record viene letto con 2 valori: [a\] e [b].

Valore predefinito: '\0'
columnNameOfCorruptRecord
Supportato per l'Auto Loader. Non è supportato per COPY INTO (legacy).
Tipo: String
Colonna per l'archiviazione di record malformati e non analizzabili. Se il parametro di analisi mode è impostato su DROPMALFORMED, questa 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 inferisce lo 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
Indica 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 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'analisi predefinita di date, timestamp e decimali all'interno del file 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 l'Auto Loader quando si deduce lo 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 testuale 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 (deprecato)
Tipo: Boolean
Durante la lettura dei file, se si debbano allineare le colonne dichiarate nell'intestazione tenendo conto delle maiuscole e minuscole dello schema. Questa opzione è true per impostazione predefinita per Auto Loader. 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 come stringa dell'infinito positivo durante l'analisi delle colonne FloatType o DoubleType.
Valore predefinito: "Inf"
preferDate
Tipo: Boolean
Quando possibile, tenta di interpretare le stringhe come date anziché come timestamp. È 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 escludere i valori quando 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, recupera le colonne di dati i cui nomi differiscono per maiuscole e minuscole rispetto allo schema; altrimenti, leggi i dati senza distinzione tra maiuscole e minuscole.
Valore predefinito: true
rescuedDataColumn
Tipo: String
Se devono essere raccolti tutti i dati che non possono essere analizzati a causa di: mancata corrispondenza del tipo di dati e 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
La 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 non saltata e non 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
Strategia per la gestione delle virgolette non precedute da caratteri di escape. Opzioni consentite:
  • STOP_AT_CLOSING_QUOTE: se nell'input vengono trovate virgolette senza caratteri di escape, accumulare il carattere della virgoletta e continuare ad analizzare il valore come valore tra virgolette, fino a quando non viene trovata una virgoletta di chiusura.
  • BACK_TO_DELIMITER: se nell'input vengono trovate virgolette senza caratteri di escape, considerare il valore come non virgolettato. 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 vengono trovate virgolette senza caratteri di escape, considerare il valore come non virgolettato. 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 nell'input vengono trovate virgolette senza caratteri di escape, il contenuto analizzato per il valore specificato verrà ignorato (finché non viene trovato il delimitatore successivo) e il valore impostato in nullValue verrà generato.
  • RAISE_ERROR: se nell'input vengono trovate virgolette senza caratteri di escape,
    TextParsingException verrà lanciata.

Valore predefinito: STOP_AT_DELIMITER

Opzioni XML

Opzione Descrizione Scope
rowTag Tag di riga dei file XML da considerare come 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 Tag utilizzato per i dati di caratteri all'interno di elementi che hanno anche attributi o elementi 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 caratteri composti solo da 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 sugli elementi e sugli 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 nell'elemento rowTag, solo i suoi elementi figli letti. L'analisi XML non è sensibile agli spazi dei nomi anche se false. Impostazione predefinita: false. leggere
timestampFormat Stringa di formato timestamp personalizzata che segue il modello di formato 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 segue il formato del modello datetime. Questo vale per il tipo di data. Impostazione predefinita: yyyy-MM-dd. lettura, scrittura
locale Imposta un locale come 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?>. Impostare 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: stringa 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. Potrebbe trattarsi di uno dei nomi abbreviati noti, senza distinzione tra maiuscole e minuscole (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, recupera le colonne di dati i cui nomi differiscono per maiuscole e minuscole rispetto allo schema; altrimenti, leggi i dati senza distinzione tra maiuscole e minuscole. Impostazione predefinita: true. leggere
rescuedDataColumn Valutare se raccogliere tutti i dati che non possono essere analizzati a causa di una discrepanza tra tipo di dati e schema (inclusa la distinzione tra maiuscole e minuscole) 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 il ricalcolo dei valori DATE e TIMESTAMP tra i calendari giuliano e gregoriano prolettico. Valori consentiti: EXCEPTION, LEGACY e
CORRECTED.
Valore predefinito: LEGACY
int96RebaseMode
Tipo: String
Controlla il riposizionamento dei valori di timestamp INT96 tra i calendari Giuliano 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, recupera le colonne di dati i cui nomi differiscono per maiuscole e minuscole rispetto allo schema; altrimenti, leggi i dati senza distinzione tra maiuscole e minuscole.
Valore predefinito: true
rescuedDataColumn
Tipo: String
Se devono essere raccolti tutti i dati che non possono essere analizzati a causa di: mancata corrispondenza del tipo di dati e 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 il ricalcolo dei valori DATE e TIMESTAMP tra i calendari giuliano 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.
mergeSchema per Avro non rilassa i tipi di dati.
Valore predefinito: false
readerCaseSensitive
Tipo: Boolean
Specifica il comportamento di distinzione tra maiuscole e minuscole quando rescuedDataColumn è abilitato. Se è vero, recupera le colonne di dati i cui nomi differiscono per maiuscole e minuscole rispetto allo schema; altrimenti, leggi i dati senza distinzione tra maiuscole e minuscole.
Valore predefinito: true
rescuedDataColumn
Tipo: String
Se devono essere raccolti tutti i dati che non possono essere analizzati a causa di: mancata corrispondenza del tipo di dati e 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 fra 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 specifiche del cloud

Il caricatore automatico offre diverse opzioni per la configurazione dell'infrastruttura cloud.

Opzioni specifiche di AWS

Specificare l'opzione seguente solo se si sceglie cloudFiles.useNotifications = true e si vuole che il caricatore automatico configuri automaticamente i servizi di notifica:

Opzione
cloudFiles.region
Tipo: String
L'area in cui risiede il bucket S3 di origine e dove verranno creati i servizi AWS SNS e SQS.
Valore predefinito: area dell'istanza EC2.

Specificare l'opzione seguente solo se si sceglie cloudFiles.useNotifications = true e si vuole che il caricatore automatico usi una coda già configurata:

Opzione
cloudFiles.queueUrl
Tipo: String
L'URL della coda SQS. Se specificato, Auto Loader consuma direttamente gli eventi da questa coda invece di configurare i propri servizi AWS SNS e SQS.
Valore predefinito: Nessuno

Opzioni di autenticazione di AWS

Fornire l'opzione di autenticazione seguente per usare una credenziale del servizio Databricks:

Opzione
databricks.serviceCredential
Tipo: String
Il nome della credenziale di servizio Databricks . Disponibile in Databricks Runtime 16.2 e versioni successive.
Valore predefinito: Nessuno

Quando le credenziali del servizio Databricks o i ruoli IAM non sono disponibili, è invece possibile fornire le opzioni di autenticazione seguenti:

Opzione
cloudFiles.awsAccessKey
Tipo: String
La chiave di accesso ID AWS per l’utente. Deve essere fornita con
cloudFiles.awsSecretKey.
Valore predefinito: Nessuno
cloudFiles.awsSecretKey
Tipo: String
La chiave di accesso segreta AWS per l’utente. Deve essere fornita con
cloudFiles.awsAccessKey.
Valore predefinito: Nessuno
cloudFiles.roleArn
Tipo: String
L'ARN di un ruolo IAM da assumere, se necessario. Il ruolo può essere assunto dal profilo dell'istanza del cluster o può essere fornito fornendo credenziali con
cloudFiles.awsAccessKey e cloudFiles.awsSecretKey.
Valore predefinito: Nessuno
cloudFiles.roleExternalId
Tipo: String
Identificatore da specificare durante l'assunzione di un ruolo tramite cloudFiles.roleArn.
Valore predefinito: Nessuno
cloudFiles.roleSessionName
Tipo: String
Un nome di sessione facoltativo da usare quando si assume un ruolo
cloudFiles.roleArn.
Valore predefinito: Nessuno
cloudFiles.stsEndpoint
Tipo: String
Endpoint facoltativo da fornire per l'accesso ad AWS STS quando si presuppone un ruolo usando cloudFiles.roleArn.
Valore predefinito: Nessuno

Opzioni specifiche di Azure

È necessario specificare i valori per tutte le opzioni seguenti se si specifica cloudFiles.useNotifications = true e si vuole che il caricatore automatico configuri automaticamente i servizi di notifica:

Opzione
cloudFiles.resourceGroup
Tipo: String
Gruppo di risorse Azure in cui viene creato l'account di archiviazione.
Valore predefinito: Nessuno
cloudFiles.subscriptionId
Tipo: String
L'ID sottoscrizione di Azure sotto cui viene creato il gruppo di risorse.
Valore predefinito: Nessuno
databricks.serviceCredential
Tipo: String
Il nome della credenziale di servizio Databricks . Disponibile in Databricks Runtime 16.2 e versioni successive.
Valore predefinito: Nessuno

Se una credenziale del servizio Databricks non è disponibile, è possibile fornire invece le opzioni di autenticazione seguenti:

Opzione
cloudFiles.clientId
Tipo: String
ID cliente o ID applicazione del principale del servizio.
Valore predefinito: Nessuno
cloudFiles.clientSecret
Tipo: String
Segreto del client principale di servizio.
Valore predefinito: Nessuno
cloudFiles.connectionString
Tipo: String
La stringa di connessione per l'account di archiviazione, in base alla chiave di accesso dell'account o alla firma di accesso condiviso (SAS).
Valore predefinito: Nessuno
cloudFiles.tenantId
Tipo: String
ID tenant di Azure sotto il quale viene creato il principale del servizio.
Valore predefinito: Nessuno

Importante

La configurazione automatica delle notifiche è disponibile nelle aree di Azure Cina e enti pubblici con Databricks Runtime 9.1 e versioni successive. È necessario fornire un queueName per utilizzare il Caricatore Automatico con le notifiche dei file nelle seguenti regioni per le versioni precedenti di DBR.

Specificare l'opzione seguente solo se si sceglie cloudFiles.useNotifications = true e si vuole che il caricatore automatico usi una coda già configurata:

Opzione
cloudFiles.queueName
Tipo: String
Nome della coda di Azure. Se specificato, l'origine dei file cloud utilizza direttamente gli eventi di questa coda invece di configurare i propri servizi Azure Event Grid e Queue Storage. In tal caso, il databricks.serviceCredential o cloudFiles.connectionString richiede solo autorizzazioni di lettura per la coda.
Valore predefinito: Nessuno

Opzioni specifiche di Google

Auto Loader può configurare automaticamente i servizi di notifica sfruttando le credenziali del servizio Databricks . L'account del servizio creato con le credenziali del servizio Databricks richiederà le autorizzazioni specificate in Che cos'è la modalità di notifica file di Auto Loader?.

Opzione
cloudFiles.projectId
Tipo: String
ID del progetto in cui si trova il bucket GCS. Anche la sottoscrizione di Google Cloud Pub/Sub verrà creata all'interno di questo progetto.
Valore predefinito: Nessuno
databricks.serviceCredential
Tipo: String
Il nome della credenziale di servizio Databricks . Disponibile in Databricks Runtime 16.2 e versioni successive.
Valore predefinito: Nessuno

Se le credenziali di un servizio Databricks non sono disponibili, è possibile usare direttamente gli account del servizio Google. È possibile configurare il cluster per presupporre un account del servizio seguendo configurazione del servizio Google oppure specificare direttamente le opzioni di autenticazione seguenti:

Opzione
cloudFiles.client
Tipo: String
ID client dell'account del servizio Google.
Valore predefinito: Nessuno
cloudFiles.clientEmail
Tipo: String
Indirizzo di posta elettronica dell'account del servizio Google.
Valore predefinito: Nessuno
cloudFiles.privateKey
Tipo: String
Chiave privata generata per l'account del servizio Google.
Valore predefinito: Nessuno
cloudFiles.privateKeyId
Tipo: String
ID della chiave privata generata per l'account del servizio Google.
Valore predefinito: Nessuno

Specificare l'opzione seguente solo se si sceglie cloudFiles.useNotifications = true e si vuole che il caricatore automatico usi una coda già configurata:

Opzione
cloudFiles.subscription
Tipo: String
Nome della sottoscrizione Google Cloud Pub/Sub. Se specificato, l'origine dei file cloud utilizza gli eventi di questa coda invece di configurare i propri servizi GCS Notification e Google Cloud Pub/Sub.
Valore predefinito: Nessuno