Referência de opçõesSpark API

Esta página lista as opções de entrada e saída disponíveis para as APIs do Spark que leem e gravam dados.

Opções do DataFrameReader

Use estas opções com DataFrameReader.option(), DataFrameReader.options(), read_files, COPY INTO e Auto Loader para controlar como o Databricks lê os arquivos de dados.

Exemplo

O exemplo a seguir define multiLine como True para leitura de arquivos JSON:

Python
Scala
SQL

Python
df = spark.read.format("json").option("multiLine", True).load("/path/to/data")

Scala
val df = spark.read.format("json").option("multiLine", "true").load("/path/to/data")

SQL
SELECT * FROM read_files("/path/to/data", format => "json", multiLine => true)

Comum

As seguintes opções se aplicam a todos os formatos de arquivo.

Chave	Padrão	Descrição
`ignoreCorruptFiles`	`false`	Se deve ignorar ou não os arquivos corrompidos. Se isso for verdade, o trabalho Spark continuará a ser executado ao encontrar arquivos corrompidos e o conteúdo que já foi lido ainda será retornado. Para `COPY INTO`, você pode observar arquivos corrompidos ignorados como `numSkippedCorruptFiles` na coluna `operationMetrics` do histórico do Delta Lake . Disponível no Databricks Runtime 11.3 LTS e versões superiores.
`ignoreMissingFiles`	`false` Para Auto Loader, `true` para `COPY INTO` (legado)	Se deve ignorar ou não os ficheiros em falta. Se isso for verdade, o trabalho Spark continuará a ser executado mesmo ao encontrar arquivos ausentes e o conteúdo ainda será retornado. Disponível no Databricks Runtime 11.3 LTS e versões superiores.
`modifiedAfter`	Nenhuma	Um carimbo de data/hora opcional como filtro para ingerir apenas arquivos que tenham um carimbo de data/hora de modificação posterior ao carimbo de data/hora fornecido.
`modifiedBefore`	Nenhuma	Um carimbo de data/hora opcional como filtro para ingerir apenas arquivos que tenham um carimbo de data/hora de modificação anterior ao carimbo de data/hora fornecido.
`pathGlobFilter` ou `fileNamePattern`	Nenhuma	Um possível padrão glob para auxiliar na seleção de arquivos. Equivalente a `PATTERN` em `COPY INTO` (legado). `fileNamePattern` pode ser usado em `read_files`.
`recursiveFileLookup`	`false`	Quando `true`, esta opção pesquisa em diretórios aninhados mesmo que seus nomes não sigam um esquema de nomenclatura de partição como `date=2019-07-01`.

Avro

Chave	Padrão	Descrição
`avroSchema`	Nenhuma	Esquema opcional fornecido pelo usuário no formato Avro. Ao ler um arquivo Avro, essa opção pode ser definida para um esquema evoluído que seja compatível, mas diferente do esquema Avro original. O esquema de desserialização é consistente com o esquema evoluído. Por exemplo, se você definir um esquema evoluído contendo uma coluna adicional com um valor default , o resultado da leitura também conterá a nova coluna.
`avroSchemaEvolutionMode`	`none`	Como lidar com a evolução do esquema ao usar um registro de esquemas. Valores válidos: `none` (ignorar alterações de esquema e continuar o Job), `restart` (quando alterações de esquema são detectadas, gera um `UnknownFieldException` e requer um reinício do Job).
`datetimeRebaseMode`	`LEGACY`	Controla o rebase dos valores DATE e TIMESTAMP entre calendários gregoriano juliano e proléptico. Valores válidos: `EXCEPTION`, `LEGACY` e `CORRECTED`.
`enableStableIdentifiersForUnionType`	`false`	Se deve ou não utilizar nomes de campo estáveis para os tipos Avro Union. Quando ativado, os nomes dos campos do tipo união são derivados de seus nomes de tipo em minúsculas (por exemplo, `member_int`, `member_string`). Lança uma exceção se dois nomes de tipo forem idênticos após a conversão para minúsculas.
`mergeSchema`	`false`	Se deve inferir o esquema em vários arquivos e mesclar o esquema de cada arquivo. `mergeSchema` para Avro não relaxa os tipos de dados.
`mode`	`FAILFAST`	Modo de análise sintática para lidar com registros corrompidos. Valores válidos: `FAILFAST` (lança uma exceção), `PERMISSIVE` (define campos malformados como nulos), `DROPMALFORMED` (descarta silenciosamente registros inválidos).
`readerCaseSensitive`	`true`	Especifica o comportamento de diferenciação entre maiúsculas e minúsculas quando `rescuedDataColumn` está ativado. Se verdadeiro, recupere as colunas de dados cujos nomes diferem em maiúsculas e minúsculas do esquema. Quando falso, leia os dados sem diferenciar maiúsculas de minúsculas.
`recursiveFieldMaxDepth`	Nenhuma	Profundidade máxima de recursão para campos Avro recursivos. Defina como `1` para truncar todos os campos recursivos, `2` para permitir um nível de recursão e assim por diante até `15`. Quando não definido ou `0`, os campos recursivos não são permitidos. Valores válidos: `0` a `15`.
`rescuedDataColumn`	Nenhuma	Determinar se todos os dados que não puderam ser analisados devido a: incompatibilidade de tipo de dados e incompatibilidade de esquema (incluindo maiúsculas e minúsculas nas colunas) devem ser coletados em uma coluna separada. Esta coluna é incluída por default ao usar Auto Loader. `COPY INTO` (legado) não suporta a coluna de dados recuperados porque você não pode definir manualmente o esquema usando `COPY INTO`. A Databricks recomenda o uso do Auto Loader para a maioria dos cenários de ingestão. Para obter mais detalhes, consulte O que é a coluna de dados recuperados?
`stableIdentifierPrefixForUnionType`	`member_`	O prefixo a ser usado para nomes de campos de tipo de união estável quando `enableStableIdentifiersForUnionType=true`.

CSV

Chave	Padrão	Descrição
`badRecordsPath`	Nenhuma	O caminho para armazenar arquivos para registrar as informações sobre registros CSV ruins.
`charToEscapeQuoteEscaping`	`\0`	O caractere usado para escapar do caractere usado para escapar das citações. Por exemplo, para o seguinte registro: `[ " a\\", b ]`: Se o caractere para escapar do `'\'` não estiver definido, o registro não será analisado. O analisador lerá os caracteres: `[a],[\],["],[,],[ ],[b]` e lançará um erro porque não consegue encontrar uma aspa de fechamento. Se o caractere para escapar do `'\'` for definido como `'\'`, o registro será lido com valores de 2: `[a\]` e `[b]`.
`columnNameOfCorruptRecord`	`_corrupt_record`	Compatível com Auto Loader. Não suportado para `COPY INTO` (legado). A coluna destinada a armazenar registros malformados que não podem ser analisados. Se o `mode` para análise for definido como `DROPMALFORMED`, esta coluna ficará vazia.
`comment`	`\0`	Define o caractere que representa um comentário de linha quando encontrado no início de uma linha de texto. Use `'\0'` para desativar a omissão de comentários.
`dateFormat`	`yyyy-MM-dd`	O formato para analisar cadeias de caracteres de data.
`emptyValue`	Cadeias vazias	Representação de string de um valor vazio.
`enableDateTimeParsingFallback`	`false`	Indica se deve recorrer ao comportamento de análise de data e hora legado quando um valor não puder ser analisado com o formato especificado. Quando `false`, falhas de análise geram um erro ou produzem nulo dependendo de `mode`.
`encoding` ou `charset`	`UTF-8`	O nome da codificação dos arquivos CSV. Consulte `java.nio.charset.Charset` para obter a lista de opções. `UTF-16` e `UTF-32` não podem ser utilizados quando `multiline` é `true`.
`enforceSchema`	`true`	Se deve aplicar à força o esquema especificado ou inferido aos arquivos CSV. Se a opção estiver habilitada, os cabeçalhos de arquivos CSV serão ignorados. Essa opção é ignorada por padrão ao usar o Auto Loader para resgatar dados e permitir a evolução do esquema.
`escape`	`\`	O caractere de escape a ser usado ao analisar os dados.
`extension`	`csv`	A extensão de nome de arquivo esperada. Arquivos sem essa extensão são filtrados durante a leitura.
`failOnUnknownFields`	`false`	Indica se a operação deve falhar quando o registro CSV contiver colunas não presentes no esquema. Quando `false`, colunas não reconhecidas são descartadas silenciosamente ou recuperadas dependendo de `rescuedDataColumn`.
`failOnWidenedFields`	`false`	Indica se a análise deve falhar quando o valor de um campo não puder ser interpretado como o tipo de esquema declarado sem ampliação (widering). Quando `false`, os valores ampliados por tipo são silenciosamente recuperados dependendo de `rescuedDataColumn`. A configuração `failOnUnknownFields=true` pode mascarar os efeitos desta opção.
`header`	`false`	Se os arquivos CSV contêm um cabeçalho. O Auto Loader pressupõe que os arquivos tenham cabeçalhos ao inferir o esquema.
`ignoreLeadingWhiteSpace`	`false`	Se deve ignorar os principais espaços em branco para cada valor analisado.
`ignoreTrailingWhiteSpace`	`false`	Se devem ser ignorados os espaços em branco à direita para cada valor analisado.
`inferSchema`	`false`	Se deve inferir os tipos de dados dos registros CSV analisados ou assumir que todas as colunas são de `StringType`. Exige um passe adicional sobre os dados se configurado para `true`. Para o Auto Loader, use `cloudFiles.inferColumnTypes` em vez disso.
`inputBufferSize`	`1048576` (1 MB)	O tamanho do buffer em bytes para o analisador CSV. Útil para otimizar o uso de memória ao analisar arquivos CSV grandes. Valores válidos: números inteiros positivos.
`lineSep`	Nenhum, que abrange `\r`, `\r\n` e `\n`	Uma string entre dois registros CSV consecutivos.
`locale`	`US`	Um identificador `java.util.Locale`. Influencia a data padrão, o carimbo de data e a análise decimal dentro do CSV.
`maxCharsPerColumn`	`-1`	Número máximo de caracteres esperados em um valor a ser analisado. Pode ser usado para evitar erros de memória. O valor padrão é `-1`, o que significa ilimitado. Valores válidos: números inteiros positivos ou `-1` para ilimitado.
`maxColumns`	`20480`	O limite máximo de colunas que um registro pode ter. Valores válidos: números inteiros positivos.
`mergeSchema`	`false`	Se deve inferir o esquema em vários arquivos e mesclar o esquema de cada arquivo. Habilitado por padrão para o Auto Loader ao inferir o esquema.
`mode`	`PERMISSIVE`	Modo de análise sintática para lidar com registros malformados. Valores válidos: `PERMISSIVE`, `DROPMALFORMED`, `FAILFAST`.
`multiLine`	`false`	Se os registros CSV abrangem várias linhas.
`nanValue`	`NaN`	A representação de string de um valor não numérico ao analisar colunas `FloatType` e `DoubleType` .
`negativeInf`	`-Inf`	A representação de string do infinito negativo ao analisar colunas `FloatType` ou `DoubleType`.
`nullValue`	Cadeias vazias	Representação de string de um valor nulo.
`parserCaseSensitive` (obsoleto)	`false`	Durante a leitura de arquivos, verifique se as colunas declaradas no cabeçalho devem ser alinhadas com o esquema com diferenciação de maiúsculas e minúsculas. Isso é `true` por padrão para o Auto Loader. As colunas que diferem por maiúsculas e minúsculas serão resgatadas no `rescuedDataColumn` se habilitadas. Esta opção foi preterida a favor de `readerCaseSensitive`.
`positiveInf`	`Inf`	A representação de string do infinito positivo ao analisar colunas `FloatType` ou `DoubleType`.
`preferDate`	`true`	Tenta inferir strings como datas em vez de carimbo de data/hora quando possível. Você também deve usar a inferência de esquema, habilitando `inferSchema` ou usando `cloudFiles.inferColumnTypes` com o Auto Loader.
`quote`	`"`	O caractere usado para escapar de valores onde o delimitador de campo faz parte do valor.
`readerCaseSensitive`	`true`	Especifica o comportamento de diferenciação entre maiúsculas e minúsculas quando `rescuedDataColumn` está ativado. Se verdadeiro, recupere as colunas de dados cujos nomes diferem em maiúsculas e minúsculas do esquema. Quando falso, leia os dados sem diferenciar maiúsculas de minúsculas.
`rescuedDataColumn`	Nenhuma	Determinar se todos os dados que não puderam ser analisados devido a: incompatibilidade de tipo de dados e incompatibilidade de esquema (incluindo maiúsculas e minúsculas nas colunas) devem ser coletados em uma coluna separada. Esta coluna é incluída por default ao usar Auto Loader. Para obter mais detalhes, consulte O que é a coluna de dados recuperados? `COPY INTO` (legado) não suporta a coluna de dados recuperados porque você não pode definir manualmente o esquema usando `COPY INTO`. A Databricks recomenda o uso do Auto Loader para a maioria dos cenários de ingestão.
`sep` ou `delimiter`	`,`	A string separadora entre colunas.
`singleVariantColumn`	Nenhuma	Quando definido para um nome de coluna, lê o registro CSV inteiro em uma única coluna `VariantType` com esse nome, em vez de analisar cada campo em sua própria coluna. Requer `header=true`.
`skipRows`	`0`	Número de linhas do início do arquivo CSV que devem ser ignoradas (incluindo linhas comentadas e vazias). Se `header` for verdadeiro, o cabeçalho será a primeira linha não ignorada e não comentada. Valores válidos: números inteiros positivos ou 0.
`timeFormat`	`HH:mm:ss`	O formato para analisar os valores da coluna `TimeType` .
`timestampFormat`	`yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]`	O formato para analisar cadeias de caracteres de carimbo de data/hora.
`timestampNTZFormat`	`yyyy-MM-dd'T'HH:mm:ss[.SSS]`	O formato para analisar timestamps sem fuso horário (`TimestampNTZType`) strings.
`timeZone`	Nenhuma	O `java.time.ZoneId` a ser usado ao analisar carimbos de data/hora e datas.
`unescapedQuoteHandling`	`STOP_AT_DELIMITER`	A estratégia para lidar com cotações sem escape. Opções permitidas: `STOP_AT_CLOSING_QUOTE`: Caso sejam encontradas aspas não escapadas na entrada, acumule o caractere de aspas e continue a análise do valor como um valor entre aspas, até encontrar uma aspa de fechamento. `BACK_TO_DELIMITER`: Se citações sem formato forem encontradas na entrada, considere o valor como um valor sem aspas. Isto fará com que o analisador acumule todos os caracteres do valor analisado atual até que o delimitador definido por `sep` seja localizado. Se nenhum delimitador for encontrado no valor, o analisador continuará acumulando caracteres da entrada até encontrar um delimitador ou o fim da linha. `STOP_AT_DELIMITER`: Se citações sem formato forem encontradas na entrada, considere o valor como um valor sem aspas. Isso fará com que o analisador acumule todos os caracteres até que o delimitador definido por `sep` ou um final de linha seja encontrado na entrada. `SKIP_VALUE`: Se citações sem formato forem encontradas na entrada, o conteúdo analisado para o valor fornecido será ignorado (até que o próximo delimitador seja encontrado) e o valor definido em `nullValue` será produzido. `RAISE_ERROR`: Se forem encontradas aspas sem escape na entrada, um `TextParsingException` será lançado.

