Referencia de opciones de la API de Spark

En esta página se enumeran las opciones de entrada y salida disponibles para las API de Spark que leen y escriben datos.

Opciones de DataFrameReader

Use estas opciones con DataFrameReader.option(), DataFrameReader.options(), read_files, COPY INTO y Auto Loader para controlar cómo Azure Databricks lee los archivos de datos.

Example

En el ejemplo siguiente se establece multiLine en True para leer archivos JSON:

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)

Común

Las siguientes opciones se aplican a todos los formatos de archivo.

Clave	Predeterminado	Descripción
ignoreCorruptFiles	false	Si se deben omitir los archivos dañados. Si el valor es true, los trabajos de Spark seguirán ejecutándose cuando haya archivos dañados y se devolverá el contenido leído. Para COPY INTO, puede observar archivos dañados omitidos como numSkippedCorruptFiles en la operationMetrics columna del historial de Delta Lake. Disponible en Databricks Runtime 11.3 LTS y versiones posteriores.
ignoreMissingFiles	false para Auto Loader, true para COPY INTO (heredado)	Si se deben omitir los archivos que faltan. Si es true, los trabajos de Spark continúan ejecutándose al encontrar archivos que faltan y se sigue devolviendo el contenido. Disponible en Databricks Runtime 11.3 LTS y versiones posteriores.
modifiedAfter	None	Una marca de tiempo opcional como filtro para procesar solo archivos cuyo sello de modificación sea posterior al proporcionado.
modifiedBefore	None	Marca de tiempo opcional como filtro para filtrar solo los archivos con una marca de tiempo de modificación anterior a la marca de tiempo dada.
pathGlobFilter o fileNamePattern	None	Un posible patrón global que proporcionar para elegir archivos. Equivalente a PATTERN en COPY INTO (heredado). fileNamePattern se puede usar en read_files.
recursiveFileLookup	false	Cuando true, esta opción busca en directorios anidados incluso si sus nombres no siguen un esquema de nomenclatura de particiones como date=2019-07-01.

Avro

Clave	Predeterminado	Descripción
avroSchema	None	Esquema opcional proporcionado por un usuario en formato Avro. Al leer Avro, esta opción se puede establecer en un esquema evolucionado compatible pero diferente del esquema avro real. El esquema de deserialización es coherente con el esquema evolucionado. Por ejemplo, si establece un esquema evolucionado que contiene una columna adicional con un valor predeterminado, el resultado de lectura también contiene la nueva columna.
avroSchemaEvolutionMode	none	Cómo controlar la evolución del esquema al usar un registro de esquemas. Valores válidos: none (omita los cambios de esquema y continúe el trabajo), restart (cuando se detectan cambios de esquema, genera un UnknownFieldException y requiere un reinicio del trabajo).
datetimeRebaseMode	LEGACY	Controla el cambio de base de los valores de fecha y marca de tiempo entre el calendario juliano y gregoriano proléptico. Valores válidos: EXCEPTION, LEGACY y CORRECTED.
enableStableIdentifiersForUnionType	false	Si se usan nombres de campo estables para los tipos de Unión avro. Cuando está habilitado, los nombres de campo de tipo de unión se derivan de sus nombres de tipo en minúsculas (por ejemplo, member_int, member_string). Produce una excepción si dos nombres de tipo son idénticos después de la reducción.
mergeSchema	false	Si se debe inferir el esquema en varios archivos y combinar el esquema de cada archivo. mergeSchema para Avro no flexibiliza los tipos de datos.
mode	FAILFAST	Modo analizador para controlar registros dañados. Valores válidos: FAILFAST (produce una excepción), PERMISSIVE (establece campos con formato incorrecto en NULL) DROPMALFORMED (quita registros incorrectos de forma silenciosa).
readerCaseSensitive	true	Especifica el comportamiento de distinción entre mayúsculas y minúsculas cuando rescuedDataColumn está habilitado. Si es true, rescate las columnas de datos cuyos nombres difieren entre mayúsculas y minúsculas del esquema. Cuando es false, lea los datos de una manera que no distingue mayúsculas de minúsculas.
recursiveFieldMaxDepth	None	Profundidad máxima de recursividad para campos Recursivos avro. Establezca en 1 para truncar todos los campos recursivos, 2 para permitir un nivel de recursión, etc. hasta 15. Cuando no se establece o 0, no se permiten campos recursivos. Valores válidos: 0 en 15.
rescuedDataColumn	None	Si se deben recopilar todos los datos que no se puedan analizar debido a un desajuste de tipos de datos y un desajuste de esquema (incluida la distinción entre mayúsculas y minúsculas en las columnas) en una columna independiente. Esta columna se incluye de forma predeterminada cuando se usa Auto Loader. COPY INTO (heredado) no admite la columna de datos rescatada porque no se puede establecer manualmente el esquema mediante COPY INTO. Databricks recomienda usar Auto Loader para la mayoría de los escenarios de ingesta. Para obtener más información, consulte ¿Qué es la columna de datos rescatados?.
stableIdentifierPrefixForUnionType	member_	Prefijo que se va a usar para nombres de campo de tipo de unión estables cuando enableStableIdentifiersForUnionType=true.

CSV

Clave	Predeterminado	Descripción
badRecordsPath	None	La ruta para almacenar los archivos para registrar la información sobre los registros CSV erróneos.
charToEscapeQuoteEscaping	\0	El carácter utilizado para escapar de las comillas. Por ejemplo, para el registro siguiente: [ " a\\", b ]: Si el carácter que se va a escapar '\' está indefinido, no se procesará el registro. El analizador leerá caracteres: [a],[\],["],[,],[ ],[b] y producirá un error porque no encuentra una comilla de cierre. Si el carácter de escape de '\' se define como '\', el registro se leerá con 2 valores: [a\] y [b].
columnNameOfCorruptRecord	_corrupt_record	Compatible con el Cargador automático. No se admite para COPY INTO (heredado) Columna para almacenar registros mal formados que no se pueden interpretar. Si el mode para el análisis se configura como DROPMALFORMED, esta columna estará vacía.
comment	\0	Define el carácter que representa un comentario de línea cuando se encuentra al principio de una línea de texto. Use '\0' para deshabilitar la omisión de comentarios.
dateFormat	yyyy-MM-dd	Formato para analizar las cadenas de fecha.
emptyValue	Cadena vacía	Representación de cadena de un valor vacío.
enableDateTimeParsingFallback	false	Si se debe revertir al comportamiento de análisis de fecha y marca de tiempo heredados cuando no se puede analizar un valor con el formato especificado. Cuando false, los errores de análisis generan un error o generan valores NULL en función de mode.
encoding o charset	UTF-8	Nombre de la codificación de los archivos CSV. Consulte java.nio.charset.Charset para la lista de opciones. UTF-16 y UTF-32 no se pueden usar cuando multiline es true.
enforceSchema	true	Si se aplica forzosamente el esquema especificado o inferido a los archivos CSV. Si la opción está habilitada, se omiten los encabezados de los archivos CSV. Esta opción se omite de forma predeterminada al usar Auto Loader para rescatar datos y permitir la evolución del esquema.
escape	\	Carácter de escape que se usará al analizar los datos.
extension	csv	Extensión de nombre de archivo esperada. Los archivos sin esta extensión se filtran durante las lecturas.
failOnUnknownFields	false	Si se produce un error cuando el registro CSV contiene columnas que no están presentes en el esquema. Cuando false, las columnas no reconocidas se quitan o se rescatan silenciosamente en función de rescuedDataColumn.
failOnWidenedFields	false	Si se produce un error cuando no se puede analizar un valor de campo como el tipo de esquema declarado sin ampliar. Cuando false, los valores de ancho de tipo se rescatarán silenciosamente en función de rescuedDataColumn. La configuración failOnUnknownFields=true puede enmascarar los efectos de esta opción.
header	false	Si los archivos CSV contienen encabezado. Auto Loader supone que los archivos tienen encabezados al inferir el esquema.
ignoreLeadingWhiteSpace	false	Si se omiten los espacios en blanco iniciales en los valores analizados.
ignoreTrailingWhiteSpace	false	Si se omiten los espacios en blanco finales en los valores analizados.
inferSchema	false	Decidir si inferir los tipos de datos de los registros CSV analizados o bien suponer que todas las columnas son de StringType. Requiere un paso adicional sobre los datos si se establece en true. Para el Cargador automático, use cloudFiles.inferColumnTypes en su lugar.
inputBufferSize	1048576 (1 MB)	Tamaño del búfer en bytes para el analizador csv. Resulta útil para optimizar el uso de memoria al analizar archivos CSV grandes. Valores válidos: enteros positivos.
lineSep	Ninguno, que cubre \r, \r\ny \n	Cadena entre dos registros CSV consecutivos.
locale	US	Un identificador java.util.Locale. Influye en la fecha predeterminada, la marca de tiempo y el análisis decimal dentro de CSV.
maxCharsPerColumn	-1	Máximo de caracteres esperados de un valor que se analizará. Se puede usar para evitar errores en la memoria. El valor predeterminado es -1, que significa ilimitado. Valores válidos: enteros positivos o -1 para ilimitados.
maxColumns	20480	Límite máximo de columnas que puede tener un registro. Valores válidos: enteros positivos.
mergeSchema	false	Si se debe inferir el esquema en varios archivos y combinar el esquema de cada archivo. Habilitado de forma predeterminada para Auto Loader al inferir el esquema.
mode	PERMISSIVE	Modo de analizador para el control de registros con formato incorrecto. Valores válidos: PERMISSIVE, DROPMALFORMED, FAILFAST.
multiLine	false	Si los registros CSV abarcan varias líneas.
nanValue	NaN	Representación de cadena de un valor no numérico al analizar columnas FloatType y DoubleType.
negativeInf	-Inf	La representación en cadena del infinito negativo cuando se analizan las columnas FloatType o DoubleType.
nullValue	Cadena vacía	Representación de cadena de un valor NULL.
parserCaseSensitive (en desuso)	false	Durante la lectura de ficheros, si se deben alinear las columnas declaradas en el encabezado con el esquema teniendo en cuenta mayúsculas y minúsculas. Esto es true de manera predeterminada para Auto Loader. Las columnas que difieren en las mayúsculas y las minúsculas se rescatarán en rescuedDataColumn si está habilitado. Esta opción ha quedado en desuso en favor de readerCaseSensitive.
positiveInf	Inf	Representación en forma de cadena del infinito positivo al analizar las columnas FloatType o DoubleType.
preferDate	true	Intentar inferir cadenas como fechas en lugar de una marca de tiempo cuando sea posible. También debe usar la inferencia de esquema, ya sea habilitando inferSchema o usando cloudFiles.inferColumnTypes con autocargador.
quote	"	Carácter utilizado para escapar valores en los que el delimitador de campo forma parte del valor.
readerCaseSensitive	true	Especifica el comportamiento de distinción entre mayúsculas y minúsculas cuando rescuedDataColumn está habilitado. Si es true, rescate las columnas de datos cuyos nombres difieren entre mayúsculas y minúsculas del esquema. Cuando es false, lea los datos de una manera que no distingue mayúsculas de minúsculas.
rescuedDataColumn	None	Si se deben recopilar todos los datos que no se puedan analizar debido a un desajuste de tipos de datos y un desajuste de esquema (incluida la distinción entre mayúsculas y minúsculas en las columnas) en una columna independiente. Esta columna se incluye de forma predeterminada cuando se usa Auto Loader. Para obtener más información, consulte ¿Qué es la columna de datos rescatados?. COPY INTO (heredado) no admite la columna de datos rescatada porque no se puede establecer manualmente el esquema mediante COPY INTO. Databricks recomienda usar Auto Loader para la mayoría de los escenarios de ingesta.
sep o delimiter	,	Cadena separadora de columnas.
singleVariantColumn	None	Cuando se establece en un nombre de columna, lee todo el registro CSV en una sola VariantType columna con ese nombre en lugar de analizar cada campo en su propia columna. Se requiere header=true.
skipRows	0	Número de filas desde el principio del archivo CSV que se debe omitir (incluidas las filas comentadas y vacías). Si header es verdadero, el encabezado será la primera fila no omitida ni comentada. Valores válidos: enteros positivos o 0.
timeFormat	HH:mm:ss	Formato para analizar valores de TimeType columna.
timestampFormat	yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]	Formato para analizar cadenas de marca de tiempo.
timestampNTZFormat	yyyy-MM-dd'T'HH:mm:ss[.SSS]	El formato para analizar la marca de tiempo sin cadenas de zona horaria (TimestampNTZType).
timeZone	None	java.time.ZoneId que se usará al analizar marcas de tiempo y fechas.
unescapedQuoteHandling	STOP_AT_DELIMITER	Estrategia para controlar las comillas sin escape. Opciones permitidas: STOP_AT_CLOSING_QUOTE: si se encuentran comillas sin escape en la entrada, acumule el carácter de comilla y continúe analizando el valor como un valor entre comillas hasta que se encuentre una comilla de cierre. BACK_TO_DELIMITER: si se encuentran comillas sin escape en la entrada, considere el valor como un valor sin comillas. Esto hará que el analizador acumule todos los caracteres del valor analizado actual hasta que se encuentre el delimitador definido por sep. Si no se encuentra ningún delimitador en el valor, el analizador seguirá acumulando caracteres de la entrada hasta que se encuentre un delimitador o un final de línea. STOP_AT_DELIMITER: si se encuentran comillas sin escape en la entrada, considere el valor como un valor sin comillas. Esto hará que el analizador acumule todos los caracteres hasta el delimitador definido mediante sep o hasta que se encuentre un final de línea en la entrada. SKIP_VALUE: si se encontrasen comillas sin escape en la entrada, se omitirá el contenido analizado para el valor dado (hasta que se encuentre el siguiente delimitador) y se producirá en su lugar el valor establecido en nullValue. RAISE_ERROR: si se encuentran comillas sin escape en la entrada, se producirá una TextParsingException excepción .

Excel

Clave	Predeterminado	Descripción
dataAddress	None	Intervalo de celdas que se va a leer en Excel sintaxis. Si se omite, lee todas las celdas válidas de la primera hoja. Use "SheetName!C5:H10" para leer un intervalo de una hoja con nombre, "C5:H10" para leer un intervalo de la primera hoja o "SheetName" para leer todos los datos de una hoja específica.
headerRows	0	Número de filas iniciales que se van a usar como encabezados de nombre de columna. Cuando dataAddress se especifica, esto se aplica dentro del intervalo de celdas. Cuando 0, los nombres de columna se generan automáticamente como _c1, _c2, _c3, , etc. Valores válidos: 0, 1.
ignoreMissingSheet	false	Si se omiten silenciosamente los archivos que no contienen la hoja especificada por dataAddress. Cuando falsees , se produce un error si falta un archivo en la hoja solicitada. Solo se aplica cuando se especifica un nombre de hoja en dataAddress. Valores válidos: true, false.
includePhoneticRuns	false	Si se deben incluir anotaciones fonéticas (como pinyin o furigana) concatenadas a valores de cadena de celda al leer archivos XLSX. Valores válidos: true, false.
operation	readSheet	Operación que se va a realizar en el libro de Excel. Valores válidos: readSheet (lee datos de una hoja), listSheets (devuelve una estructura con campos sheetIndex: long y sheetName: String para cada hoja).
timestampNTZFormat	yyyy-MM-dd'T'HH:mm:ss[.SSS]	Cadena de formato personalizado para los valores de timestamp-without-timezone almacenados como cadenas en Excel. Los formatos de fecha personalizados siguen los formatos de Patrones de fecha y hora.
dateFormat	yyyy-MM-dd	Cadena de formato personalizado para los valores de cadena leídos como Date. Los formatos de fecha personalizados siguen los formatos de Patrones de fecha y hora.

JSON

Clave	Predeterminado	Descripción
allowBackslashEscapingAnyCharacter	false	Si se permite que las barras diagonales invertidas sean caracteres de escape para cualquier carácter posterior. Si no está habilitado, solo se pueden escapar los caracteres que se enumeran explícitamente mediante la especificación JSON.
allowComments	false	Si se permite el uso de comentarios de estilo en Java, C y C++ (variedades '/', '*' y '//') dentro del contenido analizado o no.
allowNonNumericNumbers	true	Si se permite el conjunto de tokens que no son cifras (NaN) como valores de número flotante válidos.
allowNumericLeadingZeros	false	Si se permite que los números enteros comiencen con ceros adicionales (que se pueden omitir) (por ejemplo, 000001).
allowSingleQuotes	true	Si se permite el uso de comillas simples (apóstrofo, carácter '\') para citar cadenas (nombres y valores de cadena).
allowUnquotedControlChars	false	Si se permite que las cadenas JSON contengan caracteres de control sin escape (caracteres ASCII con un valor inferior a 32, incluidos los de tabulación y avance de línea) o no.
allowUnquotedFieldNames	false	Si se permite el uso de nombres de campo sin comprimido, que javaScript permite, pero no mediante la especificación JSON.
alternateVariantEncoding	None	Codificación que se usa para los valores Variant en el JSON de origen. Z85 Establézcalo en para descodificar valores Variant que se han codificado en Base85 en lugar de almacenarse como JSON insertado.
badRecordsPath	None	La ruta para almacenar archivos destinados a registrar la información sobre los registros JSON erróneos. El uso de la badRecordsPath opción en un origen de datos basado en archivos tiene las siguientes limitaciones: No es transaccional y puede dar lugar a resultados incoherentes. Los errores transitorios se tratan como errores.
columnNameOfCorruptRecord	_corrupt_record	Columna para almacenar registros mal formados que no se pueden interpretar. Si el mode para el análisis se configura como DROPMALFORMED, esta columna estará vacía.
dateFormat	yyyy-MM-dd	Formato para analizar las cadenas de fecha.
dropFieldIfAllNull	false	Si se deben ignorar las columnas con todos los valores NULL o las matrices y estructuras vacías durante la inferencia del esquema.
encoding o charset	UTF-8	Nombre de la codificación de los archivos JSON. Consulte java.nio.charset.Charset para la lista de opciones. No se puede usar UTF-16 y UTF-32 cuando multiline es true.
inferTimestamp	false	Si se deben probar y deducir cadenas de marca de tiempo como TimestampType. Cuando se establece trueen , la inferencia de esquema puede tardar notablemente más tiempo. Debe habilitar cloudFiles.inferColumnTypes para usar con Auto Loader.
lineSep	Ninguno, que cubre \r, \r\ny \n	Una cadena que aparece entre dos registros JSON consecutivos.
locale	US	Un identificador java.util.Locale. Influye en la fecha predeterminada, la marca de tiempo y el análisis decimal dentro de JSON.
maxNestingDepth	500	Profundidad de anidamiento máxima permitida para objetos y matrices JSON. Aumente este valor para documentos profundamente anidados. Valores válidos: enteros positivos.
maxNumLen	1000	Longitud máxima de los tokens de número en la entrada JSON. Aumente este valor para JSON con literales numéricos grandes. Valores válidos: enteros positivos.
maxStringLen	Ilimitado	Longitud máxima de valores de cadena en la entrada JSON. Establézcalo para limitar el uso de memoria al analizar JSON con cadenas grandes. Valores válidos: enteros positivos.
mode	PERMISSIVE	Modo de analizador para el control de registros con formato incorrecto. Valores válidos: PERMISSIVE, DROPMALFORMED, FAILFAST.
multiLine	false	Si los registros JSON abarcan varias líneas.
prefersDecimal	false	Intentos para inferir cadenas como DecimalType en lugar de tipo float o double cuando sea posible. También debe usar la inferencia de esquema, ya sea habilitando inferSchema o usando cloudFiles.inferColumnTypes con autocargador.
primitivesAsString	false	Si se deben inferir tipos primitivos como números y booleanos como StringType.
readerCaseSensitive	true	Especifica el comportamiento de distinción entre mayúsculas y minúsculas cuando rescuedDataColumn está habilitado. Si es true, rescate las columnas de datos cuyos nombres difieren entre mayúsculas y minúsculas del esquema. Cuando es false, lea los datos de una manera que no distingue mayúsculas de minúsculas. Disponible en Databricks Runtime 13.3 y versiones posteriores.
rescuedDataColumn	None	Si se van a recopilar todos los datos que no se pueden analizar debido a un error de coincidencia de tipo de datos o a un error de coincidencia de esquema (incluido el uso de mayúsculas y minúsculas de columna) en una columna independiente. Esta columna se incluye de forma predeterminada cuando se usa Auto Loader. Para obtener más información, consulte ¿Cuál es la columna de datos rescatados?. COPY INTO (heredado) no admite la columna de datos rescatada porque no se puede establecer manualmente el esquema mediante COPY INTO. Databricks recomienda usar Auto Loader para la mayoría de los escenarios de ingesta.
singleVariantColumn	None	Si se debe ingerir todo el documento JSON, analizado en una sola columna Variant con la cadena especificada como nombre de la columna. Si no se establece, los campos JSON se ingieren en sus propias columnas. Valores válidos: cualquier cadena.
timestampFormat	yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]	Formato para analizar cadenas de marca de tiempo.
timestampNTZFormat	yyyy-MM-dd'T'HH:mm:ss[.SSS]	El formato para analizar la marca de tiempo sin cadenas de zona horaria (TimestampNTZType).
timeZone	None	java.time.ZoneId que se usará al analizar marcas de tiempo y fechas.
upgradeExceptionAsBadRecord	false	Si se deben tratar las excepciones de actualización de tipos (por ejemplo, cuando un valor no se puede ampliar al tipo de columna declarado) como registros incorrectos en lugar de producir una excepción.

Kafka

Para obtener la lista completa de opciones de lector de Kafka, consulte Opciones de Kafka DataStreamReader. Las siguientes opciones solo se aplican a las lecturas por lotes mediante spark.read.format("kafka").

Clave	Predeterminado	Descripción
endingOffsets	latest	Dónde dejar de leer. Valores válidos: latest, o una cadena JSON de desplazamientos para cada partición, como {"topicA":{"0":50,"1":-1}}. En la cadena JSON, -1 es el desplazamiento más reciente. -2, que es el desplazamiento más antiguo, no se permite como desplazamiento final.
endingOffsetsByTimestamp	None	Desplazamientos finales por partición especificados como marcas de tiempo en milisegundos. Valores válidos: una cadena JSON de marcas de tiempo para cada partición, como {"topicA":{"0":2000,"1":3000}}.
endingTimestamp	None	Marca de tiempo de finalización global en milisegundos aplicados a todas las particiones. Valores válidos: enteros no negativos.

ORC

Clave	Predeterminado	Descripción
mergeSchema	false	Si se debe inferir el esquema en varios archivos y combinar el esquema de cada archivo.

Parquet

Clave	Predeterminado	Descripción
datetimeRebaseMode	LEGACY	Controla el cambio de base de los valores de fecha y marca de tiempo entre el calendario juliano y gregoriano proléptico. Valores válidos: EXCEPTION, LEGACY y CORRECTED.
int96RebaseMode	LEGACY	Controla el cambio de base de los valores de marca de tiempo INT96 entre el calendario juliano y el gregoriano proléptico. Valores válidos: EXCEPTION, LEGACY y CORRECTED.
mergeSchema	false	Si se debe inferir el esquema en varios archivos y combinar el esquema de cada archivo.
readerCaseSensitive	true	Especifica el comportamiento de distinción entre mayúsculas y minúsculas cuando rescuedDataColumn está habilitado. Si es true, rescate las columnas de datos cuyos nombres difieren entre mayúsculas y minúsculas del esquema. Cuando es false, lea los datos de una manera que no distingue mayúsculas de minúsculas.
rescuedDataColumn	None	Si se deben recopilar todos los datos que no se puedan analizar debido a un desajuste de tipos de datos y un desajuste de esquema (incluida la distinción entre mayúsculas y minúsculas en las columnas) en una columna independiente. Esta columna se incluye de forma predeterminada cuando se usa Auto Loader. Para obtener más información, consulte ¿Qué es la columna de datos rescatados?. COPY INTO (heredado) no admite la columna de datos rescatada porque no se puede establecer manualmente el esquema mediante COPY INTO. Databricks recomienda usar Auto Loader para la mayoría de los escenarios de ingesta.