Excel

Chave	Padrão	Descrição
`dataAddress`	Nenhuma	O intervalo de células a ser lido na sintaxe do Excel. Se omitido, lê todas as células válidas da primeira planilha. Use `"SheetName!C5:H10"` para ler um intervalo de uma planilha nomeada, `"C5:H10"` para ler um intervalo da primeira planilha ou `"SheetName"` para ler todos os dados de uma planilha específica.
`headerRows`	`0`	Número de linhas iniciais a serem usadas como cabeçalhos de nome de coluna. Quando `dataAddress` é especificado, isso se aplica ao intervalo de células. Quando `0`, os nomes das colunas são gerados automaticamente como `_c1`, `_c2`, `_c3`, etc. Valores válidos: `0`, `1`.
`operation`	`readSheet`	As operações a serem realizadas na planilha Excel . Valores válidos: `readSheet` (lê dados de uma planilha), `listSheets` (retorna uma estrutura com os campos `sheetIndex: long` e `sheetName: String` para cada planilha).
`timestampNTZFormat`	`yyyy-MM-dd'T'HH:mm:ss[.SSS]`	Cadeias de formatação personalizadas para valores de carimbo de data/hora sem fuso horário armazenados como strings no Excel. Os formatos de data personalizados seguem os formatos definidos em Datetime patterns.
`dateFormat`	`yyyy-MM-dd`	Cadeias de formato personalizadas para valores de string lidos como `Date`. Os formatos de data personalizados seguem os formatos definidos em Datetime patterns.

JSON

Chave	Padrão	Descrição
`allowBackslashEscapingAnyCharacter`	`false`	Se deve permitir que barras invertidas () sejam usadas para escapar qualquer caractere que a suceda.Se não estiver habilitado, somente caracteres que são explicitamente listados pela especificação JSON podem ser escapados.
`allowComments`	`false`	Se deve permitir ou não o uso de comentários no estilo Java, C e C++ (variedades `'/'`, `'*'` e `'//'`) no conteúdo analisado.
`allowNonNumericNumbers`	`true`	Se o conjunto de tokens não é um número (`NaN`) deve ser permitido como valores numéricos flutuantes legais.
`allowNumericLeadingZeros`	`false`	Se é permitido permitir que números inteiros comecem com zeros adicionais (ignoráveis) (por exemplo, `000001`).
`allowSingleQuotes`	`true`	Se deve ser permitido o uso de aspas simples (apóstrofo, caractere `'\'`) para citar strings (nomes e valores de String).
`allowUnquotedControlChars`	`false`	Permitir ou não que as strings JSON contenham caracteres de controle sem escape (caracteres ASCII com valor menor que a 32, incluindo caracteres de tabulação e de avanço de linha).
`allowUnquotedFieldNames`	`false`	Se deve ser permitido o uso de nomes de campos sem aspas, o que é permitido pelo JavaScript, mas não pela especificação JSON.
`alternateVariantEncoding`	Nenhuma	A codificação usada para os valores Variant no JSON de origem. Defina como `Z85` para decodificar valores Variant que foram codificados em Base85 em vez de armazenados como JSON embutido.
`badRecordsPath`	Nenhuma	O caminho para armazenar arquivos que registram informações sobre registros JSON inválidos. O uso da opção `badRecordsPath` em uma fonte de dados baseada em arquivo apresenta as seguintes limitações: Não é transacional e pode levar a resultados inconsistentes. Erros transitórios são tratados como falhas.
`columnNameOfCorruptRecord`	`_corrupt_record`	A coluna para armazenar registros que estão malformados e não podem ser analisados. Se o `mode` para análise estiver definido como `DROPMALFORMED`, esta coluna estará vazia.
`dateFormat`	`yyyy-MM-dd`	O formato para analisar cadeias de caracteres de data.
`dropFieldIfAllNull`	`false`	Se deve ignorar colunas de todos os valores nulos ou matrizes e estruturas vazias durante a inferência do esquema.
`encoding` ou `charset`	`UTF-8`	O nome da codificação dos arquivos JSON. Consulte `java.nio.charset.Charset` para obter uma lista de opções. Você não pode usar `UTF-16` e `UTF-32` quando `multiline` for `true`.
`inferTimestamp`	`false`	Se deve tentar inferir strings de carimbo de data/hora como `TimestampType`. Quando definido como `true`, a inferência de esquema pode demorar consideravelmente mais. Você deve habilitar `cloudFiles.inferColumnTypes` para usar com o Auto Loader.
`lineSep`	Nenhum, que abrange `\r`, `\r\n` e `\n`	Uma string entre dois registros JSON consecutivos.
`locale`	`US`	Um identificador `java.util.Locale`. Influencia a data padrão, o carimbo de data e a análise decimal dentro do JSON.
`maxNestingDepth`	`500`	A profundidade máxima de aninhamento permitida para objetos e matrizes JSON. Aumente esse valor para documentos profundamente aninhados. Valores válidos: números inteiros positivos.
`maxNumLen`	`1000`	O comprimento máximo dos tokens numéricos na entrada JSON. Aumente esse valor para JSON com literais numéricos grandes. Valores válidos: números inteiros positivos.
`maxStringLen`	Ilimitadas	O comprimento máximo dos valores de string na entrada JSON . Configure para limitar o uso de memória ao analisar JSON com strings grandes. Valores válidos: números inteiros positivos.
`mode`	`PERMISSIVE`	Modo de análise sintática para lidar com registros malformados. Valores válidos: `PERMISSIVE`, `DROPMALFORMED`, `FAILFAST`.
`multiLine`	`false`	Se os registros JSON abrangem múltiplas linhas.
`prefersDecimal`	`false`	Tenta inferir strings como `DecimalType` ao invés de float ou tipo duplo quando possível. Você também deve usar a inferência de esquema, habilitando `inferSchema` ou usando `cloudFiles.inferColumnTypes` com o Auto Loader.
`primitivesAsString`	`false`	Se inferir tipos primitivos como números e booleanos como `StringType`.
`readerCaseSensitive`	`true`	Especifica o comportamento de diferenciação entre maiúsculas e minúsculas quando `rescuedDataColumn` está ativado. Se verdadeiro, recupere as colunas de dados cujos nomes diferem em maiúsculas e minúsculas do esquema. Quando falso, leia os dados sem diferenciar maiúsculas de minúsculas. Disponível no Databricks Runtime 13.3 e versões superiores.
`rescuedDataColumn`	Nenhuma	Decidiu-se se todos os dados que não puderam ser analisados devido a uma incompatibilidade de tipo de dados ou de esquema (incluindo maiúsculas e minúsculas nas colunas) devem ser coletados em uma coluna separada. Esta coluna é incluída por default ao usar Auto Loader. Para obter mais detalhes, consulte O que é a coluna de dados recuperados? `COPY INTO` (legado) não suporta a coluna de dados recuperados porque você não pode definir manualmente o esquema usando `COPY INTO`. A Databricks recomenda o uso do Auto Loader para a maioria dos cenários de ingestão.
`singleVariantColumn`	Nenhuma	Indica se o documento JSON completo deve ser ingerido e analisado em uma única coluna Variant com as strings especificadas como nome da coluna. Caso não sejam definidos, os campos JSON são inseridos em suas próprias colunas. Valores válidos: quaisquer sequências de caracteres.
`timestampFormat`	`yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]`	O formato para analisar cadeias de caracteres de carimbo de data/hora.
`timestampNTZFormat`	`yyyy-MM-dd'T'HH:mm:ss[.SSS]`	O formato para analisar timestamps sem fuso horário (`TimestampNTZType`) strings.
`timeZone`	Nenhuma	O `java.time.ZoneId` a ser usado ao analisar carimbos de data/hora e datas.
`upgradeExceptionAsBadRecord`	`false`	Definir se as exceções de atualização de tipo (por exemplo, quando um valor não pode ser ampliado para o tipo de coluna declarado) devem ser tratadas como registros inválidos em vez de lançar uma exceção.

ORC

Chave	Padrão	Descrição
`mergeSchema`	`false`	Se deve inferir o esquema em vários arquivos e mesclar o esquema de cada arquivo.

Parquet