Almacén de estado

Use estas opciones con spark.read.format("statestore") o la read_statestore función con valores de tabla para leer datos de estado de Structured Streaming. Consulte Leer información de estado de Structured Streaming.

Clave	Predeterminado	Descripción
batchId	Identificador de lote más reciente	Lote de destino desde el que se va a leer. Use para consultar un estado anterior de la consulta. El lote debe ser confirmado, pero aún no debe depurarse. Valores válidos: enteros no negativos.
operatorId	0	Operador de destino del que se va a leer. Use cuando la consulta tenga varios operadores con estado. Valores válidos: enteros no negativos.
storeName	DEFAULT	Nombre del almacén de estado de destino del que se va a leer. Use cuando el operador con estado tenga varias instancias de almacén de estado. Debe especificar storeName o joinSide para una combinación stream-stream, pero no para ambas. Valores válidos: cualquier cadena.
joinSide	None	Lado de destino desde el que se va a leer una combinación de flujo de flujo. Debe especificar storeName o joinSide para una combinación stream-stream, pero no para ambas. Valores válidos: left, right.
snapshotStartBatchId	None	Identificador de lote de la instantánea que se va a usar como punto de partida al leer el estado. El lector vuelve a generar el estado reproduciendo los cambios de esta instantánea hasta batchId. Resulta útil cuando una instantánea está dañada. Debe especificarse junto con snapshotPartitionId. No se puede usar con readChangeFeed. Admite el almacén de estado respaldado por HDFS y el almacén de estado de RocksDB con puntos de comprobación del registro de cambios habilitados. Disponible en Databricks Runtime 15.4 LTS y versiones posteriores. Valores válidos: enteros no negativos.
snapshotPartitionId	None	Si se especifica, la consulta solo lee esta partición. Debe especificarse junto con snapshotStartBatchId. No se puede usar con readChangeFeed. Disponible en Databricks Runtime 15.4 LTS y versiones posteriores. Valores válidos: enteros no negativos.
readChangeFeed	false	Cuando true, devuelve los cambios de estado en un intervalo especificado de lotes entre changeStartBatchId y changeEndBatchId. Se requiere changeStartBatchId. No se puede usar con joinSide, batchId, snapshotStartBatchIdo snapshotPartitionId. Disponible en Databricks Runtime 16.4 LTS y versiones posteriores. Valores válidos: true, false. Para obtener más información, consulte Read Structured Streaming state changes (Leer cambios de estado de Structured Streaming).
changeStartBatchId	None	Identificador de lote inicial del intervalo de fuente de cambios. Obligatorio cuando readChangeFeed es true. Solo se aplica cuando readChangeFeed se establece en true. Disponible en Databricks Runtime 16.4 LTS y versiones posteriores. Valores válidos: enteros no negativos.
changeEndBatchId	Identificador de lote más reciente	Identificador del lote final para el intervalo de fuente de cambios. Debe ser mayor o igual que changeStartBatchId. Solo se aplica cuando readChangeFeed se establece en true. Disponible en Databricks Runtime 16.4 LTS y versiones posteriores. Valores válidos: enteros no negativos.
stateVarName	None	Nombre de la variable de estado que se va a leer. El nombre de la variable de estado es el nombre único de cada variable dentro de la init función de un StatefulProcessor utilizado por el transformWithState operador . Obligatorio cuando se usa el transformWithState operador . Disponible en Databricks Runtime 16.4 LTS y versiones posteriores. Valores válidos: cualquier cadena.
readRegisteredTimers	false	Cuando true, lee los temporizadores registrados utilizados por el transformWithState operador . Solo se aplica al transformWithState operador . Disponible en Databricks Runtime 16.4 LTS y versiones posteriores. Valores válidos: true, false.
flattenCollectionTypes	true	Cuando true, aplana los registros devueltos para las variables de estado de asignación y lista. Cuando false, devuelve registros como Spark SQL Array o Map. Solo se aplica al transformWithState operador . Disponible en Databricks Runtime 16.4 LTS y versiones posteriores. Valores válidos: true, false.

Texto

Clave	Predeterminado	Descripción
encoding	UTF-8	Nombre de la codificación del separador de líneas de archivo TEXT. Para obtener una lista de opciones, vea java.nio.charset.Charset. El contenido del archivo no se ve afectado por esta opción y se lee as-is.
lineSep	Ninguno, que cubre \r, \r\n y \n	Cadena entre dos registros de TEXT consecutivos.
wholeText	false	Si se debe leer un archivo como único registro.

XML

Clave	Predeterminado	Descripción
rowTag	None	Etiqueta de fila de los archivos XML que se van a tratar como una fila. En el XML <books> <book><book>...<books> de ejemplo, el valor adecuado es book. Esta es una opción necesaria.
samplingRatio	1.0	Define una fracción de filas usadas para la inferencia de esquema. Las funciones integradas XML omiten esta opción. Valores válidos: 0.0 en 1.0.
excludeAttribute	false	Si se excluyen los atributos en los elementos.
mode	None	Modo para tratar los registros corruptos durante el análisis sintáctico. PERMISSIVE: Para los registros corruptos, coloca la cadena malformada en un campo configurado por columnNameOfCorruptRecord, y establece los campos con formato incorrecto en null. Para conservar los registros corruptos, puede establecer un campo de tipo string denominado columnNameOfCorruptRecord en un esquema definido por el usuario. Si un esquema no tiene el campo, los registros dañados se quitan durante el análisis. Al deducir un esquema, agrega implícitamente un campo columnNameOfCorruptRecord en un esquema de salida. DROPMALFORMED: omite los registros dañados. Este modo no es compatible con las funciones integradas XML. FAILFAST: Lanza una excepción cuando el analizador encuentra registros dañados.
inferSchema	true	Si true, entonces intenta deducir un tipo adecuado para cada columna del DataFrame resultante. Si false, todas las columnas resultantes son de tipo string. Las funciones integradas XML omiten esta opción.
columnNameOfCorruptRecord	spark.sql.columnNameOfCorruptRecord	Permite cambiar el nombre del nuevo campo que contiene una cadena con formato incorrecto creada por PERMISSIVE el modo .
attributePrefix	None	El prefijo de los atributos para diferenciarlos de los elementos. Este será el prefijo para los nombres de campo. El valor predeterminado es _. Puede estar vacío para leer XML, pero no para escribir. También se aplica a las opciones XML dataFrameWriter.
valueTag	_VALUE	Etiqueta usada para los datos de caracteres dentro de los elementos que también tienen atributos o elementos secundarios. El usuario puede especificar el valueTag campo en el esquema o se agregará automáticamente durante la inferencia de esquema cuando los datos de caracteres estén presentes en elementos con otros elementos o atributos. También se aplica a las opciones XML dataFrameWriter.
encoding	UTF-8	Para leer, descodifica los archivos XML mediante el tipo de codificación especificado. Para escribir, especifica la codificación (charset) de los archivos XML guardados. Las funciones integradas XML omiten esta opción. También se aplica a las opciones XML dataFrameWriter.
ignoreSurroundingSpaces	true	Si se deben omitir los espacios en blanco que rodean los valores. Los datos de caracteres de solo espacio en blanco se omiten.
rowValidationXSDPath	None	Ruta a un archivo XSD opcional que se utiliza para validar el XML de cada fila individualmente. Las filas que no se validan se tratan como errores de análisis. De lo contrario, el XSD no afecta al esquema, ya sea proporcionado o inferido.
ignoreNamespace	false	Si true, se omiten los prefijos de los espacios de nombres en los elementos y atributos XML. Las etiquetas <abc:author> y <def:author>, por ejemplo, se tratan como si ambos son simplemente <author>. Los espacios de nombres no se pueden omitir en el elemento rowTag, solo sus elementos secundarios de lectura. El análisis XML no es compatible con el espacio de nombres, incluso si es false.
timestampFormat	yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]	Cadena de formato de marca de tiempo personalizada que sigue el formato del patrón de fecha y hora . Esto se aplica al tipo timestamp. También se aplica a las opciones XML dataFrameWriter.
timestampNTZFormat	yyyy-MM-dd'T'HH:mm:ss[.SSS]	Cadena de formato personalizado para la marca de tiempo sin zona horaria que sigue el formato de patrón datetime. Esto se aplica al tipo TimestampNTZType. También se aplica a las opciones XML dataFrameWriter.
dateFormat	yyyy-MM-dd	Cadena de formato de fecha personalizada que sigue el patrón de fecha y hora. Esto se aplica al tipo de fecha. También se aplica a las opciones XML dataFrameWriter.
locale	en-US	Establece una configuración regional como etiqueta de idioma en formato IETF BCP 47. Por ejemplo, locale se usa al analizar fechas y marcas de tiempo.
nullValue	cadena null	Establece la representación en cadena de un valor nulo. Cuando se trata de null, el analizador no escribe atributos y elementos para los campos. También se aplica a las opciones XML dataFrameWriter.
readerCaseSensitive	true	Especifica el comportamiento de distinción entre mayúsculas y minúsculas cuando se habilita rescuedDataColumn. Si es true, rescate las columnas de datos cuyos nombres difieren entre mayúsculas y minúsculas del esquema. Cuando es false, lea los datos de una manera que no distingue mayúsculas de minúsculas.
rescuedDataColumn	None	Si se van a recopilar todos los datos que no se pueden analizar debido a un desajuste de tipo de datos y a un desajuste de esquema (incluido el uso de mayúsculas y minúsculas de columna) en una columna separada. Esta columna se incluye de forma predeterminada cuando se usa Auto Loader. Para obtener más información, consulte ¿Qué es la columna de datos rescatados?. COPY INTO (heredado) no admite la columna de datos rescatada porque no se puede establecer manualmente el esquema mediante COPY INTO. Databricks recomienda usar Auto Loader para la mayoría de los escenarios de ingesta.
singleVariantColumn	none	Especifica el nombre de la columna variante única. Si se especifica esta opción para leer, analice todo el registro XML en una sola columna Variant con el valor de cadena de opción especificado como nombre de la columna. Si se ofrece esta opción para la escritura, escriba el valor de la columna única de Variant en archivos XML. También se aplica a las opciones XML dataFrameWriter.
useLegacyXMLParser	true	Si se va a usar el analizador XML heredado. El analizador heredado tiene una validación menos estricta para el contenido con formato incorrecto, pero es menos eficaz para la memoria. Establézcalo false en para participar en el analizador predeterminado más estricto.
wildcardColName	xs_any	Nombre de columna usado para capturar elementos XML que coinciden con el elemento de esquema comodín (xs:any). No se puede usar junto con rescuedDataColumn.

Opciones de DataStreamReader

Use estas opciones con DataStreamReader.option() para configurar las lecturas de streaming de tablas de Delta Lake y otros orígenes basados en archivos.

Para ver las opciones de formato de archivo (JSON, CSV, Parquet y otros), consulte Opciones de DataFrameReader.

Para ver las opciones de Auto Loader (cloudFiles.*), consulte Auto Loader (Auto Loader).

Example

En el ejemplo siguiente se establece maxFilesPerTrigger en 10 para un flujo de tabla de Delta Lake:

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

Común

Las siguientes opciones se aplican a las tablas de Delta Lake y a otros orígenes de streaming basados en archivos.

Clave	Predeterminado	Descripción
cleanSource	off	Cómo controlar los archivos de origen después de que la secuencia los procese. Valores válidos: off (sin acción), delete (elimine permanentemente el archivo de origen) archive (vaya a sourceArchiveDir). Cuando se establece en archive, sourceArchiveDir también debe establecerse. No se aplica al streaming de tablas de Delta Lake.
fileNameOnly	false	Indica si se deben identificar archivos ya procesados por nombre de archivo solo en lugar de por ruta de acceso completa. Cuando true, los archivos en rutas de acceso diferentes con el mismo nombre de archivo se tratan como el mismo archivo y no se vuelven a procesar. No se aplica al streaming de tablas de Delta Lake.
latestFirst	false	Si se van a procesar primero los archivos modificados más recientemente dentro de cada microlote. Resulta útil cuando desea procesar los datos más recientes lo antes posible. Cuando true se establece maxFileAge o maxFilesPerTriggermaxBytesPerTrigger , se omite. No se aplica al streaming de tablas de Delta Lake.
maxBytesPerTrigger	None	Máximo flexible para la cantidad de datos procesados para cada microproceso. Un lote puede procesar más que el límite si la unidad de entrada más pequeña la supera. Cuando se usa junto con maxFilesPerTrigger, el microproceso procesa los datos hasta que se alcanza primero cualquiera de los límites. Valores válidos: enteros positivos. Para el Cargador automático, use cloudFiles.maxBytesPerTrigger en su lugar. Consulte Común.
maxCachedFiles	10000	Número máximo de archivos no procesados que se almacenarán en caché para los microprocesos posteriores. Establezca en 0 para desactivar el almacenamiento en caché. Aumente este valor cuando el directorio de origen contenga muchos archivos nuevos para cada desencadenador. No se aplica al streaming de tablas de Delta Lake. Valores válidos: enteros positivos o 0.
maxFileAge	7d	Antigüedad máxima de los archivos considerados para su procesamiento, en relación con la marca de tiempo del archivo modificado más recientemente en lugar de la hora actual del sistema. Los archivos anteriores a este umbral se omiten. Acepta cadenas de duración como 7d o 4h. Se omite cuando latestFirst es true y maxFilesPerTrigger o maxBytesPerTrigger se establece. No se aplica al streaming de tablas de Delta Lake.
maxFilesPerTrigger	1000 para Delta Lake y Auto Loader. No hay ningún valor máximo para otros orígenes basados en archivos.	Límite superior para el número de archivos nuevos procesados en cada microproceso. Cuando se usa junto con maxBytesPerTrigger, el microproceso procesa los datos hasta que se alcanza primero cualquiera de los límites. Valores válidos: enteros positivos. Para el Cargador automático, use cloudFiles.maxFilesPerTrigger en su lugar. Consulte Común.
sourceArchiveDir	None	Ruta de acceso al directorio de archivo cuando cleanSource se establece en archive. Los archivos de origen se mueven a esta ruta de acceso después del procesamiento, conservando su estructura de directorios relativa. No se aplica al streaming de tablas de Delta Lake.

Cargador automático

Use estas opciones con el cloudFiles origen para configurar Auto Loader para la ingesta de streaming desde el almacenamiento en la nube. Las opciones específicas del cloudFiles origen tienen el prefijo cloudFiles para mantenerlos en un espacio de nombres independiente de otras opciones de origen de Structured Streaming .

Común

Clave	Predeterminado	Descripción
cloudFiles.allowOverwrites	false	Indica si se permiten cambios en el archivo de directorio de entrada para sobrescribir los datos existentes. Para ver advertencias de configuración, consulte ¿Procesa el cargador automático el archivo de nuevo cuando el archivo se anexa o sobrescribe?.
cloudFiles.backfillInterval	None	El cargador automático puede desencadenar reposición asincrónica en un intervalo determinado. Por ejemplo 1 day , para rellenar diariamente o 1 week para rellenar semanalmente. Para obtener más información, consulte Activar reposiciones regulares usando cloudFiles.backfillInterval. No use cuando cloudFiles.useManagedFileEvents se establece en true.
cloudFiles.cleanSource	OFF	Si desea eliminar automáticamente los archivos procesados del directorio de entrada. Cuando se establece en OFF (valor predeterminado), no se elimina ningún archivo. Cuando se establece en DELETE, Auto Loader elimina automáticamente los archivos 30 días después de procesarlos. Para ello, El cargador automático debe tener permisos de escritura en el directorio de origen. Cuando se establece en MOVE, Auto Loader mueve automáticamente los archivos a la ubicación especificada en cloudFiles.cleanSource.moveDestination 30 días después de procesarlos. Para ello, el Cargador Automático debe tener permisos de escritura en el directorio de origen, así como en la ubicación del movimiento. Un archivo se considera procesado cuando tiene un valor distinto de NULL para commit_time en el resultado de la cloud_files_state función con valores de tabla. Consulte cloud_files_state función con valores de tabla. La espera adicional de 30 días después del procesamiento se puede configurar mediante cloudFiles.cleanSource.retentionDuration. Revise las consideraciones siguientes antes de habilitar cloudFiles.cleanSource: Azure Databricks no recomienda usar esta opción si hay varios flujos que consumen datos de la ubicación de origen porque el consumidor más rápido eliminará los archivos y no se ingerirá en los orígenes más lentos. La habilitación de esta característica requiere que el cargador automático mantenga un estado adicional en su punto de control, lo que incurre en sobrecarga de rendimiento, pero permite una observabilidad mejorada a través de la cloud_files_state función con valores de tabla. Consulte cloud_files_state función con valores de tabla. cleanSource usa la configuración actual para decidir si se debe o MOVEDELETE un archivo determinado. Por ejemplo, supongamos que la configuración era MOVE cuando el archivo se procesó originalmente, pero se cambió a DELETE cuando el archivo se convirtió en candidato para la limpieza de 30 días después. En este caso, cleanSource eliminará el archivo. No se garantiza que los archivos se limpien en cuanto retentionDuration expire. Para mantener bajos costos, el cargador automático elimina los archivos simultáneamente con el procesamiento de flujos y finaliza en cuanto se completa o finaliza el procesamiento de la secuencia. Los archivos que eran candidatos para la limpieza, pero que no se pudieron limpiar durante el procesamiento de flujos se recogerán la próxima vez que se ejecute Auto Loader. Disponible en Databricks Runtime 16.4 y versiones posteriores.
cloudFiles.cleanSource.retentionDuration	30 days	Tiempo de espera antes de que los archivos procesados se conviertan en candidatos para ser archivados con cleanSource. Debe ser mayor que 7 días para DELETE. No hay ninguna restricción mínima para MOVE. El valor es una cadena CalendarInterval . Por ejemplo, "14 days", "30 days", "2 weeks" o "1 month". Disponible en Databricks Runtime 16.4 y versiones posteriores.
cloudFiles.cleanSource.moveDestination	None	Ruta de acceso para archivar los archivos procesados cuando cloudFiles.cleanSource se establece en MOVE. Puede ser una ruta de acceso de almacenamiento en la nube o una ruta de acceso de volumen del catálogo de Unity (por ejemplo, /Volumes/my_catalog/my_schema/my_volume/archive/). La ubicación de movimiento debe: No sea un elemento secundario del directorio de origen. Si coloca el destino de movimiento dentro del directorio de origen, los archivos archivados se ingieren de nuevo. Estar en la misma ubicación externa, volumen o montaje de DBFS que el origen. No se admiten movimientos entre buckets y contenedores, lo que resulta en un error. Auto Loader debe tener permisos de escritura en este directorio. Disponible en Databricks Runtime 16.4 y versiones posteriores.
cloudFiles.format	Ninguno (opción obligatoria)	El formato del archivo de datos en la ruta de origen. Los valores válidos son: avro: archivos Avro binaryFile: archivos binarios csv: archivos CSV json: archivos JSON orc: archivos ORC parquet: Archivos de Parquet text: archivos TXT xml: archivos XML
cloudFiles.includeExistingFiles	true	Indica si se incluyen los archivos existentes en la ruta de acceso de entrada del procesamiento de flujos o si solo se procesan los nuevos archivos que llegan después de la configuración inicial. Esta opción solo se evalúa cuando se inicia una transmisión por primera vez. Cambiar esta opción después de reiniciar la secuencia no tiene ningún efecto.
cloudFiles.inferColumnTypes	false	Determinar si se deben inferir los tipos de columnas exactos al aprovechar la inferencia de esquema. De manera predeterminada, las columnas se infieren como cadenas al inferir conjuntos de datos JSON y CSV. Consulte Inferencia de esquemas para obtener más detalles.
cloudFiles.maxBytesPerTrigger	None	Número máximo de bytes nuevos que se procesarán en cada desencadenador. Puede especificar una cadena de bytes como 10g para limitar cada microlote a 10 GB de datos. Se trata de un límite suave. Si tiene archivos de 3 GB cada uno, Azure Databricks procesa 12 GB en un microlote. Cuando se usa junto con cloudFiles.maxFilesPerTrigger, Azure Databricks consume hasta el límite inferior de cloudFiles.maxFilesPerTrigger o cloudFiles.maxBytesPerTrigger, lo que se alcance primero. Esta opción no tiene ningún efecto cuando se usa con Trigger.Once() (Trigger.Once() está en desuso). En Databricks Runtime 18.0 y versiones posteriores, esta opción está configurada dinámicamente y no es necesario establecerla manualmente.
cloudFiles.maxFileAge	None	Cuánto dura el seguimiento de un evento de archivo con fines de desduplicación. Databricks no recomienda ajustar este parámetro a menos que ingiera datos en el orden de millones de archivos por hora. Consulte la sección seguimiento de eventos de archivo para obtener más detalles. Un ajuste demasiado agresivo de cloudFiles.maxFileAge puede causar problemas en la calidad de los datos, como la ingesta duplicada o la falta de archivos. Por lo tanto, Databricks recomienda una configuración prudente para cloudFiles.maxFileAge, como 90 días, que es similar a lo que recomiendan soluciones comparables de ingesta de datos.
cloudFiles.maxFilesPerTrigger	1000	Número máximo de archivos nuevos que se procesarán en cada desencadenador. Cuando se usa junto con cloudFiles.maxBytesPerTrigger, Azure Databricks consume hasta el límite inferior de cloudFiles.maxFilesPerTrigger o cloudFiles.maxBytesPerTrigger, lo que se alcance primero. Esta opción no tiene ningún efecto cuando se usa con Trigger.Once() (en desuso). En Databricks Runtime 18.0 y versiones posteriores, esta opción está configurada dinámicamente y no es necesario establecerla manualmente.
cloudFiles.partitionColumns	None	Lista separada por comas de columnas de partición de estilo de Hive que desea deducir de la estructura de directorios de los archivos. Las columnas de partición de estilo de Hive son pares clave-valor combinados mediante un signo de igualdad como <base-path>/a=x/b=1/c=y/file.format. En este ejemplo, las columnas de partición son a, by c. De manera predeterminada, estas columnas se agregan automáticamente al esquema si usa la inferencia de esquema y proporciona la <base-path> desde la que cargar los datos. Si proporciona un esquema, el cargador automático espera que estas columnas se incluyan en el esquema. Si no quiere que estas columnas formen parte del esquema, puede especificar "" para ignorarlas. Además, puede usar esta opción cuando desee que las columnas se infieran de la ruta de acceso del archivo en estructuras de directorio complejas, como en el ejemplo siguiente: <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 devuelve year=2022 para file1.csv, pero las month columnas y day son null. month y day se analizan correctamente para file2.csv y file3.csv.
cloudFiles.schemaEvolutionMode	addNewColumnscuando no se proporciona un esquema; de lo contrario, none	El modo de hacer evolucionar el esquema a medida que se detectan nuevas columnas en los datos. De manera predeterminada, las columnas se infieren como cadenas al inferir conjuntos de datos JSON. Consulte evolución del esquema para obtener más detalles.
cloudFiles.schemaHints	None	Información de esquema que usted proporciona al Cargador Automático durante la inferencia del esquema. Consulte Sugerencias de esquema para obtener más detalles.
cloudFiles.schemaLocation	Ninguno (necesario para deducir el esquema)	Ubicación en la que se almacenará el esquema deducido y los cambios posteriores. Consulte Inferencia de esquemas para obtener más detalles.
cloudFiles.useStrictGlobber	false	Si se usa un patrón global estricto que coincida con el comportamiento global predeterminado de otros orígenes de archivos en Apache Spark. Consulte Patrones comunes de carga de datos para obtener más detalles. Disponible en Databricks Runtime 12.2 LTS y versiones posteriores.
cloudFiles.validateOptions	true	Indica si se validan las opciones de Auto Loader y se devuelve un error para opciones desconocidas o incoherentes.