Chave	Padrão	Descrição
`datetimeRebaseMode`	`LEGACY`	Controla o rebase dos valores DATE e TIMESTAMP entre calendários gregoriano juliano e proléptico. Valores válidos: `EXCEPTION`, `LEGACY` e `CORRECTED`.
`int96RebaseMode`	`LEGACY`	Controla o rebase dos valores do timestamp INT96 entre calendários gregoriano juliano e proléptico. Valores válidos: `EXCEPTION`, `LEGACY` e `CORRECTED`.
`mergeSchema`	`false`	Se deve inferir o esquema em vários arquivos e mesclar o esquema de cada arquivo.
`readerCaseSensitive`	`true`	Especifica o comportamento de diferenciação entre maiúsculas e minúsculas quando `rescuedDataColumn` está ativado. Se verdadeiro, recupere as colunas de dados cujos nomes diferem em maiúsculas e minúsculas do esquema. Quando falso, leia os dados sem diferenciar maiúsculas de minúsculas.
`rescuedDataColumn`	Nenhuma	Determinar se todos os dados que não puderam ser analisados devido a: incompatibilidade de tipo de dados e incompatibilidade de esquema (incluindo maiúsculas e minúsculas nas colunas) devem ser coletados em uma coluna separada. Esta coluna é incluída por default ao usar Auto Loader. Para obter mais detalhes, consulte O que é a coluna de dados recuperados? `COPY INTO` (legado) não suporta a coluna de dados recuperados porque você não pode definir manualmente o esquema usando `COPY INTO`. A Databricks recomenda o uso do Auto Loader para a maioria dos cenários de ingestão.

Texto

Chave	Padrão	Descrição
`encoding`	`UTF-8`	O nome da codificação do separador de linhas do arquivo TEXT. Para uma lista de opções, veja `java.nio.charset.Charset`. O conteúdo do arquivo não é afetado por esta opção e é lido tal como está.
`lineSep`	Nenhum, que abrange `\r`, `\r\n` e `\n`	Uma string entre dois registros TEXT consecutivos.
`wholeText`	`false`	Se deve ler um arquivo como um único registro.

XML

Chave	Padrão	Descrição
`rowTag`	Nenhuma	A tag de linha dos arquivos XML a serem tratados como uma linha. No exemplo XML `<books> <book><book>...<books>`, o valor apropriado é `book`. Esta é uma opção obrigatória.
`samplingRatio`	`1.0`	Define a fração de linhas usadas para inferência de esquema. As funções integradas XML ignoram esta opção. Valores válidos: `0.0` a `1.0`.
`excludeAttribute`	`false`	Se deve ou não excluir atributos dos elementos.
`mode`	Nenhuma	Mode para lidar com registros corrompidos durante a análise sintática. `PERMISSIVE`: Para registros corrompidos, coloca as strings malformadas em um campo configurado por `columnNameOfCorruptRecord` e define os campos malformados para `null`. Para manter registros corrompidos, você pode definir um campo do tipo `string` chamado `columnNameOfCorruptRecord` em um esquema definido pelo usuário. Se um esquema não possuir o campo, os registros corrompidos serão descartados durante a análise. Ao inferir um esquema, o analisador adiciona implicitamente um campo `columnNameOfCorruptRecord` em um esquema de saída. `DROPMALFORMED`: Ignora registros corrompidos. Este modo não é compatível com funções integradas XML. `FAILFAST`: Lança uma exceção quando o analisador encontra registros corrompidos.
`inferSchema`	`true`	Se `true`, tenta inferir um tipo apropriado para cada coluna do DataFrame resultante. Se `false`, todas as colunas resultantes são do tipo `string` . As funções integradas XML ignoram esta opção.
`columnNameOfCorruptRecord`	`spark.sql.columnNameOfCorruptRecord`	Permite renomear o novo campo que contém strings malformadas criadas pelo modo `PERMISSIVE` .
`attributePrefix`	Nenhuma	O prefixo dos atributos serve para diferenciá-los dos elementos. Este será o prefixo para os nomes dos campos. O valor padrão é `_`. Pode estar vazio para leitura de XML, mas não para escrita. Isso também se aplica às opções XML do DataFrameWriter.
`valueTag`	`_VALUE`	A tag usada para os dados de caracteres dentro de elementos que também possuem atributos ou elementos filhos. O usuário pode especificar o campo `valueTag` no esquema ou ele será adicionado automaticamente durante a inferência do esquema quando dados de caracteres estiverem presentes em elementos com outros elementos ou atributos. Isso também se aplica às opções XML do DataFrameWriter.
`encoding`	`UTF-8`	Para leitura, decodifica os arquivos XML de acordo com o tipo de codificação fornecido. Para escrita, especifica a codificação (conjunto de caracteres) dos arquivos XML salvos. As funções integradas XML ignoram esta opção. Isso também se aplica às opções XML do DataFrameWriter.
`ignoreSurroundingSpaces`	`true`	Se os espaços em branco ao redor dos valores devem ser ignorados. Os dados de caracteres compostos apenas por espaços em branco são ignorados.
`rowValidationXSDPath`	Nenhuma	Caminho para um arquivo XSD opcional usado para validar o XML de cada linha individualmente. As linhas que não forem validadas serão tratadas como erros de análise sintática. O XSD não afeta o esquema de nenhuma outra forma, seja ele fornecido ou inferido.
`ignoreNamespace`	`false`	Se `true`, os prefixos de namespaces em elementos e atributos XML são ignorados. As tags `<abc:author>` e `<def:author>`, por exemplo, são tratadas como se ambas fossem apenas `<author>`. Os namespaces não podem ser ignorados no elemento `rowTag` , apenas seus filhos de leitura. A análise XML não leva em consideração o namespace, mesmo se `false`.
`timestampFormat`	`yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]`	Cadeias de formato de carimbo de data/hora personalizadas que seguem o padrão de formato de data e hora . Isso se aplica ao tipo `timestamp` . Isso também se aplica às opções XML do DataFrameWriter.
`timestampNTZFormat`	`yyyy-MM-dd'T'HH:mm:ss[.SSS]`	Cadeias de formato personalizadas para carimbo de data/hora sem fuso horário, seguindo o formato de padrão de data e hora. Isso se aplica ao tipo TimestampNTZType. Isso também se aplica às opções XML do DataFrameWriter.
`dateFormat`	`yyyy-MM-dd`	Cadeias de formato de data personalizadas que seguem o padrão de data e hora . Isso se aplica ao tipo de data. Isso também se aplica às opções XML do DataFrameWriter.
`locale`	`en-US`	Define uma localidade como uma tag de idioma no formato IETF BCP 47. Por exemplo, `locale` é usado ao analisar datas e carimbos de data/hora.
`nullValue`	string `null`	Define a representação em string de um valor nulo. Quando este valor é `null`, o analisador não grava atributos e elementos para os campos. Isso também se aplica às opções XML do DataFrameWriter.
`readerCaseSensitive`	`true`	Especifica o comportamento de diferenciação entre maiúsculas e minúsculas quando rescuedDataColumn está habilitado. Se verdadeiro, recupere as colunas de dados cujos nomes diferem em maiúsculas e minúsculas do esquema. Quando falso, leia os dados sem diferenciar maiúsculas de minúsculas.
`rescuedDataColumn`	Nenhuma	Determinar se todos os dados que não puderam ser analisados devido a uma incompatibilidade de tipo de dados e de esquema (incluindo maiúsculas e minúsculas nas colunas) devem ser coletados em uma coluna separada. Esta coluna é incluída por default ao usar Auto Loader. Para obter mais detalhes, consulte O que é a coluna de dados recuperados?. `COPY INTO` (legado) não suporta a coluna de dados recuperados porque você não pode definir manualmente o esquema usando `COPY INTO`. A Databricks recomenda o uso do Auto Loader para a maioria dos cenários de ingestão.
`singleVariantColumn`	`none`	Especifica o nome da coluna de variante única. Se esta opção for especificada para leitura, analise todo o registro XML em uma única coluna Variant com o valor da string de opção fornecida como nome da coluna. Se esta opção estiver disponível para gravação, escreva o valor da coluna Variant única em arquivos XML. Isso também se aplica às opções XML do DataFrameWriter.
`useLegacyXMLParser`	`true`	Se deve ser utilizado o analisador XML legado. O analisador sintático legado possui uma validação menos rigorosa para conteúdo malformado, mas é menos eficiente em termos de memória. Defina como `false` para optar pelo analisador default mais rigoroso.
`wildcardColName`	`xs_any`	O nome da coluna usada para capturar elementos XML que correspondem ao elemento de esquema curinga (`xs:any`). Não pode ser usado em conjunto com `rescuedDataColumn`.

Opções do DataStreamReader

Use estas opções com DataStreamReader.option() para configurar leituras de transmissão de tabelas Delta Lake e outras fontes baseadas em arquivos.

Para opções de formato de arquivo (JSON, CSV, Parquet e outros), consulte as opções do DataFrameReader.

Para opções de Auto Loader (cloudFiles.*), consulte Auto Loader.

Exemplo

O exemplo a seguir define maxFilesPerTrigger como 10 para uma tabela Delta Lake :

Python
Scala

Python
df = spark.readStream.format("delta").option("maxFilesPerTrigger", 10).load("/path/to/delta-table")

Scala
val df = spark.readStream.format("delta").option("maxFilesPerTrigger", "10").load("/path/to/delta-table")

Comum

As seguintes opções aplicam-se às tabelas Delta Lake e a outras fontes de transmissão baseadas em ficheiros.

Chave	Padrão	Descrição
`cleanSource`	`off`	Como lidar com arquivos de origem após serem processados pela transmissão. Valores válidos: `off` (nenhuma ação), `delete` (excluir permanentemente o arquivo de origem), `archive` (mover para `sourceArchiveDir`). Quando definido como `archive`, `sourceArchiveDir` também deve ser definido. Não se aplica à transmissão da tabela Delta Lake .
`fileNameOnly`	`false`	Se os arquivos já processados devem ser identificados apenas pelo nome do arquivo, em vez do caminho completo. Quando `true`, arquivos em caminhos diferentes com o mesmo nome de arquivo são tratados como o mesmo arquivo e não são reprocessados. Não se aplica à transmissão da tabela Delta Lake .
`latestFirst`	`false`	Se os arquivos modificados mais recentemente devem ser processados primeiro dentro de cada microlote. Útil quando você deseja processar os dados mais recentes o mais rápido possível. Quando `true` e `maxFilesPerTrigger` ou `maxBytesPerTrigger` estão definidos, `maxFileAge` é ignorado. Não se aplica à transmissão da tabela Delta Lake .
`maxBytesPerTrigger`	Nenhuma	Limite máximo flexível para a quantidade de dados processados por microlote. Um lote pode processar mais do que o limite se a menor unidade de entrada o exceder. Quando usado em conjunto com `maxFilesPerTrigger`, o micro-lote processa os dados até que um dos limites seja atingido primeiro. Valores válidos: números inteiros positivos. Para o Auto Loader, use `cloudFiles.maxBytesPerTrigger` em vez disso. Ver Comum.
`maxCachedFiles`	`10000`	Número máximo de arquivos não processados a serem armazenados em cache para micro-lotes subsequentes. Defina como `0` para desativar o cache. Aumente esse valor quando o diretório de origem contiver muitos arquivos novos por gatilho. Não se aplica à transmissão da tabela Delta Lake . Valores válidos: números inteiros positivos ou 0.
`maxFileAge`	`7d`	Idade máxima dos arquivos considerados para processamento, em relação ao carimbo de data/hora do arquivo modificado mais recentemente, e não à hora atual do sistema. Arquivos mais antigos que esse limite serão ignorados. Aceita strings de duração como `7d` ou `4h`. Ignorado quando `latestFirst` é `true` e `maxFilesPerTrigger` ou `maxBytesPerTrigger` está definido. Não se aplica à transmissão da tabela Delta Lake .
`maxFilesPerTrigger`	`1000` Para Delta Lake e Auto Loader. Não há limite máximo para outras fontes baseadas em arquivos.	Limite superior para o número de novos arquivos processados em cada microlote. Quando usado em conjunto com `maxBytesPerTrigger`, o micro-lote processa os dados até que um dos limites seja atingido primeiro. Valores válidos: números inteiros positivos. Para o Auto Loader, use `cloudFiles.maxFilesPerTrigger` em vez disso. Ver Comum.
`sourceArchiveDir`	Nenhuma	Caminho para o diretório de arquivos quando `cleanSource` é definido como `archive`. Os arquivos de origem são movidos para este caminho após o processamento, preservando sua estrutura de diretórios relativa. Não se aplica à transmissão da tabela Delta Lake .