Lista de directorios

Clave	Predeterminado	Descripción
cloudFiles.useIncrementalListing (en desuso)	auto en Databricks Runtime 17.2 y versiones posteriores, false en Databricks Runtime 17.3 y versiones posteriores	Esta característica ha quedado en desuso. Databricks recomienda usar el modo de notificación de archivos con eventos de archivo en lugar de cloudFiles.useIncrementalListing. Indica si se debe usar la lista incremental en lugar de la lista completa en el modo de lista de directorios. De forma predeterminada, Auto Loader hace todo lo posible para detectar automáticamente si un directorio determinado es aplicable para el listado incremental. Puede usar explícitamente la lista incremental o usar la lista de directorios completa si las establece como true o false respectivamente. Habilitar incorrectamente la lista incremental en un directorio ordenado no léxico impide que Auto Loader detecte nuevos archivos. Funciona con Azure Data Lake Storage (abfss://), S3 (s3://) y GCS (gs://). Disponible en Databricks Runtime 9.1 LTS y versiones superiores. Valores disponibles: auto, true, false

Notificación de archivo

Para obtener información sobre cómo configurar el modo de notificación de archivos, incluidos los permisos de nube necesarios, las instrucciones de configuración y los métodos de autenticación, consulte Configuración de flujos de cargador automático en modo de notificación de archivos.

Clave	Predeterminado	Descripción
cloudFiles.fetchParallelism	1	Número de subprocesos que se usan al capturar mensajes del servicio de cola. No use cuando cloudFiles.useManagedFileEvents se establece en true.
cloudFiles.pathRewrites	None	Solo es necesario si especifica un queueUrl objeto que recibe notificaciones de archivos de varios cubos S3 y desea usar puntos de montaje configurados para acceder a los datos de estos contenedores. Use esta opción para reescribir el prefijo de la ruta de acceso bucket/key con el punto de montaje. Solo se pueden reescribir los prefijos. Por ejemplo, para la configuración {"<databricks-mounted-bucket>/path": "dbfs:/mnt/data-warehouse"}, la ruta s3://<databricks-mounted-bucket>/path/2017/08/fileA.json se vuelve a modificar a dbfs:/mnt/data-warehouse/2017/08/fileA.json. No use cuando cloudFiles.useManagedFileEvents se establece en true.
cloudFiles.resourceTag	None	Una serie de pares de etiquetas clave-valor para ayudar a asociar e identificar recursos relacionados, por ejemplo: cloudFiles.option("cloudFiles.resourceTag.myFirstKey", "myFirstValue") .option("cloudFiles.resourceTag.mySecondKey", "mySecondValue") Para obtener más información sobre AWS, consulte Etiquetas de asignación de costos de Amazon SQS y Configuración de etiquetas para un tema de Amazon SNS. (1) Para obtener más información sobre Azure, consulte Asignar nombres a colas y metadatos y la cobertura de properties.labels en Suscripciones a eventos. El cargador automático almacena estos pares de etiquetas clave-valor en JSON como etiquetas. (1) Para obtener más información sobre GCP, consulte Uso de informes con etiquetas. (1) No use cuando cloudFiles.useManagedFileEvents se establece en true. En su lugar, establezca etiquetas de recursos mediante la consola del proveedor de nube.
cloudFiles.useManagedFileEvents	false	Cuando se establece en true, Auto Loader usa el servicio de eventos de archivo para detectar archivos en la ubicación externa. Puede usar esta opción solo si la ruta de acceso de carga está en una ubicación externa donde los eventos de archivo estén habilitados. Consulte Uso del modo de notificación de archivos con eventos de archivo. Los eventos de archivo proporcionan un rendimiento de nivel de notificaciones en la detección de archivos, ya que Auto Loader puede detectar nuevos archivos después de la última ejecución. A diferencia de la lista de directorios, este proceso no necesita enumerar todos los archivos del directorio. Hay algunas situaciones en las que Auto Loader usa la lista de directorios aunque la opción de eventos de archivo esté habilitada: Durante la carga inicial, cuando includeExistingFiles se establece en true, se realiza una lista completa de directorios para descubrir todos los archivos que estaban presentes en el directorio antes de que se inicie Auto Loader. El servicio de eventos de archivos optimiza la detección de archivos almacenando en caché los archivos creados más recientemente. Si el cargador automático se ejecuta con poca frecuencia, esta caché puede expirar y el cargador automático vuelve a la lista de directorios para detectar archivos y actualizar la memoria caché. Para evitar este escenario, invoque Auto Loader al menos una vez cada siete días. Consulte ¿Cuándo usa Auto Loader con eventos de archivo la lista de directorios? para obtener una lista completa de situaciones en las que Auto Loader usa la lista de directorios con esta opción. Disponible en Databricks Runtime 14.3 LTS y versiones posteriores.
cloudFiles.listOnStart	false	Cuando se establece trueen , El cargador automático realiza una lista de directorios completa cuando se inicia la secuencia, en lugar de empezar con el token de continuación en el punto de control. Use esta opción para recuperarse de errores, como CF_MANAGED_FILE_EVENTS_INVALID_CONTINUATION_TOKEN. Consulte ¿Cómo puedo recuperarme de un CF_MANAGED_FILE_EVENTS_INVALID_CONTINUATION_TOKEN error?.
cloudFiles.useNotifications	false	Indica si se debe usar el modo de notificación de archivos para determinar cuándo hay nuevos archivos. Si es false, use el modo de lista de directorios. Consulte Comparación de los modos de detección de archivos del cargador automático. No use cuando cloudFiles.useManagedFileEvents se establece en true.

(1) El cargador automático agrega de forma predeterminada y en la medida de lo posible los siguientes pares de etiquetas clave-valor:

• vendor: Databricks
• path: ubicación desde la que se cargan los datos. No disponible en GCP debido a las limitaciones de etiquetado.
• checkpointLocation: la ubicación del punto de control de la secuencia. No disponible en GCP debido a las limitaciones de etiquetado.
• streamId: identificador único global de la secuencia.

Databricks reserva estos nombres de clave y no puede sobrescribir sus valores.

Específico de la nube

Auto Loader proporciona opciones para configurar la infraestructura en la nube para el modo de notificación de archivos. Para obtener instrucciones de configuración y permisos de nube necesarios, consulte Configuración de flujos de cargador automático en modo de notificación de archivos.

AWS

Proporcione las siguientes opciones solo si elige cloudFiles.useNotifications = true y desea que Auto Loader configure los servicios de notificación automáticamente:

Clave	Predeterminado	Descripción
cloudFiles.region	Región de la instancia EC2	La región donde reside el cubo S3 de origen y dónde desea crear los servicios de AWS SNS y SQS.

Clave	Predeterminado	Descripción
cloudFiles.restrictNotificationSetupToSameAWSAccountId	false	Permitir únicamente notificaciones de eventos de depósitos de AWS S3 en la misma cuenta que el tópico SNS. Cuando es true, Auto Loader solo acepta notificaciones de eventos de cubos de AWS S3 en la misma cuenta que el tópico SNS. Cuando false es, la directiva de acceso no restringe la configuración entre cuentas de los buckets y temas de SNS. Esto resulta útil cuando el tema de SNS y la ruta de acceso del bucket están asociados a cuentas diferentes. Disponible en Databricks Runtime 17.2 y versiones posteriores.

Proporcione la siguiente opción solo si elige cloudFiles.useNotifications = true y desea que el cargador automático use una cola que ya haya configurado:

Clave	Predeterminado	Descripción
cloudFiles.queueUrl	None	Dirección URL de la cola de SQS. Si se proporciona, el cargador automático consume directamente los eventos de esta cola en lugar de configurar sus propios servicios AWS SNS y SQS.

Opciones de autenticación de AWS

Proporcione la siguiente opción de autenticación para usar una credencial de servicio de Databricks:

Clave	Predeterminado	Descripción
databricks.serviceCredential	None	Nombre de la credencial de servicio de Databricks . Disponible en Databricks Runtime 16.1 y versiones posteriores.

Cuando las credenciales del servicio Databricks o los roles de IAM no están disponibles, puede proporcionar las siguientes opciones de autenticación en su lugar:

Clave	Predeterminado	Descripción
cloudFiles.awsAccessKey	None	El ID de clave de acceso de AWS del usuario. Debe proporcionarse con cloudFiles.awsSecretKey.
cloudFiles.awsSecretKey	None	Clave de acceso secreta de AWS para el usuario. Debe proporcionarse con cloudFiles.awsAccessKey.
cloudFiles.roleArn	None	EL ARN de un rol IAM que se debe asumir, si procede. El rol se puede asumir desde el perfil de instancia del clúster o proporcionando credenciales con cloudFiles.awsAccessKey y cloudFiles.awsSecretKey.
cloudFiles.roleExternalId	None	Identificador que se debe proporcionar a la vez que se asume un rol mediante cloudFiles.roleArn.
cloudFiles.roleSessionName	None	Un nombre de sesión opcional que se usará al asumir un rol mediante cloudFiles.roleArn.
cloudFiles.stsEndpoint	None	Un punto de conexión opcional para proporcionar acceso a AWS STS al asumir un rol mediante cloudFiles.roleArn.

Azure

Debe proporcionar valores para todas las opciones siguientes si especifica cloudFiles.useNotifications = true y desea que el cargador automático configure automáticamente los servicios de notificación:

Clave	Predeterminado	Descripción
cloudFiles.resourceGroup	None	El Azure grupo de recursos en el que se crea la cuenta de almacenamiento.
cloudFiles.subscriptionId	None	El Azure identificador de suscripción en el que se crea el grupo de recursos.
databricks.serviceCredential	None	Nombre de la credencial de servicio de Databricks . Disponible en Databricks Runtime 16.1 y versiones posteriores.

Si una credencial de servicio de Databricks no está disponible, puede proporcionar las siguientes opciones de autenticación en su lugar:

Clave	Predeterminado	Descripción
cloudFiles.clientId	None	Id. de cliente o id. de aplicación de la entidad de servicio.
cloudFiles.clientSecret	None	El secreto de cliente de la entidad de servicio.
cloudFiles.connectionString	None	Cadena de conexión de la cuenta de almacenamiento, en función de la clave de acceso de la cuenta o de la firma de acceso compartido (SAS).
cloudFiles.tenantId	None	Identificador de inquilino Azure en el que se crea la entidad de servicio.

Proporcione la siguiente opción solo si establece cloudFiles.useNotifications = true y desea que Auto Loader use una cola existente:

Clave	Predeterminado	Descripción
cloudFiles.queueName	None	Nombre de la cola de Azure. Si se proporciona, el origen de archivos en la nube consume directamente los eventos de esta cola en lugar de configurar sus propios servicios de Azure Event Grid y Queue Storage. En ese caso, databricks.serviceCredential o cloudFiles.connectionString solo necesita permisos de lectura en la cola.

GCP

El cargador automático puede configurar automáticamente los servicios de notificaciones utilizando las credenciales de servicio de Databricks . La cuenta de servicio creada con la credencial de servicio de Databricks requerirá los permisos especificados en Configurar flujos de cargador automático en modo de notificación de archivos.

Clave	Predeterminado	Descripción
cloudFiles.projectId	None	Identificador del proyecto en el que se encuentra el cubo GCS. La suscripción a Google Cloud Pub/Sub también se crea en este proyecto.
databricks.serviceCredential	None	Nombre de la credencial de servicio de Databricks . Disponible en Databricks Runtime 16.1 y versiones posteriores.

Si una credencial de servicio de Databricks no está disponible, puede usar las cuentas de servicio de Google directamente. Puede configurar el clúster para asumir una cuenta de servicio siguiendo la configuración del servicio de Google o proporcionar las siguientes opciones de autenticación directamente:

Clave	Predeterminado	Descripción
cloudFiles.client	None	El Id. de cliente de la cuenta de servicio de Google.
cloudFiles.clientEmail	None	El correo electrónico de la cuenta de servicio de Google.
cloudFiles.privateKey	None	Clave privada que se genera para la cuenta de servicio de Google.
cloudFiles.privateKeyId	None	Identificador de la clave privada que se genera para la cuenta de servicio de Google.

Proporcione la siguiente opción solo si elige cloudFiles.useNotifications = true y desea que el cargador automático use una cola que ya haya configurado:

Clave	Predeterminado	Descripción
cloudFiles.subscription	None	Nombre de la suscripción de Google Cloud Pub/Sub. Si se proporciona, el origen de archivos en la nube consume los eventos de esta cola en lugar de configurar sus propios servicios GCS Notification y Google Cloud Pub/Sub.

Delta Lake

Las siguientes opciones se aplican al leer desde una tabla de Delta Lake mediante spark.readStream.

Clave	Predeterminado	Descripción
allowSourceColumnDrop	None	Establézcalo en un número de versión de la tabla Delta o "always" para permitir que la secuencia continúe después de quitar las columnas del esquema de la tabla de origen. Cuando se establece en un número de versión, confirma todos los cambios de esquema hasta esa versión. Se requiere schemaTrackingLocation. Consulte Renombrar y eliminar columnas con el mapeo de columnas de Delta Lake.
allowSourceColumnRename	None	Establezca en un número de versión de la tabla Delta o "always" para permitir que la secuencia continúe después de que se cambie el nombre de las columnas en la tabla de origen. Cuando se establece en un número de versión, confirma todos los cambios de esquema hasta esa versión. Se requiere schemaTrackingLocation. Consulte Renombrar y eliminar columnas con el mapeo de columnas de Delta Lake.
allowSourceColumnTypeChange	None	Establézcalo en un número de versión de la tabla Delta o "always" para permitir que la secuencia continúe después de cambiar los tipos de columna en la tabla de origen. Cuando se establece en un número de versión, confirma todos los cambios de esquema hasta esa versión. Se requiere schemaTrackingLocation. Consulte Ampliación de tipos.
excludeRegex	None	Patrón de expresión regular. Los archivos cuyas rutas de acceso coinciden con el patrón se excluyen de la lectura de streaming. Resulta útil para filtrar archivos que no se ajustan a la convención de nomenclatura esperada.
failOnDataLoss	true	Si se produce un error en la consulta de streaming si se han eliminado los datos de origen debido a la retención del registro (logRetentionDuration). Establézcalo en false para omitir los datos que faltan y continuar con el procesamiento. Vea Configuración de la retención de datos para las consultas de historial temporal.
ignoreChanges (en desuso)	false	Disponible en Databricks Runtime 11.3 LTS y versiones posteriores. Vuelve a emitir archivos de datos reescritos después de operaciones de modificación como UPDATE, MERGE INTO, DELETEo OVERWRITE. Las filas sin cambios se pueden emitir junto con las nuevas filas, por lo que los consumidores de nivel inferior deben controlar los duplicados. Las eliminaciones no se propagan hacia abajo. Reemplazado por skipChangeCommits en Databricks Runtime 12.2 LTS y versiones posteriores.
ignoreDeletes (en desuso)	false	Omite las transacciones que eliminan datos en los límites de partición (solo quita la partición completa). No controla eliminaciones, actualizaciones u otras modificaciones que no son de partición. Utilice skipChangeCommits en su lugar.
readChangeFeed o readChangeData	false	Si se habilita la lectura de la fuente de distribución de datos de cambios para la consulta de streaming. Cuando está habilitada, la secuencia emite cambios de nivel de fila (inserciones, actualizaciones y eliminaciones) con columnas de metadatos adicionales. Vea Cómo utilizar el feed de datos de cambios de Delta Lake en Azure Databricks.
schemaTrackingLocation	None	Ruta de acceso a un directorio donde Delta Lake realiza un seguimiento de los cambios de esquema para la lectura de streaming. Se requiere cuando el streaming de tablas con asignación de columnas habilitada y mediante allowSourceColumn* opciones para controlar la evolución del esquema. Debe estar dentro checkpointLocation de de la consulta de streaming. Consulte Renombrar y eliminar columnas con el mapeo de columnas de Delta Lake.
skipChangeCommits	false	Omite las transacciones que eliminan o modifican registros y procesos existentes solo anexan. Databricks recomienda esta opción para la mayoría de las cargas de trabajo que no usan fuentes de distribución de datos modificados. Disponible en Databricks Runtime 12.2 LTS y versiones posteriores. Consulte Omitir confirmaciones de cambios ascendentes con skipChangeCommits.
startingTimestamp	Más reciente disponible	Marca de tiempo desde la que empezar a leer. La secuencia lee todos los cambios de tabla confirmados en o después de la marca de tiempo especificada. Si la marca de tiempo precede a todas las confirmaciones de tabla disponibles, la secuencia comienza desde la confirmación disponible más antigua. No se puede usar junto con startingVersion. Se omite si el punto de control de streaming ya existe. Valores válidos: una cadena de marca de tiempo como "2019-01-01T00:00:00.000Z" o una cadena de fecha como "2019-01-01".
startingVersion	Más reciente disponible	Versión de la tabla delta desde la que empezar a leer. La secuencia lee todos los cambios confirmados en o después de la versión especificada. Especifique "latest" para empezar solo a partir de los cambios más recientes. No se puede usar junto con startingTimestamp. Se omite si el punto de control de streaming ya existe. Consulte Trabajar con el historial de tablas.
withEventTimeOrder	false	Divide la instantánea de tabla inicial en depósitos de tiempo de eventos para evitar que los registros se marquen incorrectamente como eventos en tiempo de ejecución y se quiten en consultas con estado con marcas de agua. No se puede cambiar después de que se haya iniciado el procesamiento inicial de instantáneas sin eliminar el punto de control. Disponible en Databricks Runtime 11.3 LTS y versiones posteriores. Consulte Procesamiento de instantáneas iniciales sin quitar datos.

Kafka

Use estas opciones con spark.readStream.format("kafka") o spark.read.format("kafka"):

Clave	Predeterminado	Descripción
assign	None	Particiones específicas que se van a consumir. Debe especificar exactamente una de las subscribeopciones , subscribePatterno assign . Valores válidos: una cadena JSON, como {"topicA":[0,1],"topicB":[2,4]}.
failOnDataLoss	true	Si se produce un error en la consulta si es posible que se hayan perdido datos, por ejemplo, debido a temas eliminados o truncamiento de desplazamiento. Establézcalo en false para omitir los datos que faltan y continuar. Valores válidos: true, false. Databricks calcula de forma conservadora si es posible que se hayan perdido los datos. Sin embargo, esto podría causar falsas alarmas.
fetchoffset.numretries	3	Se produce un error en el número de reintentos al capturar desplazamientos de Kafka. Valores válidos: enteros no negativos.
fetchoffset.retryintervalms	1000	Intervalo en milisegundos entre reintentos de captura de desplazamiento. Valores válidos: enteros no negativos.
groupIdPrefix	spark-kafka-source (streaming), spark-kafka-relation (lote)	Prefijo personalizado que se va a usar para el identificador de grupo de consumidores de Kafka generado automáticamente. Si kafka.group.id se establece explícitamente, el conector omite esta opción. Valores válidos: cualquier cadena.
includeHeaders	false	Si se deben incluir encabezados de mensaje de Kafka como una columna en la salida. Valores válidos: true, false.
kafkaconsumer.polltimeoutms	None	Tiempo de espera en milisegundos para la llamada de consumidor poll() de Kafka. Valores válidos: enteros positivos.
kafka.bootstrap.servers	None	Una lista separada por comas de direcciones host:port para agentes de Kafka. Establece la propiedad del cliente de bootstrap.servers Kafka. Si encuentra que no hay datos de Kafka, compruebe esta lista de direcciones de agente para ver direcciones incorrectas. Si la lista de direcciones del agente es incorrecta, es posible que no haya errores. Los clientes de Kafka asumen que los agentes estarán disponibles finalmente y volverán a intentarlo para siempre cuando reciban errores de red.
maxRecordsPerPartition	None	Número máximo de registros para cada partición de Spark. Cuando se establece, el conector divide las particiones de Kafka para que cada partición de Spark lea como máximo estos muchos registros. Valores válidos: enteros positivos. También puede usar esta opción con minPartitions. Cuando se establecen ambas opciones, Spark usa cualquier opción que tenga como resultado más particiones.
minPartitions	None	Número mínimo de particiones de Spark que se van a leer desde Kafka. Cuando se establece, el conector divide particiones grandes de Kafka para aumentar el paralelismo. Cuando no se establece, Spark crea una partición para cada partición de tema de Kafka. Resulta útil para controlar la asimetría de datos o las cargas máximas. Valores válidos: enteros positivos. Esta opción reinicializa los consumidores de Kafka para cada desencadenador, lo que podría afectar al rendimiento con SSL.
startingOffsets	latest (streaming), earliest (lote)	Desplazamiento desde el que comienza la consulta. Valores válidos: earliest, latesto una cadena JSON de desplazamientos para cada partición, como {"topicA":{"0":23,"1":-2}}. En la cadena JSON, -1 es el desplazamiento más reciente. -2 es el desplazamiento más antiguo. En el caso de las consultas de streaming, esta opción solo se aplica cuando se inicia una nueva consulta. Las consultas reanudadas siempre usan el punto de control. Durante una consulta, las nuevas particiones comienzan a leer el desplazamiento más pronto. En el caso de las consultas por lotes, latest no se permite.
startingOffsetsByTimestamp	None	Lista de desplazamientos iniciales para cada partición, especificadas como marcas de tiempo en milisegundos. Cuando no existe ningún desplazamiento para una marca de tiempo, el comportamiento de la consulta viene determinado por startingOffsetsByTimestampStrategy. Valores válidos: una cadena JSON de marcas de tiempo para cada partición, como {"topicA":{"0":1000,"1":2000}}. En el caso de las consultas de streaming, esta opción solo se aplica cuando se inicia una nueva consulta. Las consultas reanudadas siempre usan el punto de control. Durante una consulta, las nuevas particiones comienzan a leer el desplazamiento más pronto.
startingOffsetsByTimestampStrategy	error	Estrategia que se va a usar cuando no se encuentra ningún desplazamiento para una marca de tiempo especificada en startingOffsetsByTimestamp o startingTimestamp. Valores válidos: error (genera una excepción), latest (usa el desplazamiento disponible más reciente).
startingTimestamp	None	Marca de tiempo de inicio global en milisegundos que se aplica a todas las particiones. Cuando no existe ningún desplazamiento para la marca de tiempo, el comportamiento se controla mediante startingOffsetsByTimestampStrategy. Valores válidos: enteros no negativos.
subscribe	None	Temas a los que suscribirse. Debe especificar exactamente una de las subscribeopciones , subscribePatterno assign . Valores válidos: una lista separada por comas de nombres de tema.
subscribePattern	None	Patrón que se usa para suscribirse a temas. Debe especificar exactamente una de las subscribeopciones , subscribePatterno assign . Por ejemplo: topic.*. Valores válidos: cualquier cadena regex de Java.

Las siguientes opciones solo se aplican a las lecturas de streaming con spark.readStream.format("kafka"):

Clave	Predeterminado	Descripción
bytesEstimateWindowLength	300s	Período de tiempo usado para calcular los bytes restantes de la estimatedTotalBytesBehindLatest métrica. Valores válidos: cadenas de duración como 10m o 600s. Consulte Recuperación de métricas de Kafka.
maxOffsetsPerTrigger	None	Número máximo de desplazamientos que se van a procesar por intervalo de desencadenador. Los desplazamientos se distribuyen proporcionalmente entre particiones de tema. Valores válidos: enteros positivos.
maxTriggerDelay	15m	Tiempo máximo para esperar minOffsetsPerTrigger a que se acumule antes de desencadenarse. Valores válidos: cadenas de duración como 10m o 600s.
minOffsetsPerTrigger	None	Número mínimo de desplazamientos que se van a acumular antes de desencadenar un microproceso. Cuando maxTriggerDelay se alcanza, el microproceso se ejecuta independientemente. Valores válidos: enteros positivos.

Para ver las opciones de desplazamiento que solo se aplican a las lecturas por lotes con spark.read.format("kafka"), consulte Opciones de Kafka DataFrameReader.

Para ver las opciones de cliente de Kafka (kafka.*) y autenticación, consulte Opciones.

Opciones de DataFrameWriter

Use estas opciones con DataFrameWriter.option() y DataFrameWriterV2.option() para controlar cómo Azure Databricks escribe datos.

Example

En el ejemplo siguiente se establece mergeSchema en True para escribir una tabla de Delta Lake:

Python

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

Scala

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

Avro

Clave	Predeterminado	Descripción
avroSchema	None	Esquema avro completo como una cadena JSON. Use esta opción para convertir tipos de Spark SQL a tipos específicos de Avro. Se aplica al archivo Avro.
avroSchemaUrl	None	Dirección URL que apunta a un archivo de esquema de Avro. Use en lugar de avroSchema cuando el esquema se almacene externamente. Mutuamente excluyente con avroSchema. Se aplica al archivo Avro.
compression	snappy	Códec de compresión que se va a usar al escribir. Valores válidos: uncompressed, deflate, snappy, bzip2, xz, . zstandard Se aplica al archivo Avro.
recordName	topLevelRecord	Nombre de registro de nivel superior en el esquema avro de salida. Se aplica al archivo Avro.
positionalFieldMatching	false	Si se deben buscar coincidencias con las columnas entre el esquema de Spark y el esquema avro por posición de campo en lugar de por nombre. Se aplica al archivo Avro.
recordNamespace	Cadena vacía	Espacio de nombres para el registro de nivel superior en el esquema avro de salida. Se aplica al archivo Avro.

Delta Lake y Apache Iceberg

Clave	Predeterminado	Descripción
clusterByAuto	false	Si se habilita la agrupación en clústeres líquidos automáticas, donde Azure Databricks selecciona columnas de agrupación en clústeres en función de los patrones de consulta. Solo es válido con mode("overwrite"). No se puede usar con append el modo . Disponible en Databricks Runtime 16.4 y versiones posteriores. Se aplica al uso de clústeres líquidos para tablas.
mergeSchema	None	Si se va a habilitar la evolución del esquema para la operación de escritura. Las nuevas columnas del dataframe de origen se agregan al esquema de la tabla de destino. Se aplica a los anexos por lotes y streaming. Se aplica al esquema de la tabla de actualización.
overwriteSchema	None	Si se va a reemplazar el esquema de tabla y la creación de particiones al sobrescribir. Requiere mode("overwrite") sin replaceWhere. No se puede usar con partitionOverwriteMode. Se aplica al esquema de la tabla de actualización.
partitionOverwriteMode	None	Modo de sobrescritura de partición. Establézcalo dynamic en para sobrescribir solo las particiones que contienen nuevos datos, dejando sin cambios todas las demás particiones. Modo heredado, no compatible con el proceso sin servidor o Databricks SQL. Valores válidos: static, dynamic. Se aplica a la sobrescritura selectiva de datos con Delta Lake.
replaceOn	None	Expresión booleana que coincide con las filas de la tabla de destino para reemplazar por filas de la consulta de origen. Puede hacer referencia a columnas de la tabla de destino y de la consulta de origen. Las filas del destino que coinciden con una fila de origen se eliminan y reemplazan. Si el origen está vacío, no se produce ninguna eliminación. Use targetAlias para desambiguar las referencias de columna. Disponible en Databricks Runtime 17.1 y versiones posteriores. Se aplica a la sobrescritura selectiva de datos con Delta Lake.
replaceUsing	None	Lista separada por comas de nombres de columna que se usan para buscar coincidencias entre la tabla de destino y la consulta de origen. Tanto el destino como el origen deben contener todas las columnas enumeradas. Las filas del destino que coinciden con una fila de origen en la comparación de igualdad se eliminan y reemplazan. NULL los valores se tratan como no iguales y no coinciden. Disponible en Databricks Runtime 16.3 y versiones posteriores. Se aplica a la sobrescritura selectiva de datos con Delta Lake.
replaceWhere	None	Expresión de predicado. Sobrescribe de forma atómica solo los registros que coinciden con el predicado. Se aplica a la sobrescritura selectiva de datos con Delta Lake.
targetAlias	None	Alias de cadena para la tabla de destino. Use con replaceOn o replaceWhere para desambiguar las referencias de columna cuando la condición hace referencia a columnas de la tabla de destino y de la consulta de origen. Se aplica a la sobrescritura selectiva de datos con Delta Lake.
txnAppId	None	Cadena única que identifica la aplicación para escrituras idempotentes en foreachBatch operaciones. Use junto con txnVersion para garantizar escrituras exactamente una vez en varias tablas de Delta Lake. Se aplica a Uso foreachBatch para escrituras de tabla idempotentes.
txnVersion	None	Número que aumenta de forma monotónica que se usa como versión de transacción para escrituras idempotentes en foreachBatch operaciones. Use junto con txnAppId para garantizar escrituras exactamente una vez en varias tablas de Delta Lake. Se aplica a Uso foreachBatch para escrituras de tabla idempotentes.
optimizeWrite	None	Indica si se va a habilitar la escritura de optimización automática para esta operación de escritura. Invalida la spark.databricks.delta.optimizeWrite.enabled configuración. Se aplica a ¿Qué es Delta Lake en Azure Databricks?.
userMetadata	None	Cadena definida por el usuario anexada a los metadatos de confirmación de la operación de escritura. Visible en la salida de DESCRIBE HISTORY. Se aplica a Las tablas enriquecidas con metadatos personalizados.

CSV

Clave	Predeterminado	Descripción
charToEscapeQuoteEscaping	\0 (no habilitado)	Carácter usado para escapar el carácter de escape cuando difiere del carácter de comillas. Se aplica a csv (DataFrameWriter).
compression	none	Códec de compresión que se va a usar al escribir. Valores válidos: none, bzip2, gziplz4, snappy, , deflate, . zstd Se aplica a csv (DataFrameWriter).
dateFormat	yyyy-MM-dd	Cadena de formato para los valores de columna de fecha. Se aplica a csv (DataFrameWriter).
emptyValue	Cadena vacía	Cadena escrita para valores vacíos (no NULL). Se aplica a csv (DataFrameWriter).
encoding	UTF-8	Codificación de caracteres para los archivos de salida. Se aplica a csv (DataFrameWriter).
escape	\	Carácter usado para escapar valores entre comillas. Se aplica a csv (DataFrameWriter).
escapeQuotes	true	Indica si se deben escapar los caracteres de comillas dentro de los valores de campo entre comillas. Se aplica a csv (DataFrameWriter).
header	false	Si se van a escribir nombres de columna como primera línea de la salida. Se aplica a csv (DataFrameWriter).
ignoreLeadingWhiteSpace	false	Si se va a recortar el espacio en blanco inicial de los valores al escribir. Se aplica a csv (DataFrameWriter).
ignoreTrailingWhiteSpace	false	Si se va a recortar el espacio en blanco final de los valores al escribir. Se aplica a csv (DataFrameWriter).
lineSep	\n	Cadena separadora de línea usada entre registros. Se aplica a csv (DataFrameWriter).
locale	en-US	Un identificador java.util.Locale. Influye en el formato de los valores de fecha y marca de tiempo al escribir.
nullValue	Cadena vacía	Cadena escrita para valores NULL. Se aplica a csv (DataFrameWriter).
quote	"	Carácter utilizado para comillas de valores de campo que contienen el separador. Se aplica a csv (DataFrameWriter).
quoteAll	false	Si se deben incluir todos los valores de campo entre comillas, independientemente del contenido. Se aplica a csv (DataFrameWriter).
sep	,	Carácter delimitador de campo. Se aplica a csv (DataFrameWriter).
timestampFormat	yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]	Cadena de formato para los valores de columna de marca de tiempo. Se aplica a csv (DataFrameWriter).
timestampNTZFormat	yyyy-MM-dd'T'HH:mm:ss[.SSS]	Dar formato a la cadena para la marca de tiempo sin valores de columna de zona horaria (TimestampNTZType).

Excel

Clave	Predeterminado	Descripción
dataAddress	None	El nombre de la hoja o la celda inicial de la escritura. Si se omite, escribe en una hoja denominada Sheet1 a partir de la celda A1. Acepta un nombre de hoja ("SheetName") o una sola referencia de celda ("SheetName!A1"). No se admiten intervalos de celdas para escrituras.
dateFormatInWrite	yyyy-mm-dd	Excel cadena de formato de celda aplicada a Date columnas. Usa Excel sintaxis de formato.
headerRows	0	Si se van a escribir nombres de columna como primera fila. Valores válidos: 0, 1.
timestampNTZFormat	yyyy-mm-dd hh:mm:ss	Excel cadena de formato de celda aplicada a las columnas TimestampNTZ y Timestamp. Usa Excel sintaxis de formato.
version	xlsx	La versión de formato de archivo Excel que se va a escribir. Valores válidos: xlsx, xls.

JSON

Clave	Predeterminado	Descripción
compression	none	Códec de compresión que se va a usar al escribir. Valores válidos: none, bzip2, gziplz4, snappy, , deflate, . zstd Se aplica a json (DataFrameWriter).
dateFormat	yyyy-MM-dd	Cadena de formato para los valores de columna de fecha. Se aplica a json (DataFrameWriter).
encoding	UTF-8	Codificación de caracteres para los archivos de salida. Se aplica a json (DataFrameWriter).
ignoreNullFields	valor de spark.sql.jsonGenerator.ignoreNullFields	Si se van a omitir campos con valores NULL de la salida JSON. Se aplica a json (DataFrameWriter).
lineSep	\n	Cadena separadora de línea usada entre registros. Se aplica a json (DataFrameWriter).
locale	en-US	Un identificador java.util.Locale. Influye en el formato de los valores de fecha y marca de tiempo al escribir.
pretty	false	Indica si se va a habilitar la salida JSON bonita (con sangría y multilínea).
sortKeys	false	Si se ordenan las claves de los objetos JSON alfabéticamente en la salida. Resulta útil para producir resultados deterministas.
timestampFormat	yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]	Cadena de formato para los valores de columna de marca de tiempo. Se aplica a json (DataFrameWriter).
timestampNTZFormat	yyyy-MM-dd'T'HH:mm:ss[.SSS]	Dar formato a la cadena para la marca de tiempo sin valores de columna de zona horaria (TimestampNTZType).
writeNonAsciiCharacterAsCodePoint	false	Si se deben codificar caracteres no ASCII como \uXXXX secuencias de escape Unicode en lugar de caracteres UTF-8 literales en la salida.