Auto Loader

Use estas opções com a fonte cloudFiles para configurar Auto Loader para ingestão de transmissão a partir do armazenamento cloud . As opções específicas da fonte cloudFiles são prefixadas com cloudFiles para mantê-las em um espaço de nomes separado de outras opções de fonte de transmissão estruturada .

Comum

Chave	Padrão	Descrição
`cloudFiles.allowOverwrites`	`false`	Se permitir que alterações no arquivo do diretório de entrada substituam os dados existentes. Para ressalvas sobre a configuração, consulte "O Auto Loader processa o arquivo novamente quando ele é anexado ou sobrescrito?".
`cloudFiles.backfillInterval`	Nenhuma	O Auto Loader pode acionar preenchimentos assíncronos em um intervalo determinado. Por exemplo, `1 day` para preencher diariamente ou `1 week` para preencher semanalmente. Para obter mais informações, consulte Acionar preenchimentos regulares usando cloudFiles.backfillInterval. Não use quando `cloudFiles.useManagedFileEvents` estiver definido como `true`.
`cloudFiles.cleanSource`	`OFF`	Indica se os arquivos processados devem ser excluídos automaticamente do diretório de entrada. Quando definido como `OFF` (default), nenhum arquivo é excluído. Quando definido como `DELETE`, o Auto Loader exclui automaticamente os arquivos 30 dias após serem processados. Para isso, o Auto Loader precisa ter permissões de escrita no diretório de origem. Quando definido como `MOVE`, o Auto Loader move automaticamente os arquivos para o local especificado em `cloudFiles.cleanSource.moveDestination` 30 dias após serem processados. Para isso, o Auto Loader precisa ter permissões de escrita tanto no diretório de origem quanto no local de destino. Um arquivo é considerado processado quando possui um valor não nulo para `commit_time` no resultado da função com valor de tabela `cloud_files_state` . Veja `cloud_files_state` função com valor de tabela. A espera adicional de 30 dias após o processamento pode ser configurada usando `cloudFiles.cleanSource.retentionDuration`. Analise as seguintes considerações antes de ativar `cloudFiles.cleanSource`: Databricks não recomenda o uso desta opção se houver várias transmissões consumindo dados da origem, pois o consumidor mais rápido excluirá os arquivos e eles não serão incorporados às fontes mais lentas. Habilitar esse recurso exige que o Auto Loader mantenha um estado adicional em seu ponto de verificação, o que acarreta sobrecarga de desempenho, mas permite uma melhor observabilidade por meio da função com valor de tabela `cloud_files_state` . Veja `cloud_files_state` função com valor de tabela. `cleanSource` usa a configuração atual para decidir se deve atribuir `MOVE` ou `DELETE` a um determinado arquivo. Por exemplo, suponha que a configuração era `MOVE` quando o arquivo foi processado originalmente, mas foi alterada para `DELETE` quando o arquivo se tornou um candidato à limpeza 30 dias depois. Nesse caso, o comando cleanSource irá excluir o arquivo. Não há garantia de que os arquivos serão limpos assim que o `retentionDuration` expirar. Para manter os custos baixos, Auto Loader exclui arquivos simultaneamente ao processamento da transmissão e é encerrado assim que o processamento da transmissão for concluído ou for finalizado. Os arquivos que eram candidatos à limpeza, mas não puderam ser limpos durante o processamento da transmissão, serão coletados na próxima execução Auto Loader . Disponível no Databricks Runtime 16.4 e versões superiores.
`cloudFiles.cleanSource.retentionDuration`	`30 days`	Tempo de espera antes que os arquivos processados se tornem candidatos ao arquivamento com `cleanSource`. Deve ser maior que 7 dias para `DELETE`. Não há restrição mínima para `MOVE`. O valor é uma string do tipo CalendarInterval . Por exemplo, `"14 days"`, `"30 days"`, `"2 weeks"` ou `"1 month"`. Disponível no Databricks Runtime 16.4 e versões superiores.
`cloudFiles.cleanSource.moveDestination`	Nenhuma	Caminho para arquivar os arquivos processados quando `cloudFiles.cleanSource` estiver definido como `MOVE`. Isso pode ser um caminho de armazenamento cloud ou um caminho de volumeUnity Catalog (por exemplo, `/Volumes/my_catalog/my_schema/my_volume/archive/`). O local da mudança deve: Não pode ser um diretório filho do diretório de origem. Se você colocar o destino da movimentação dentro do diretório de origem, os arquivos arquivados serão reinseridos. Esteja no mesmo local externo, volume ou ponto de montagem DBFS que a origem. Movimentações entre buckets e contêineres não são suportadas e resultam em erro. O Auto Loader precisa ter permissão de escrita neste diretório. Disponível no Databricks Runtime 16.4 e versões superiores.
`cloudFiles.format`	Nenhuma (opção obrigatória)	O formato do arquivo de dados no caminho de origem. Os valores válidos incluem: `avro`Arquivos Avro `binaryFile`Arquivos binários `csv`Arquivos CSV `json`Arquivos JSON `orc`Arquivos ORC `parquet`Arquivos Parquet `text`Arquivos TXT `xml`Arquivos XML
`cloudFiles.includeExistingFiles`	`true`	Se os arquivos existentes devem ser incluídos no caminho de entrada do processamento da transmissão ou se devem ser processados somente os novos arquivos que chegarem após a configuração inicial. Essa opção é avaliada somente quando você inicia uma transmissão pela primeira vez. Alterar esta opção após reiniciar a transmissão não tem efeito.
`cloudFiles.inferColumnTypes`	`false`	Se deve ou não inferir os tipos exatos das colunas ao utilizar a inferência de esquema. Por default, as colunas são inferidas como strings ao inferir conjuntos de dados JSON e CSV . Consulte a seção sobre inferência de esquema para obter mais detalhes.
`cloudFiles.maxBytesPerTrigger`	Nenhuma	O número máximo de novos bytes a serem processados em cada gatilho. Você pode especificar uma sequência de bytes, como `10g` , para limitar cada microlote a 10 GB de dados. Este é um máximo flexível. Se você tiver arquivos de 3 GB cada, o Databricks processará 12 GB em um microlote. Quando usado em conjunto com `cloudFiles.maxFilesPerTrigger`, o Databricks consome até o limite inferior de `cloudFiles.maxFilesPerTrigger` ou `cloudFiles.maxBytesPerTrigger`, o que for atingido primeiro. Esta opção não tem efeito quando usada com `Trigger.Once()` (`Trigger.Once()` está obsoleto). No Databricks Runtime 18.0 e versões superiores, essa opção é configurada dinamicamente e não precisa ser definida manualmente.
`cloudFiles.maxFileAge`	Nenhuma	Por quanto tempo um evento de arquivo é rastreado para fins de desduplicação. A Databricks não recomenda ajustar esse parâmetro, a menos que você esteja ingerindo dados na ordem de milhões de arquivos por hora. Consulte a seção sobre acompanhamento de eventos de arquivo para obter mais detalhes. Ajustar `cloudFiles.maxFileAge` de forma muito agressiva pode causar problemas de qualidade de dados, como ingestão duplicada ou arquivos ausentes. Portanto, a Databricks recomenda uma configuração conservadora para `cloudFiles.maxFileAge`, como 90 dias, que é semelhante ao que soluções comparáveis de ingestão de dados recomendam.
`cloudFiles.maxFilesPerTrigger`	`1000`	O número máximo de novos arquivos a serem processados em cada gatilho. Quando usado junto com `cloudFiles.maxBytesPerTrigger`, o Databricks consome até o limite mais baixo de `cloudFiles.maxFilesPerTrigger` ou `cloudFiles.maxBytesPerTrigger`, o que for atingido primeiro. Essa opção não tem efeito quando usada com `Trigger.Once()` (descontinuada). No Databricks Runtime 18.0 e versões superiores, essa opção é configurada dinamicamente e não precisa ser definida manualmente.
`cloudFiles.partitionColumns`	Nenhuma	Uma lista separada por vírgulas das colunas de partição no estilo Hive que você gostaria de inferir da estrutura de diretórios dos arquivos. As colunas de partição no estilo Hive são pares key-valor combinados por um sinal de igualdade como `<base-path>/a=x/b=1/c=y/file.format`. Neste exemplo, as colunas de partição são `a`, `b` e `c`. Por default essas colunas são adicionadas automaticamente ao seu esquema se você estiver usando inferência de esquema e fornecer o `<base-path>` para carregar os dados. Se você fornecer um esquema, o Auto Loader espera que essas colunas estejam incluídas no esquema. Se você não quiser essas colunas como parte do seu esquema, você pode especificar `""` para ignorar essas colunas. Além disso, você pode usar essa opção quando quiser que as colunas sejam inferidas a partir do caminho do arquivo em estruturas de diretório complexas, como no exemplo abaixo: `<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` Especificar `cloudFiles.partitionColumns` como `year,month,day` retorna `year=2022` para `file1.csv`, mas as colunas `month` e `day` são `null`. `month` e `day` são analisados corretamente para `file2.csv` e `file3.csv`.
`cloudFiles.schemaEvolutionMode`	`addNewColumns` Quando nenhum esquema for fornecido, `none` caso contrário	O modo de evolução do esquema à medida que novas colunas são descobertas nos dados. Por default, as colunas são inferidas como strings ao inferir um conjunto de dados JSON . Consulte a seção sobre a evolução do esquema para obter mais detalhes.
`cloudFiles.schemaHints`	Nenhuma	Informações de esquema que você fornece ao Auto Loader durante a inferência de esquema. Consulte as dicas do esquema para obter mais detalhes.
`cloudFiles.schemaLocation`	Nenhum (necessário para inferir o esquema)	Local para armazenar o esquema inferido e as alterações subsequentes. Consulte a seção sobre inferência de esquema para obter mais detalhes.
`cloudFiles.useStrictGlobber`	`false`	Se deve ser utilizado um globber estrito que corresponda ao comportamento de globbing default de outras fontes de arquivos no Apache Spark. Consulte Padrões comuns de carregamento de dados para obter mais detalhes. Disponível no Databricks Runtime 12.2 LTS e versões superiores.
`cloudFiles.validateOptions`	`true`	Se deve validar as opções do Auto Loader e retornar um erro para opções desconhecidas ou inconsistentes.

Listagem de diretório

Chave	Padrão	Descrição
`cloudFiles.useIncrementalListing` (obsoleto)	`auto` no Databricks Runtime 17.2 e abaixo, `false` no Databricks Runtime 17.3 e acima	Este recurso foi descontinuado. A Databricks recomenda o uso do modo de notificação de arquivo com eventos de arquivo em vez de `cloudFiles.useIncrementalListing`. Se deve usar a listagem incremental em vez da listagem completa no modo de listagem de diretório. Por default, Auto Loader faz o possível para detectar automaticamente se um determinado diretório é aplicável à listagem incremental. Você pode usar explicitamente a listagem incremental ou usar a listagem completa do diretório definindo-a como `true` ou `false` respectivamente. Habilitar incorretamente a listagem incremental em um diretório sem ordem lexicográfica impede que o Auto Loader descubra novos arquivos. Funciona com o Azure Data Lake Storage (`abfss://`), S3 (`s3://`) e GCS (`gs://`). Disponível no Databricks Runtime 9.1 LTSe acima. Valores disponíveis: `auto`, `true`, `false`

Chave

Padrão

Descrição

cloudFiles.useIncrementalListing (obsoleto)

auto no Databricks Runtime 17.2 e abaixo, false no Databricks Runtime 17.3 e acima

Este recurso foi descontinuado. A Databricks recomenda o uso do modo de notificação de arquivo com eventos de arquivo em vez de cloudFiles.useIncrementalListing.