ORC

Clave	Predeterminado	Descripción
compression	zstd	Códec de compresión que se va a usar al escribir. Valores válidos: none, uncompressed, snappy, zlib, lzozstd, , lz4brotli. Se aplica a orc (DataFrameWriter).

Parquet

Clave	Predeterminado	Descripción
compression	snappy	Códec de compresión que se va a usar al escribir. Valores válidos: none, uncompressed, snappy, gzip, brotlilzo, lz4, , lz4_raw, zstd. Se aplica a parquet (DataFrameWriter).
spark.sql.parquet.outputTimestampType	INT96	Tipo físico que se usa para codificar columnas de marca de tiempo. Valores válidos: INT96, TIMESTAMP_MICROS, TIMESTAMP_MILLIS. Se usa INT96 para la compatibilidad con lectores de Parquet heredados que no admiten los tipos de marca de tiempo estándar.

Texto

Clave	Predeterminado	Descripción
compression	none	Códec de compresión que se va a usar al escribir. Valores válidos: none, bzip2, gziplz4, snappy, , deflate, . zstd Se aplica al texto (DataFrameWriter).
encoding	UTF-8	Codificación de caracteres para los archivos de salida.
lineSep	\n	Cadena separadora de línea usada entre registros. Se aplica al texto (DataFrameWriter).

XML

Clave	Predeterminado	Descripción
arrayElementName	item	Nombre del elemento de los elementos de matriz que no tienen ningún nombre explícito. Se aplica a xml (DataFrameWriter).
attributePrefix	_	Prefijo antepuesto a nombres de campo que corresponden a atributos XML. Se aplica a xml (DataFrameWriter).
compression	none	Códec de compresión que se va a usar al escribir. Valores válidos: none, bzip2, gziplz4, snappy, , deflate, . zstd Se aplica a xml (DataFrameWriter).
dateFormat	yyyy-MM-dd	Cadena de formato para los valores de columna de fecha. Se aplica a xml (DataFrameWriter).
declaration	version="1.0" encoding="UTF-8" standalone="yes"	Cadena de declaración XML escrita en la parte superior de cada archivo de salida. Establezca en una cadena vacía para suprimir la declaración. Se aplica a xml (DataFrameWriter).
encoding	UTF-8	Codificación de caracteres para los archivos de salida. Se aplica a xml (DataFrameWriter).
indent	4 espacios	Cadena usada para aplicar sangría a elementos secundarios en la salida. Establezca en una cadena vacía para desactivar la sangría y escribir cada fila en una sola línea.
locale	en-US	Un identificador java.util.Locale. Influye en el formato de los valores de fecha y marca de tiempo al escribir.
nullValue	null	Cadena escrita para valores NULL. Cuando se establece en null, se omiten atributos y elementos secundarios para campos NULL. Se aplica a xml (DataFrameWriter).
rootTag	ROWS	Etiqueta de elemento raíz que ajusta todos los elementos de fila de la salida. Se aplica a xml (DataFrameWriter).
rowTag	ROW	Etiqueta de elemento que representa una fila en la salida. Se aplica a xml (DataFrameWriter).
singleVariantColumn	None	Nombre de la única columna Variant que se va a escribir en archivos XML. Se aplica a xml (DataFrameWriter).
timestampFormat	yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]	Cadena de formato para los valores de columna de marca de tiempo. Se aplica a xml (DataFrameWriter).
timestampNTZFormat	yyyy-MM-dd'T'HH:mm:ss[.SSS]	Cadena de formato para la marca de tiempo sin valores de columna de zona horaria. Se aplica a xml (DataFrameWriter).
validateName	true	Si se produce una excepción si un nombre de columna no es un identificador de elemento XML válido. Se aplica a xml (DataFrameWriter).
valueTag	_VALUE	Nombre de campo usado para los datos de caracteres en elementos XML que también tienen atributos o elementos secundarios. Se aplica a xml (DataFrameWriter).

Opciones de DataStreamWriter

Use estas opciones con DataStreamWriter.option() para configurar escrituras de streaming.

Example

En el ejemplo siguiente se establece la ubicación del punto de control de una secuencia:

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

Común

Clave	Predeterminado	Descripción
checkpointLocation	Ninguno (obligatorio)	Ruta de acceso al directorio de punto de control de la consulta de streaming. Necesario para la tolerancia a errores y garantías de procesamiento exactamente una vez. Cada consulta de streaming debe usar una ubicación de punto de control única. Databricks recomienda almacenar puntos de control en un volumen del catálogo de Unity o en una ruta de acceso de almacenamiento en la nube. Consulte Puntos de control de Structured Streaming.
path	None	Ruta de acceso de salida para receptores de streaming basados en archivos, como Parquet. Solo se aplica a formatos basados en archivos.

Receptor de consola

Clave	Predeterminado	Descripción
numRows	20	Número de filas que se van a mostrar para cada microproceso al escribir en el receptor de la consola.
truncate	true	Si se truncan cadenas largas al mostrar filas. Establézcalo en false para mostrar valores de cadena completos.

Delta Lake

Las siguientes opciones se aplican al escribir una secuencia en una tabla de Delta Lake mediante format("delta"). No se admiten opciones de solo sobrescritura como overwriteSchema, replaceWherey partitionOverwriteMode para escrituras de streaming.

Clave	Predeterminado	Descripción
mergeSchema	false	Si va a evolucionar el esquema de tabla de Delta Lake cuando el dataframe de streaming contiene nuevas columnas. Solo se aplica al modo de salida anexado. Se aplica al esquema de la tabla de actualización.
userMetadata	None	Cadena definida por el usuario anexada a los metadatos de confirmación de la operación de escritura. Visible en la salida de DESCRIBE HISTORY. Se aplica a Las tablas enriquecidas con metadatos personalizados.

Receptor de archivos

La siguiente opción se aplica al escribir una secuencia en formatos basados en archivos (Parquet, JSON, CSV, ORC, text). Para obtener opciones específicas del formato, consulte Opciones de DataFrameWriter.

Clave	Predeterminado	Descripción
retention	None	Cuánto tiempo se conservan los archivos de metadatos receptores usados para la tolerancia a errores y la compactación. Acepta una cadena de tiempo como 7 days o 24 hours. Cuando no se establece, los archivos de metadatos se conservan indefinidamente.

Receptor de Kafka

Para obtener una lista completa de las opciones para escribir secuencias en Kafka, consulte Opciones.

Clave	Predeterminado	Descripción
kafka.bootstrap.servers	None	Required. Lista separada por comas de direcciones de agente host:port de Kafka.
topic	None	Tema de Kafka de destino para todas las filas. Obligatorio si dataFrame no incluye una topic columna.
kafka.*	None	Cualquier configuración del productor de Kafka con kafka.el prefijo . Por ejemplo: kafka.compression.type.

Receptor de memoria

Clave	Predeterminado	Descripción
queryName	Ninguno (obligatorio)	Nombre de la tabla en memoria en la que escribe la consulta. Necesario para el receptor de memoria. También se puede configurar a través de .queryName().
mode	exactlyonce	Garantía de entrega para el receptor de memoria. exactlyonce usa el modo micro-batch con semántica exactamente una vez. atleastonce usa el modo continuo con semántica de al menos una vez. Valores válidos: exactlyonce, atleastonce.

Opciones de funciones de Spark

Algunas funciones integradas de Spark SQL aceptan un options mapa que controla el comportamiento de análisis o serialización. Pase las opciones como Python dict o Scala Map[String, String].

Example

En el ejemplo siguiente se analiza una columna JSON al quitar registros con formato incorrecto:

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

Las funciones de Avro aceptan las mismas opciones que las opciones de DataFrame correspondientes:

• from_avro y schema_of_avro use las opciones de Avro DataFrameReader.
• to_avro usa las opciones de DataFrameWriter Avro.

Example

En el ejemplo siguiente se descodifica una columna avro con la evolución del esquema habilitada:

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

Además, las variantes del Registro de esquema de from_avro y to_avro aceptan las siguientes opciones:

Clave	Predeterminado	Descripción
schemaId	None	Identificador de esquema del Registro de esquemas de Confluent que se usará al descodificar datos de Avro que se codificaron con un esquema incompatible con jsonFormatSchema. Solo se aplica a from_avro .
confluent.schema.registry.*	None	Propiedades de configuración del cliente del Registro de esquemas de Confluent. Pase cualquier propiedad de cliente sr de Confluent mediante este prefijo, por ejemplo confluent.schema.registry.basic.auth.user.info , para las credenciales de autenticación básicas. Necesario para las variantes del Registro de esquema de from_avro y to_avro.

CSV

Las funciones CSV aceptan las mismas opciones que las correspondientes opciones de DataFrame:

• from_csv y schema_of_csv usan las opciones de CSV DataFrameReader.
• to_csv usa las opciones de CSV DataFrameWriter.

Example

En el ejemplo siguiente se lee CSV con un separador y NULL un valor personalizados:

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

Las funciones JSON aceptan las mismas opciones que las opciones de DataFrame correspondientes:

• from_json y schema_of_json usar las opciones JSON dataFrameReader.
• to_json usa las opciones JSON dataFrameWriter.

Example

En el ejemplo siguiente se escribe JSON con NULL campos omitido y con formato bonito habilitado:

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 y to_protobuf no usan un DataSource basado en archivos. Los datos protobuf siempre se leen y escriben como columnas binarias mediante estas funciones. Las opciones se pasan como Map[String, String] y distinguen mayúsculas de minúsculas.

Example

En el ejemplo siguiente se descodifica una columna Protobuf mediante el modo PERMISSIVE:

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

Las funciones protobuf usan las siguientes opciones:

Clave	Predeterminado	Descripción
mode	FAILFAST	Cómo controlar registros dañados. FAILFAST genera una excepción. PERMISSIVE establece los campos con formato incorrecto en NULL. Valores válidos: FAILFAST, PERMISSIVE. Se aplica a from_protobuf.
recursive.fields.max.depth	-1 (deshabilitado)	Profundidad máxima de recursión para campos Protobuf recursivos. Establézcalo en 0 para desactivar la compatibilidad con campos recursivos. Valores válidos: 0 en 10. Se aplica a from_protobuf.
convert.any.fields.to.json	false	Si se van a convertir campos protobuf Any en una cadena JSON en lugar de .STRUCT Se aplica a from_protobuf.
emit.default.values	false	Si se deben emitir campos con cero o valores predeterminados (semántica proto3). Cuando false, los campos con valores predeterminados se omiten de la salida. Se aplica a from_protobuf.
enums.as.ints	false	Indica si se deben representar campos de enumeración como valores enteros en lugar de cadenas. Se aplica a from_protobuf.
upcast.unsigned.ints	false	Indica si se va a realizar la difusión uint32 a Long y uint64 a para Decimal(20,0) evitar el desbordamiento de enteros. Se aplica a from_protobuf.
unwrap.primitive.wrapper.types	false	Si se van a desencapsular google.protobuf los tipos de contenedor (por ejemplo, Int32Value y StringValue) a sus tipos primitivos de Spark correspondientes. Se aplica a from_protobuf.
retain.empty.message.types	false	Si se deben conservar los tipos de mensaje Protobuf vacíos en el esquema de salida insertando una columna ficticia. Se aplica a from_protobuf.
schema.registry.subject	None	Nombre del firmante del Registro de esquema. Necesario cuando se usan las variantes del Registro de esquema de from_protobuf y to_protobuf.
schema.registry.address	None	Dirección del Registro de esquema (host y puerto). Necesario cuando se usan las variantes del Registro de esquema de from_protobuf y to_protobuf.
schema.registry.protobuf.name	None	Especifica el mensaje Protobuf que se va a usar cuando el asunto del Registro de esquema contiene varios mensajes. Opcional.

XML

Las funciones XML aceptan las mismas opciones que las opciones de DataFrame correspondientes:

• from_xml y schema_of_xml usar las opciones XML de DataFrameReader.
• to_xml usa las opciones XML dataFrameWriter.

Example

En el ejemplo siguiente se escribe XML con etiquetas de fila y raíz personalizadas:

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