Se deve usar a listagem incremental em vez da listagem completa no modo de listagem de diretório. Por default, Auto Loader faz o possível para detectar automaticamente se um determinado diretório é aplicável à listagem incremental. Você pode usar explicitamente a listagem incremental ou usar a listagem completa do diretório definindo-a como true ou false respectivamente.

Habilitar incorretamente a listagem incremental em um diretório sem ordem lexicográfica impede que o Auto Loader descubra novos arquivos.

Funciona com o Azure Data Lake Storage (abfss://), S3 (s3://) e GCS (gs://).

Disponível no Databricks Runtime 9.1 LTSe acima. Valores disponíveis: auto, true, false

Notificação de arquivo

Para obter informações sobre como configurar o modo de notificação de arquivos, incluindo permissões cloud necessárias, instruções de configuração e métodos de autenticação, consulte Configurar transmissões Auto Loader no modo de notificação de arquivos.

Chave	Padrão	Descrição
`cloudFiles.fetchParallelism`	`1`	Número de segmentos a serem usados ao buscar mensagens do serviço de enfileiramento. Não use quando `cloudFiles.useManagedFileEvents` estiver definido como `true`.
`cloudFiles.pathRewrites`	Nenhuma	Necessário apenas se você especificar um `queueUrl` que recebe notificações de arquivos de vários buckets S3 e você quiser usar pontos de montagem configurados para acessar dados nesses contêineres. Use esta opção para reescrever o prefixo do caminho `bucket/key` com o ponto de montagem. Somente os prefixos podem ser reescritos. Por exemplo, para a configuração `{"<databricks-mounted-bucket>/path": "dbfs:/mnt/data-warehouse"}`, o caminho `s3://<databricks-mounted-bucket>/path/2017/08/fileA.json` é reescrito para `dbfs:/mnt/data-warehouse/2017/08/fileA.json`. Não use quando `cloudFiles.useManagedFileEvents` estiver definido como `true`.
`cloudFiles.resourceTag`	Nenhuma	Uma série de pares de tags de valor chave para ajudar a associar e identificar recursos relacionados, por exemplo: `cloudFiles.option("cloudFiles.resourceTag.myFirstKey", "myFirstValue")` `.option("cloudFiles.resourceTag.mySecondKey", "mySecondValue")` Para obter mais informações sobre AWS, consulte tagsde alocação de custosAmazon SQS e Configurando tags para um tópico Amazon SNS. (1) Para mais informações sobre Azure, consulte Filas de Nomeação e Metadados e a cobertura de `properties.labels` em Inscrição de Evento. Auto Loader armazena esses pares tag key-valor em JSON como rótulo. (1) Para obter mais informações sobre GCP, consulte Relatório de uso com rótulo. (1) Não use quando `cloudFiles.useManagedFileEvents` estiver definido como `true`. Em vez disso, defina tags de recurso usando o console do provedor cloud .
`cloudFiles.useManagedFileEvents`	`false`	Quando definido como `true`, o Auto Loader usa o serviço de eventos de arquivo para descobrir arquivos em seu local externo. Você pode usar essa opção somente se o caminho de carregamento estiver em um local externo com eventos de arquivo ativados. Consulte Usar o modo de notificação de arquivos com eventos de arquivos. Os eventos de arquivo proporcionam desempenho de nível de notificação na descoberta de arquivos, pois o Auto Loader consegue descobrir novos arquivos após a última execução. Diferentemente da listagem de diretórios, esse processo não precisa listar todos os arquivos do diretório. Existem algumas situações em que o Auto Loader usa a listagem de diretórios mesmo quando a opção de eventos de arquivo está ativada: Durante o carregamento inicial, quando `includeExistingFiles` é definido como `true`, uma listagem completa do diretório é realizada para descobrir todos os arquivos que estavam presentes no diretório antes do início Auto Loader . O serviço de eventos de arquivos otimiza a descoberta de arquivos armazenando em cache os arquivos criados mais recentemente. Se a execução Auto Loader for infrequente, esse cache pode expirar e Auto Loader recorrerá à listagem de diretórios para descobrir arquivos e atualizar o cache. Para evitar esse cenário, invoque o Auto Loader pelo menos uma vez a cada sete dias. Consulte Quando o Auto Loader com eventos de arquivo usa a listagem de diretórios? Para obter uma lista completa das situações em que o Auto Loader usa a listagem de diretórios com esta opção. Disponível no Databricks Runtime 14.3 LTS e versões superiores.
`cloudFiles.listOnStart`	`false`	Quando definido como `true`, Auto Loader realiza uma listagem completa do diretório quando a transmissão começa, em vez de começar com os tokens de continuação no ponto de verificação. Use esta opção para recuperar de erros, como `CF_MANAGED_FILE_EVENTS_INVALID_CONTINUATION_TOKEN`. Veja Como me recuperar de um erro `CF_MANAGED_FILE_EVENTS_INVALID_CONTINUATION_TOKEN` ?.
`cloudFiles.useNotifications`	`false`	Ativar ou desativar o modo de notificação de arquivos para detectar a presença de novos arquivos. Se `false`, use o modo de listagem de diretório. Consulte Comparar os modos de detecção de arquivos do Auto Loader. Não use quando `cloudFiles.useManagedFileEvents` estiver definido como `true`.

(1) O Auto Loader adiciona os seguintes pares de tags de chave-valor por padrão com base no melhor esforço:

vendor: Databricks
path: O local de onde os dados são carregados. Indisponível no GCP devido a limitações de rotulagem.
checkpointLocationLocalização do posto de controle da transmissão. Não disponível no GCP devido a limitações de rótulo.
streamId: um identificador globalmente exclusivo para a transmissão.

Databricks reserva esses nomes key e você não pode sobrescrever seus valores.

específico da nuvem

Auto Loader oferece opções para configurar a infraestrutura cloud para o modo de notificação de arquivos. Para obter informações sobre as permissões cloud necessárias e as instruções de configuração, consulte Configurar Auto Loader transmissões no modo de notificação de arquivos.

AWS

Forneça as seguintes opções somente se você escolher cloudFiles.useNotifications = true e quiser que Auto Loader configure o serviço de notificação para você:

Chave	Padrão	Descrição
`cloudFiles.region`	A região da instância EC2	A região onde reside o bucket S3 de origem e onde você deseja criar os serviços AWS SNS e SQS.

Chave	Padrão	Descrição
`cloudFiles.restrictNotificationSetupToSameAWSAccountId`	`false`	Permitir notificações de eventos somente de buckets do AWS S3 na mesma account que o tópico do SNS. Quando ativada, Auto Loader aceita apenas notificações de eventos de buckets do AWS S3 na mesma account que o tópico do SNS. Quando `false`, a política de acesso não restringe as configurações de bucket e tópico SNS entreaccount diferentes. Isso é útil quando o tópico SNS e o caminho do bucket estão associados a contas diferentes. Disponível no Databricks Runtime 17.2 e versões superiores.

Chave

Padrão

Descrição

cloudFiles.restrictNotificationSetupToSameAWSAccountId

false

Permitir notificações de eventos somente de buckets do AWS S3 na mesma account que o tópico do SNS. Quando ativada, Auto Loader aceita apenas notificações de eventos de buckets do AWS S3 na mesma account que o tópico do SNS.

Quando false, a política de acesso não restringe as configurações de bucket e tópico SNS entreaccount diferentes. Isso é útil quando o tópico SNS e o caminho do bucket estão associados a contas diferentes.

Disponível no Databricks Runtime 17.2 e versões superiores.

Forneça a seguinte opção apenas se escolher cloudFiles.useNotifications = true e pretender que o Auto Loader utilize uma fila que já configurou:

Chave	Padrão	Descrição
`cloudFiles.queueUrl`	Nenhuma	O URL da fila SQS. Se fornecido, o Auto Loader consome diretamente os eventos dessa fila em vez de configurar seus próprios serviços AWS SNS e SQS.

opções de autenticação da AWS

Forneça a seguinte opção de autenticação para usar uma credencial de serviço do Databricks:

Chave	Padrão	Descrição
`databricks.serviceCredential`	Nenhuma	O nome da sua credencial de serviço do Databricks. Disponível no Databricks Runtime 16.1 e versões superiores.

Quando as credenciais do serviço Databricks ou a função IAM não estiverem disponíveis, você pode fornecer as seguintes opções de autenticação:

Chave	Padrão	Descrição
`cloudFiles.awsAccessKey`	Nenhuma	A ID da chave de acesso AWS para o usuário. Deve ser fornecido com `cloudFiles.awsSecretKey`.
`cloudFiles.awsSecretKey`	Nenhuma	A chave de acesso secreto da AWS para o usuário. Deve ser fornecido com `cloudFiles.awsAccessKey`.
`cloudFiles.roleArn`	Nenhuma	O ARN de uma IAM role a ser assumida, se necessário. A função pode ser assumida a partir do instance profile do seu cluster ou fornecendo credenciais com `cloudFiles.awsAccessKey` e `cloudFiles.awsSecretKey`.
`cloudFiles.roleExternalId`	Nenhuma	Um identificador a ser fornecido ao assumir uma função usando `cloudFiles.roleArn`.
`cloudFiles.roleSessionName`	Nenhuma	Um nome de sessão opcional para utilizar ao assumir um papel utilizando `cloudFiles.roleArn`.
`cloudFiles.stsEndpoint`	Nenhuma	Um ponto final opcional a ser fornecido para acessar o AWS STS ao assumir uma função utilizando o `cloudFiles.roleArn`.

Azure

Você deve fornecer valores para todas as seguintes opções se especificar cloudFiles.useNotifications = true e desejar que o Auto Loader configure os serviços de notificação para você:

Chave	Padrão	Descrição
`cloudFiles.resourceGroup`	Nenhuma	O grupo de recursos Azure no qual a account de armazenamento foi criada.
`cloudFiles.subscriptionId`	Nenhuma	O ID de inscrição Azure no qual o grupo de recursos foi criado.
`databricks.serviceCredential`	Nenhuma	O nome da sua credencial de serviço do Databricks. Disponível no Databricks Runtime 16.1 e versões superiores.

Caso as credenciais de serviço do Databricks não estejam disponíveis, você pode fornecer as seguintes opções de autenticação:

Chave	Padrão	Descrição
`cloudFiles.clientId`	Nenhuma	O ID do cliente ou o ID do aplicativo da entidade de serviço Databricks.
`cloudFiles.clientSecret`	Nenhuma	O segredo do cliente da entidade de serviço Databricks .
`cloudFiles.connectionString`	Nenhuma	A string de caracteres de conexão para a conta de armazenamento, com base na chave de acesso à conta ou na assinatura de acesso compartilhado (SAS).
`cloudFiles.tenantId`	Nenhuma	O ID do inquilino Azure no qual a entidade de serviço Databricks é criada.

Forneça a seguinte opção somente se você definir cloudFiles.useNotifications = true e quiser que o Auto Loader use uma fila existente:

Chave	Padrão	Descrição
`cloudFiles.queueName`	Nenhuma	O nome da fila do Azure. Se fornecida, a fonte de arquivos cloud consome eventos diretamente dessa fila, em vez de configurar seu próprio serviço Azure Event Grid e Queue Storage. Nesse caso, seu `databricks.serviceCredential` ou `cloudFiles.connectionString` requer apenas permissões de leitura na fila.

GCP

Auto Loader pode configurar automaticamente o serviço de notificações para você, utilizando as credenciais do serviço Databricks . A account de serviço criada com as credenciais de serviço Databricks exigirá as permissões especificadas em Configurar transmissão Auto Loader no modo de notificação de arquivo.

Chave	Padrão	Descrição
`cloudFiles.projectId`	Nenhuma	O ID do projeto ao qual o bucket do GCS pertence. A assinatura Pub/Sub do Google Cloud também foi criada dentro deste projeto.
`databricks.serviceCredential`	Nenhuma	O nome da sua credencial de serviço do Databricks. Disponível no Databricks Runtime 16.1 e versões superiores.

Caso não tenha credenciais de serviço Databricks , você pode usar diretamente sua conta do Google. Você pode configurar seu cluster para assumir uma account de serviço seguindo as instruções de configuração do serviço do Google ou fornecer as seguintes opções de autenticação diretamente:

Chave	Padrão	Descrição
`cloudFiles.client`	Nenhuma	A ID do cliente da conta do Google Service.
`cloudFiles.clientEmail`	Nenhuma	O e-mail da Conta de Serviço do Google.
`cloudFiles.privateKey`	Nenhuma	A key privada gerada para a conta do serviço do Google.
`cloudFiles.privateKeyId`	Nenhuma	O ID da key privada gerada para a conta do serviço Google.

Forneça a seguinte opção apenas se escolher cloudFiles.useNotifications = true e pretender que o Auto Loader utilize uma fila que já configurou:

Chave	Padrão	Descrição
`cloudFiles.subscription`	Nenhuma	O nome da assinatura do Google Cloud Pub/Sub. Se fornecido, a fonte de arquivos na nuvem consome eventos desta fila em vez de configurar seus próprios serviços de Notificação GCS e Google Cloud Pub/Sub.

Delta Lake

As seguintes opções se aplicam ao ler de uma tabela Delta Lake usando spark.readStream.

Chave	Padrão	Descrição
`allowSourceColumnDrop`	Nenhuma	Defina com um número de versão da tabela Delta ou `"always"` para permitir que a transmissão continue após a remoção de colunas do esquema da tabela de origem. Quando definido para um número de versão, reconhece todas as alterações de esquema até essa versão. Requer `schemaTrackingLocation`. Consulte Renomear e remover colunas com o mapeamento de colunas do Delta Lake.
`allowSourceColumnRename`	Nenhuma	Defina com um número de versão da tabela Delta ou `"always"` para permitir que a transmissão continue após as colunas serem renomeadas na tabela de origem. Quando definido para um número de versão, reconhece todas as alterações de esquema até essa versão. Requer `schemaTrackingLocation`. Consulte Renomear e remover colunas com o mapeamento de colunas do Delta Lake.
`allowSourceColumnTypeChange`	Nenhuma	Defina com um número de versão da tabela Delta ou `"always"` para permitir que a transmissão continue após a alteração dos tipos de coluna na tabela de origem. Quando definido para um número de versão, reconhece todas as alterações de esquema até essa versão. Requer `schemaTrackingLocation`. Veja Ampliação de tipo.
`excludeRegex`	Nenhuma	Um padrão de expressão regular. Os arquivos cujos caminhos correspondem ao padrão são excluídos da transmissão lida. Útil para filtrar arquivos que não estejam de acordo com a convenção de nomenclatura esperada.
`failOnDataLoss`	`true`	Se deve falhar a consulta de transmissão se os dados de origem tiverem sido excluídos devido à retenção log (`logRetentionDuration`). Defina como `false` para ignorar dados ausentes e continuar o processamento. Consulte Configurar retenção de dados para consultas de viagem do tempo.
`ignoreChanges` (obsoleto)	`false`	Disponível no Databricks Runtime 11.3 LTS e versões anteriores. Reemite arquivos de dados reescritos após operações de modificação como `UPDATE`, `MERGE INTO`, `DELETE` ou `OVERWRITE`. Linhas inalteradas podem ser emitidas juntamente com novas linhas, portanto, os consumidores subsequentes devem lidar com duplicatas. As exclusões não são propagadas para os fluxos subsequentes. Substituído por `skipChangeCommits` no Databricks Runtime 12.2 LTS e versões superiores.
`ignoreDeletes` (obsoleto)	`false`	Ignora transações que excluem dados nos limites das partições (apenas exclusões completas de partições). Não lida com exclusões, atualizações ou outras modificações que não envolvam partições. Use `skipChangeCommits` em vez disso.
`readChangeFeed` ou `readChangeData`	`false`	Indica se a leitura do feed de dados de alterações para a consulta de transmissão deve ser habilitada. Quando ativada, a transmissão emite alterações em nível de linha (inserções, atualizações e exclusões) com colunas de metadados adicionais. Consulte a seção "Usar o feed de dados de alterações do Delta Lake" no Databricks.
`schemaTrackingLocation`	Nenhuma	Caminho para um diretório onde Delta Lake rastreia as alterações de esquema para a leitura de transmissão. Necessário quando transmitido de tabelas com mapeamento de coluna ativado e usando opções `allowSourceColumn*` para lidar com a evolução do esquema. Deve estar dentro do `checkpointLocation` da consulta de transmissão. Consulte Renomear e remover colunas com o mapeamento de colunas do Delta Lake.
`skipChangeCommits`	`false`	Ignora transações que excluem ou modificam registros existentes e processa apenas as que adicionam informações. A Databricks recomenda esta opção para a maioria das cargas de trabalho que não utilizam feeds de dados de alterações. Disponível no Databricks Runtime 12.2 LTS e versões superiores. Consulte Ignorar commit de alteração upstream com `skipChangeCommits`.
`startingTimestamp`	Última versão disponível	Marca de tempo para iniciar a leitura. A transmissão lê todas as alterações de tabela confirmadas na data e hora especificadas ou posteriormente. Se o carimbo de data/hora for anterior a todos os commits disponíveis na tabela, a transmissão começará a partir do commit mais antigo disponível. Não pode ser usado em conjunto com `startingVersion`. Ignorado se o ponto de controle de transmissão já existir. Aceita strings de carimbo de data/hora como `"2019-01-01T00:00:00.000Z"` ou strings de data como `"2019-01-01"`.
`startingVersion`	Última versão disponível	Versão da tabela Delta a partir da qual iniciar a leitura. A transmissão lê todas as alterações efetuadas na versão especificada ou posteriormente. Especifique `"latest"` para começar apenas com as alterações mais recentes. Não pode ser usado em conjunto com `startingTimestamp`. Ignorado se o ponto de controle de transmissão já existir. Consulte Trabalhar com a história da tabela.
`withEventTimeOrder`	`false`	Divide a tabela inicial Snapshot em intervalos de tempo de eventos para evitar que registros sejam marcados incorretamente como eventos tardios e descartados em consultas com estado que contenham marcas d'água. Não pode ser alterado após o início do processamento inicial do Snapshot sem excluir o ponto de verificação. Disponível no Databricks Runtime 11.3 LTS e versões superiores. Consulte Processar instantâneo inicial sem descartar dados.

Opções do DataFrameWriter

Use estas opções com DataFrameWriter.option() e DataFrameWriterV2.option() para controlar como o Databricks grava os dados.

Exemplo

O exemplo a seguir define mergeSchema como True para escrever uma tabela Delta Lake:

Python
Scala

Python
df.write.format("delta").option("mergeSchema", True).saveAsTable("my_table")

Scala
df.write.format("delta").option("mergeSchema", "true").saveAsTable("my_table")

Avro

Chave	Padrão	Descrição
`avroSchema`	Nenhuma	O esquema Avro completo como uma string JSON . Use esta opção para converter tipos Spark SQL em tipos Avro específicos. Aplica-se a arquivos Avro.
`avroSchemaUrl`	Nenhuma	Uma URL que aponta para um arquivo de esquema Avro. Use em vez de `avroSchema` quando o esquema estiver armazenado externamente. Mutuamente exclusivo com `avroSchema`. Aplica-se a arquivos Avro.
`compression`	`snappy`	Codec de compressão a ser usado na gravação. Valores válidos: `uncompressed`, `deflate`, `snappy`, `bzip2`, `xz`, `zstandard`. Aplica-se a arquivos Avro.
`recordName`	`topLevelRecord`	O nome do registro de nível superior no esquema Avro de saída. Aplica-se a arquivos Avro.
`positionalFieldMatching`	`false`	Indica se a correspondência entre as colunas do esquema Spark e do esquema Avro deve ser feita por posição do campo em vez de por nome. Aplica-se a arquivos Avro.
`recordNamespace`	Cadeias vazias	O namespace para o registro de nível superior no esquema Avro de saída. Aplica-se a arquivos Avro.

Delta Lake e Iceberg Apache

Chave	Padrão	Descrição
`clusterByAuto`	`false`	Ativar ou não clustering líquido automático, em que Databricks seleciona colunas clustering com base em padrões de consulta. Válido apenas com `mode("overwrite")`. Não pode ser usado com o modo `append` . Disponível no Databricks Runtime 16.4 e versões superiores. Aplica-se ao uso clustering líquido para tabelas.
`mergeSchema`	Nenhuma	Se deve ser habilitada a evolução do esquema para as operações de gravação. Novas colunas no DataFrame de origem são adicionadas ao esquema da tabela de destino. Aplica-se a lotes e anexos de transmissão. Aplica-se à atualização do esquema da tabela.
`overwriteSchema`	Nenhuma	Se deve substituir o esquema da tabela e o particionamento ao sobrescrever. Requer `mode("overwrite")` sem `replaceWhere`. Não pode ser usado com `partitionOverwriteMode`. Aplica-se à atualização do esquema da tabela.
`partitionOverwriteMode`	Nenhuma	O modo de sobrescrita de partição. Defina este valor como `dynamic` para sobrescrever apenas as partições que contêm novos dados, deixando todas as outras partições inalteradas. Modo legado, não suportado em compute serverless ou Databricks SQL. Valores válidos: `static`, `dynamic`. Aplica-se à sobrescrita seletiva de dados com o Delta Lake.
`replaceOn`	Nenhuma	Uma expressão booleana que compara linhas na tabela de destino para substituir por linhas da consulta de origem. É possível referenciar colunas tanto da tabela de destino quanto da consulta de origem. As linhas no destino que correspondem a uma linha de origem são excluídas e substituídas. Se a origem estiver vazia, nenhuma exclusão ocorrerá. Use `targetAlias` para desambiguar referências de coluna. Disponível no Databricks Runtime 17.1 e versões superiores. Aplica-se à sobrescrita seletiva de dados com o Delta Lake.
`replaceUsing`	Nenhuma	Uma lista de nomes de colunas separados por vírgulas, usada para encontrar correspondências entre as linhas da tabela de destino e da consulta de origem. Tanto o destino quanto a origem devem conter todas as colunas listadas. As linhas no destino que correspondem a uma linha de origem na comparação de igualdade são excluídas e substituídas. Os valores `NULL` são tratados como diferentes e não corresponderão. Disponível no Databricks Runtime 16.3 e versões superiores. Aplica-se à sobrescrita seletiva de dados com o Delta Lake.
`replaceWhere`	Nenhuma	Uma expressão predicativa. Sobrescreve atomicamente apenas os registros que correspondem ao predicado. Aplica-se à sobrescrita seletiva de dados com o Delta Lake.
`targetAlias`	Nenhuma	Um alias de string para a tabela de destino. Use com `replaceOn` ou `replaceWhere` para desambiguar referências de coluna quando a condição fizer referência a colunas tanto da tabela de destino quanto da consulta de origem. Aplica-se à sobrescrita seletiva de dados com o Delta Lake.
`txnAppId`	Nenhuma	Uma string única que identifica a aplicação para escritas idempotentes em `foreachBatch` operações. Use em conjunto com `txnVersion` para garantir gravações exatamente uma vez em várias tabelas do Delta Lake. Aplica-se ao uso de `foreachBatch` para gravações de tabela idempotentes.
`txnVersion`	Nenhuma	Um número monotonicamente crescente usado como versão de transação para escritas idempotentes em operações `foreachBatch` . Use em conjunto com `txnAppId` para garantir gravações exatamente uma vez em várias tabelas do Delta Lake. Aplica-se ao uso de `foreachBatch` para gravações de tabela idempotentes.
`optimizeWrite`	Nenhuma	Indica se deseja ativar a otimização automática de gravação para esta operação de gravação. Substitui a configuração `spark.databricks.delta.optimizeWrite.enabled` . Aplica-se a "O que é Delta Lake no Databricks?".
`userMetadata`	Nenhuma	Uma sequência de caracteres definida pelo usuário é anexada aos metadados commit das operações de escrita. Visível na saída de `DESCRIBE HISTORY`. Aplica-se a Enriquecer tabelas com metadados personalizados.

CSV

Chave	Padrão	Descrição
`charToEscapeQuoteEscaping`	`\0` (não ativado)	O caractere usado para escapar do caractere de escape quando ele difere do caractere de aspas. Aplica-se a arquivos CSV (DataFrameWriter).
`compression`	`none`	Codec de compressão a ser usado na gravação. Valores válidos: `none`, `bzip2`, `gzip`, `lz4`, `snappy`, `deflate`, `zstd`. Aplica-se a arquivos CSV (DataFrameWriter).
`dateFormat`	`yyyy-MM-dd`	Cadeias de formatação para valores de coluna de data. Aplica-se a arquivos CSV (DataFrameWriter).
`emptyValue`	Cadeias vazias	As strings escritas para valores vazios (não nulos). Aplica-se a arquivos CSV (DataFrameWriter).
`encoding`	`UTF-8`	A codificação de caracteres para os arquivos de saída. Aplica-se a arquivos CSV (DataFrameWriter).
`escape`	`\`	O caractere usado para escapar valores entre aspas. Aplica-se a arquivos CSV (DataFrameWriter).
`escapeQuotes`	`true`	Indica se os caracteres de aspas devem ser escapados dentro de valores de campos entre aspas. Aplica-se a arquivos CSV (DataFrameWriter).
`header`	`false`	Indica se os nomes das colunas devem ser exibidos como a primeira linha da saída. Aplica-se a arquivos CSV (DataFrameWriter).
`ignoreLeadingWhiteSpace`	`false`	Se deve ou não remover os espaços em branco iniciais dos valores ao escrever. Aplica-se a arquivos CSV (DataFrameWriter).
`ignoreTrailingWhiteSpace`	`false`	Se deve ou não remover os espaços em branco à direita dos valores ao escrever. Aplica-se a arquivos CSV (DataFrameWriter).
`lineSep`	`\n`	As sequências de caracteres que separam as linhas entre os registros. Aplica-se a arquivos CSV (DataFrameWriter).
`locale`	`en-US`	Um identificador `java.util.Locale` . Influencia a formatação dos valores de data e hora durante a escrita.
`nullValue`	Cadeias vazias	strings escritas para valores nulos. Aplica-se a arquivos CSV (DataFrameWriter).
`quote`	`"`	O caractere usado para delimitar valores de campos que contêm o separador. Aplica-se a arquivos CSV (DataFrameWriter).
`quoteAll`	`false`	Indica se todos os valores dos campos devem ser colocados entre aspas, independentemente do conteúdo. Aplica-se a arquivos CSV (DataFrameWriter).
`sep`	`,`	O caractere delimitador de campo. Aplica-se a arquivos CSV (DataFrameWriter).
`timestampFormat`	`yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]`	As strings de formatação para os valores da coluna de carimbo de data/hora. Aplica-se a arquivos CSV (DataFrameWriter).
`timestampNTZFormat`	`yyyy-MM-dd'T'HH:mm:ss[.SSS]`	Strings de formatação para valores de coluna de carimbo de data/hora sem fuso horário (`TimestampNTZType`).

Excel

Chave	Padrão	Descrição
`dataAddress`	Nenhuma	O nome da planilha ou a célula inicial para a escrita. Se omitido, escreve em uma planilha chamada `Sheet1` começando na célula `A1`. Aceita um nome de planilha (`"SheetName"`) ou uma referência de célula única (`"SheetName!A1"`). Intervalos de células não são suportados para gravações.
`dateFormatInWrite`	`yyyy-mm-dd`	Cadeias de formatação de células Excel aplicadas às colunas `Date` . Utiliza a sintaxe de formatação do Excel.
`headerRows`	`0`	Indica se os nomes das colunas devem ser escritos como a primeira linha. Valores válidos: `0`, `1`.
`timestampNTZFormat`	`yyyy-mm-dd hh:mm:ss`	Cadeias de formatação de células Excel aplicadas às colunas `TimestampNTZ` e `Timestamp` . Utiliza a sintaxe de formatação do Excel.
`version`	`xlsx`	Versão do formato de arquivo Excel a ser gravada. Valores válidos: `xlsx`, `xls`.

JSON

Chave	Padrão	Descrição
`compression`	`none`	Codec de compressão a ser usado na gravação. Valores válidos: `none`, `bzip2`, `gzip`, `lz4`, `snappy`, `deflate`, `zstd`. Aplica-se a JSON (DataFrameWriter).
`dateFormat`	`yyyy-MM-dd`	Cadeias de formatação para valores de coluna de data. Aplica-se a JSON (DataFrameWriter).
`encoding`	`UTF-8`	A codificação de caracteres para os arquivos de saída. Aplica-se a JSON (DataFrameWriter).
`ignoreNullFields`	valor de `spark.sql.jsonGenerator.ignoreNullFields`	Indica se os campos com valores nulos devem ser omitidos da saída JSON. Aplica-se a JSON (DataFrameWriter).
`lineSep`	`\n`	As sequências de caracteres que separam as linhas entre os registros. Aplica-se a JSON (DataFrameWriter).
`locale`	`en-US`	Um identificador `java.util.Locale` . Influencia a formatação dos valores de data e hora durante a escrita.
`pretty`	`false`	Ativar ou desativar a saída JSON formatada (com recuo e várias linhas).
`sortKeys`	`false`	Indica se a chave dos objetos JSON deve ser classificada em ordem alfabética na saída. Útil para produzir resultados determinísticos.
`timestampFormat`	`yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]`	As strings de formatação para os valores da coluna de carimbo de data/hora. Aplica-se a JSON (DataFrameWriter).
`timestampNTZFormat`	`yyyy-MM-dd'T'HH:mm:ss[.SSS]`	Strings de formatação para valores de coluna de carimbo de data/hora sem fuso horário (`TimestampNTZType`).
`writeNonAsciiCharacterAsCodePoint`	`false`	Indica se os caracteres não ASCII devem ser codificados como sequências de escape Unicode `\uXXXX` em vez de caracteres UTF-8 literais na saída.

ORC

Chave	Padrão	Descrição
`compression`	`zstd`	Codec de compressão a ser usado na gravação. Valores válidos: `none`, `uncompressed`, `snappy`, `zlib`, `lzo`, `zstd`, `lz4`, `brotli`. Aplica-se a orc (DataFrameWriter).

Parquet

Chave	Padrão	Descrição
`compression`	`snappy`	Codec de compressão a ser usado na gravação. Valores válidos: `none`, `uncompressed`, `snappy`, `gzip`, `lzo`, `brotli`, `lz4`, `lz4_raw`, `zstd`. Aplica-se ao Parquet (DataFrameWriter).
`spark.sql.parquet.outputTimestampType`	`INT96`	O tipo físico usado para codificar colunas de carimbo de data/hora. Valores válidos: `INT96`, `TIMESTAMP_MICROS`, `TIMESTAMP_MILLIS`. Use `INT96` para compatibilidade com leitores Parquet legados que não suportam os tipos de carimbo de data/hora padrão.

Texto

Chave	Padrão	Descrição
`compression`	`none`	Codec de compressão a ser usado na gravação. Valores válidos: `none`, `bzip2`, `gzip`, `lz4`, `snappy`, `deflate`, `zstd`. Aplica-se ao texto (DataFrameWriter).
`encoding`	`UTF-8`	A codificação de caracteres para os arquivos de saída.
`lineSep`	`\n`	As sequências de caracteres que separam as linhas entre os registros. Aplica-se ao texto (DataFrameWriter).

XML

Chave	Padrão	Descrição
`arrayElementName`	`item`	O nome do elemento para elementos de matriz que não possuem um nome explícito. Aplica-se a xml (DataFrameWriter).
`attributePrefix`	`_`	O prefixo adicionado aos nomes de campos que correspondem a atributos XML. Aplica-se a xml (DataFrameWriter).
`compression`	`none`	Codec de compressão a ser usado na gravação. Valores válidos: `none`, `bzip2`, `gzip`, `lz4`, `snappy`, `deflate`, `zstd`. Aplica-se a xml (DataFrameWriter).
`dateFormat`	`yyyy-MM-dd`	Cadeias de formatação para valores de coluna de data. Aplica-se a xml (DataFrameWriter).
`declaration`	`version="1.0" encoding="UTF-8" standalone="yes"`	As strings de declaração XML escritas no início de cada arquivo de saída. Defina como uma string vazia para suprimir a declaração. Aplica-se a xml (DataFrameWriter).
`encoding`	`UTF-8`	A codificação de caracteres para os arquivos de saída. Aplica-se a xml (DataFrameWriter).
`indent`	4 espaços	As strings usadas para indentar os elementos filhos na saída. Defina como uma string vazia para desativar o recuo e escrever cada linha em uma única linha.
`locale`	`en-US`	Um identificador `java.util.Locale` . Influencia a formatação dos valores de data e hora durante a escrita.
`nullValue`	`null`	As strings escritas para valores nulos. Quando definido como `null`, os atributos e elementos filhos para campos nulos são omitidos. Aplica-se a xml (DataFrameWriter).
`rootTag`	`ROWS`	A tag do elemento raiz que envolve todos os elementos da linha na saída. Aplica-se a xml (DataFrameWriter).
`rowTag`	`ROW`	A tag do elemento que representa uma linha na saída. Aplica-se a xml (DataFrameWriter).
`singleVariantColumn`	Nenhuma	O nome da única coluna Variant a ser gravada nos arquivos XML. Aplica-se a xml (DataFrameWriter).
`timestampFormat`	`yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]`	As strings de formatação para os valores da coluna de carimbo de data/hora. Aplica-se a xml (DataFrameWriter).
`timestampNTZFormat`	`yyyy-MM-dd'T'HH:mm:ss[.SSS]`	Formatar strings para carimbo de data/hora sem valores de coluna de fuso horário. Aplica-se a xml (DataFrameWriter).
`validateName`	`true`	Indica se deve ser lançada uma exceção caso o nome de uma coluna não seja um identificador de elemento XML válido. Aplica-se a xml (DataFrameWriter).
`valueTag`	`_VALUE`	O nome do campo usado para dados de caracteres em elementos XML que também possuem atributos ou elementos filhos. Aplica-se a xml (DataFrameWriter).

Opções do DataStreamWriter

Use estas opções com DataStreamWriter.option() para configurar gravações de transmissão.

Exemplo

O exemplo a seguir define a localização do ponto de verificação para uma transmissão:

Python
Scala

Python
(df.writeStream
  .format("delta")
  .option("checkpointLocation", "/path/to/checkpoint")
  .start("/path/to/table"))

Scala
df.writeStream
  .format("delta")
  .option("checkpointLocation", "/path/to/checkpoint")
  .start("/path/to/table")

Comum

Chave	Padrão	Descrição
`checkpointLocation`	Nenhum (obrigatório)	Caminho para o diretório de checkpoint da consulta de transmissão. Requerido para tolerância a falhas e garantias de processamento exatamente uma vez. Cada consulta de transmissão deve usar um local de ponto de verificação exclusivo. Databricks recomenda armazenar os pontos de verificação em um volume Unity Catalog ou em um caminho de armazenamento cloud . Veja postos de controle de transmissão estruturada.
`path`	Nenhuma	Caminho de saída para destinos de transmissão baseados em arquivos, como Parquet. Aplica-se somente a formatos baseados em arquivos.

pia de console

Chave	Padrão	Descrição
`numRows`	`20`	O número de linhas a serem exibidas por microlote ao escrever no coletor de dados do console.
`truncate`	`true`	Indica se as strings longas devem ser truncadas ao exibir as linhas. Defina como `false` para exibir os valores completos das strings.

Delta Lake

As seguintes opções se aplicam ao gravar uma transmissão em uma tabela Delta Lake usando format("delta"). Opções somente de sobrescrita, como overwriteSchema, replaceWhere e partitionOverwriteMode não são suportadas para gravações de transmissão.

Chave	Padrão	Descrição
`mergeSchema`	`false`	Se deve ou não evoluir o esquema da tabela Delta Lake quando o DataFrame de transmissão contiver novas colunas. Aplica-se somente ao modo de saída de anexos. Aplica-se à atualização do esquema da tabela.
`userMetadata`	Nenhuma	Uma sequência de caracteres definida pelo usuário é anexada aos metadados commit das operações de escrita. Visível na saída de `DESCRIBE HISTORY`. Aplica-se a Enriquecer tabelas com metadados personalizados.

Pia de arquivo

A seguinte opção aplica-se ao gravar uma transmissão em formatos baseados em arquivos (Parquet, JSON, CSV, ORC, texto). Para opções específicas de formato, consulte Opções do DataFrameWriter.

Chave	Padrão	Descrição
`retention`	Nenhuma	Por quanto tempo devo reter os arquivos de metadados do coletor usados para tolerância a falhas e compactação? Aceita strings de tempo como `7 days` ou `24 hours`. Quando não configurados, os arquivos de metadados são retidos indefinidamente.

Pia de Kafka

Para obter uma lista completa das opções para escrever transmissões para Kafka, consulte Opções.

Chave	Padrão	Descrição
`kafka.bootstrap.servers`	Nenhuma	Obrigatório. Uma lista de endereços de brokers Kafka `host:port` separados por vírgulas.
`topic`	Nenhuma	O tópico de destino do Kafka para todas as linhas. Obrigatório se o DataFrame não incluir uma coluna `topic` .
`kafka.*`	Nenhuma	Qualquer configuração de produtor Kafka com o prefixo `kafka.`. Por exemplo, `kafka.compression.type`.

Pia de memória

Chave	Padrão	Descrição
`queryName`	Nenhum (obrigatório)	O nome da tabela na memória na qual a consulta grava. Necessário para o armazenamento de memória. Também configurável via `.queryName()`.
`mode`	`exactlyonce`	Garantia de entrega para a pia de memória. `exactlyonce` usa o modo micro-lotes com semântica de exatamente uma vez. `atleastonce` usa o modo contínuo com semântica de pelo menos uma vez. Valores válidos: `exactlyonce`, `atleastonce`.

Opções da função Spark

Algumas funções integradas Spark SQL aceitam um mapa options que controla o comportamento de análise ou serialização. Passe opções como um Python dict ou um Scala Map[String, String].

Exemplo

O exemplo a seguir analisa uma coluna JSON, descartando registros malformados:

Python
Scala

Python
from pyspark.sql.functions import from_json
from pyspark.sql.types import StructType, StructField, StringType

schema = StructType([StructField("name", StringType())])
df = df.withColumn("parsed", from_json("json_col", schema, {"mode": "DROPMALFORMED"}))

Scala
import org.apache.spark.sql.functions.from_json
import org.apache.spark.sql.types._

val schema = StructType(Seq(StructField("name", StringType)))
val df = df.withColumn("parsed", from_json(col("json_col"), schema, Map("mode" -> "DROPMALFORMED")))

Avro

As funções Avro aceitam as mesmas opções que as opções correspondentes do DataFrame:

from_avro e schema_of_avro usam opções Avro do DataFrameReader.
to_avro Utiliza opções Avro do DataFrameWriter.

Exemplo

O exemplo a seguir decodifica uma coluna Avro com evolução do esquema habilitada:

Python
Scala

Python
from pyspark.sql.functions import from_avro

df = df.withColumn("decoded", from_avro("avro_col", json_schema, {"avroSchemaEvolutionMode": "restart"}))

Scala
import org.apache.spark.sql.avro.functions.from_avro

val df = df.withColumn("decoded", from_avro(col("avro_col"), jsonSchema, Map("avroSchemaEvolutionMode" -> "restart")))

Além disso, as variantes do Schema Registry de from_avro e to_avro aceitam as seguintes opções:

Chave	Padrão	Descrição
`schemaId`	Nenhuma	ID do esquema do Confluent Schema Registry a ser usado ao decodificar dados Avro que foram codificados com um esquema incompatível com `jsonFormatSchema`. Aplica-se somente a `from_avro` .
`confluent.schema.registry.*`	Nenhuma	Propriedades de configuração do cliente do Confluent Schema Registry. Passe qualquer propriedade do cliente Confluent SR usando este prefixo, por exemplo, `confluent.schema.registry.basic.auth.user.info` para credenciais de autenticação básica. Requerido para as variantes do Schema Registry de `from_avro` e `to_avro`.

CSV

As funções CSV aceitam as mesmas opções que as opções correspondentes do DataFrame:

from_csv e schema_of_csv usam as opções CSV do DataFrameReader.
to_csv Utiliza as opções CSV do DataFrameWriter.

Exemplo

O exemplo a seguir lê um arquivo CSV com um separador personalizado e o valor NULL :

Python
Scala

Python
from pyspark.sql.functions import from_csv
from pyspark.sql.types import StructType, StructField, IntegerType, StringType

schema = StructType([StructField("id", IntegerType()), StructField("name", StringType())])
df = df.withColumn("parsed", from_csv("csv_col", schema, {"sep": "|", "nullValue": "N/A"}))

Scala
import org.apache.spark.sql.functions.from_csv
import org.apache.spark.sql.types._

val schema = StructType(Seq(StructField("id", IntegerType), StructField("name", StringType)))
val df = df.withColumn("parsed", from_csv(col("csv_col"), schema, Map("sep" -> "|", "nullValue" -> "N/A")))

JSON

As funções JSON aceitam as mesmas opções que as opções correspondentes do DataFrame:

from_json e schema_of_json usam opções JSON do DataFrameReader.
to_json Utiliza opções JSON do DataFrameWriter.

Exemplo

O exemplo a seguir escreve JSON com campos NULL ignorados e formatação amigável ativada:

Python
Scala

Python
from pyspark.sql.functions import to_json

df = df.withColumn("json_str", to_json("struct_col", {"pretty": "true", "ignoreNullFields": "true"}))

Scala
import org.apache.spark.sql.functions.to_json

val df = df.withColumn("json_str", to_json(col("struct_col"), Map("pretty" -> "true", "ignoreNullFields" -> "true")))

Protobuf

from_protobuf e to_protobuf não usam uma fonte de dados baseada em arquivo. Os dados Protobuf são sempre lidos e gravados como colunas binárias usando essas funções. As opções são passadas como Map[String, String] e diferenciam maiúsculas de minúsculas.

Exemplo

O exemplo a seguir decodifica uma coluna Protobuf usando o modo PERMISSIVO:

Python
Scala

Python
from pyspark.sql.functions import from_protobuf

df = df.withColumn("decoded", from_protobuf("proto_col", "MyMessage", "/path/to/descriptor.desc",
    {"mode": "PERMISSIVE", "enums.as.ints": "true"}))

Scala
import org.apache.spark.sql.protobuf.functions.from_protobuf

val df = df.withColumn("decoded", from_protobuf(col("proto_col"), "MyMessage", "/path/to/descriptor.desc",
    Map("mode" -> "PERMISSIVE", "enums.as.ints" -> "true")))

As funções do Protobuf utilizam as seguintes opções:

Chave	Padrão	Descrição
`mode`	`FAILFAST`	Como lidar com registros corrompidos. `FAILFAST` lança uma exceção. `PERMISSIVE` define campos malformados como nulos. Valores válidos: `FAILFAST`, `PERMISSIVE`. Aplica-se a `from_protobuf`.
`recursive.fields.max.depth`	`-1` (desabilitado)	Profundidade máxima de recursão para campos Protobuf recursivos. Defina como `0` para desativar o suporte a campos recursivos. Valores válidos: `0` a `10`. Aplica-se a `from_protobuf`.
`convert.any.fields.to.json`	`false`	Se deve converter campos Protobuf `Any` em strings JSON em vez de `STRUCT`. Aplica-se a `from_protobuf`.
`emit.default.values`	`false`	Indica se os campos devem ser emitidos com valores zero ou valores default (semântica do Proto3). Quando `false`, os campos com valores default são omitidos da saída. Aplica-se a `from_protobuf`.
`enums.as.ints`	`false`	Indica se os campos de enumeração devem ser renderizados como valores inteiros em vez de strings. Aplica-se a `from_protobuf`.
`upcast.unsigned.ints`	`false`	Indica se é necessário converter `uint32` para `Long` e `uint64` para `Decimal(20,0)` para evitar estouro de inteiro. Aplica-se a `from_protobuf`.
`unwrap.primitive.wrapper.types`	`false`	Se deve desembrulhar os tipos wrapper `google.protobuf` (por exemplo, `Int32Value` e `StringValue`) para seus tipos primitivos Spark correspondentes. Aplica-se a `from_protobuf`.
`retain.empty.message.types`	`false`	Indica se os tipos de mensagem Protobuf vazios devem ser mantidos no esquema de saída, inserindo uma coluna fictícia. Aplica-se a `from_protobuf`.
`schema.registry.subject`	Nenhuma	Nome do assunto do Registro de Esquemas. Obrigatório ao usar as variantes do Schema Registry de `from_protobuf` e `to_protobuf`.
`schema.registry.address`	Nenhuma	Endereço do Schema Registry (host e porta). Obrigatório ao usar as variantes do Schema Registry de `from_protobuf` e `to_protobuf`.
`schema.registry.protobuf.name`	Nenhuma	Especifica qual mensagem Protobuf usar quando o assunto do registro de esquema contém várias mensagens. Opcional.

XML

As funções XML aceitam as mesmas opções que as opções correspondentes do DataFrame:

from_xml e schema_of_xml usam opções XML do DataFrameReader.
to_xml Utiliza opções XML do DataFrameWriter.

Exemplo

O exemplo a seguir escreve XML com tags raiz e de linha personalizadas:

Python
Scala

Python
from pyspark.sql.functions import to_xml

df = df.withColumn("xml_str", to_xml("struct_col", {"rootTag": "records", "rowTag": "record"}))

Scala
import org.apache.spark.sql.functions.to_xml

val df = df.withColumn("xml_str", to_xml(col("struct_col"), Map("rootTag" -> "records", "rowTag" -> "record")))

Opções do DataFrameReader​

Exemplo​

Comum​

Avro​

CSV​

Excel​

JSON​

ORC​

Parquet​

Texto​

XML​

Opções do DataStreamReader​

Exemplo​

Comum​

Auto Loader​

Comum​

Listagem de diretório​

Notificação de arquivo​

específico da nuvem​

AWS​

Azure​

GCP​

Delta Lake​

Opções do DataFrameWriter​

Exemplo​

Avro​

Delta Lake e Iceberg Apache​

CSV​

Excel​

JSON​

ORC​

Parquet​

Texto​

XML​

Opções do DataStreamWriter​

Exemplo​

Comum​

pia de console​

Delta Lake​

Pia de arquivo​

Pia de Kafka​

Pia de memória​

Opções da função Spark​

Exemplo​

Avro​

Exemplo​

CSV​

Exemplo​

JSON​

Exemplo​

Protobuf​

Exemplo​

XML​

Exemplo​

Opções do DataFrameReader

Exemplo

Comum

Avro

CSV

Excel

JSON

ORC

Parquet

Texto

XML

Opções do DataStreamReader

Exemplo

Comum

Auto Loader

Comum

Listagem de diretório

Notificação de arquivo

específico da nuvem

AWS

Azure

GCP

Delta Lake

Opções do DataFrameWriter

Exemplo

Avro

Delta Lake e Iceberg Apache

CSV

Excel

JSON

ORC

Parquet

Texto

XML

Opções do DataStreamWriter

Exemplo

Comum

pia de console

Delta Lake

Pia de arquivo

Pia de Kafka

Pia de memória

Opções da função Spark

Exemplo

Avro

Exemplo

CSV

Exemplo

JSON

Exemplo

Protobuf

Exemplo

XML

Exemplo