Compartir a través de

read_files función con valores de tabla

Se aplica a:casilla marcada como sí Databricks SQL casilla marcada como sí Databricks Runtime 13.3 LTS y versiones posteriores

Lee los archivos en una ubicación proporcionada y devuelve los datos en formato tabular.

Admite la lectura de formatos de archivo JSON, CSV, XML, TEXT, BINARYFILE, PARQUET, AVRO y ORC. Puede detectar el formato de archivo automáticamente e inferir un esquema unificado en todos los archivos.

Sintaxis

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

Argumentos

Esta función requiere la invocación de parámetros con nombre para las claves de opción.

  • path: Un STRING con el URI de la ubicación de los datos. Admite la lectura desde Azure Data Lake Storage ('abfss://'), S3 (s3://) y Google Cloud Storage ('gs://'). Puede contener globs. Vea Detección de archivos para más información.
  • option_key: nombre de la opción que se va a configurar. Es necesario utilizar puntos suspensivos () for options that contain dots (.`).
  • option_value: una expresión constante para establecer la opción. Acepta literales y funciones escalares.

Devoluciones

Una tabla formada por los datos de los archivos leídos en la path dada.

Detección de archivos

read_files puede leer un archivo individual o leer archivos en un directorio proporcionado. read_files detecta todos los archivos del directorio proporcionado de manera recursiva a menos que se proporcione un glob, lo que instruye a read_files para que implemente una recursión en un patrón de directorio específico.

Filtrado de directorios o archivos mediante patrones globales

Los patrones globales se pueden usar para filtrar directorios y archivos cuando se proporcionan en la ruta de acceso.

Patrón Descripción
? Coincide con cualquier carácter individual
* Coincide con cero o más caracteres
[abc] Coincide con un solo carácter del juego de caracteres {a,b,c}.
[a-z] Coincide con un solo carácter del intervalo de caracteres {a...z}.
[^a] Coincide con un solo carácter que no es del juego de caracteres o el intervalo {a}. Tenga en cuenta que el carácter ^ debe aparecer inmediatamente a la derecha del corchete de apertura.
{ab,cd} Coincide con una cadena del conjunto de cadenas {ab, cd}.
{ab,c{de, fh}} Coincide con una cadena del conjunto de cadenas {ab, cde, cfh}.

read_files usa el globber estricto de Auto Loader al detectar archivos con globs. Esto se configura mediante la opción useStrictGlobber. Cuando se deshabilita el patrón global estricto, se quitan las barras diagonales finales (/) y puede expandirse un patrón de estrella como /*/ para detectar varios directorios. Consulte los ejemplos siguientes para ver la diferencia en el comportamiento.

Patrón Ruta de acceso del archivo Patrón global estricto deshabilitado Patrón global estricto habilitado
/a/b /a/b/c/file.txt Sí Sí
/a/b /a/b_dir/c/file.txt No No
/a/b /a/b.txt No No
/a/b/ /a/b.txt No No
/a/*/c/ /a/b/c/file.txt Sí Sí
/a/*/c/ /a/b/c/d/file.txt Sí Sí
/a/*/d/ /a/b/c/d/file.txt Sí No
/a/*/c/ /a/b/x/y/c/file.txt Sí No
/a/*/c /a/b/c_file.txt Sí No
/a/*/c/ /a/b/c_file.txt Sí No
/a/*/c /a/b/cookie/file.txt Sí No
/a/b* /a/b.txt Sí Sí
/a/b* /a/b/file.txt Sí Sí
/a/{0.txt,1.txt} /a/0.txt Sí Sí
/a/*/{0.txt,1.txt} /a/0.txt No No
/a/b/[cde-h]/i/ /a/b/c/i/file.txt Sí Sí

Inferencia de esquemas

El esquema de los archivos se puede proporcionar explícitamente a read_files con la opción schema. Cuando no se proporciona el esquema, read_files intenta deducir un esquema unificado en los archivos detectados, lo que requiere leer todos los archivos a menos que se use una instrucción LIMIT. Incluso cuando se usa una consulta LIMIT, es posible que se lea un conjunto mayor de archivos de los necesarios para devolver un esquema más representativo de los datos. Databricks agrega automáticamente una LIMIT instrucción para las consultas SELECT en cuadernos y en el editor de SQL en caso de que el usuario no haya proporcionado una.

La opción schemaHints se puede usar para corregir subconjuntos del esquema inferido. Consulte Anulación de la inferencia de esquemas con sugerencias de esquemas para obtener más detalles.

Un rescuedDataColumn se proporciona de forma predeterminada para rescatar cualquier dato que no coincida con el esquema. Para obtener más información, consulte ¿Qué es la columna de datos rescatados? Puede quitar rescuedDataColumn si establece la opción schemaEvolutionMode => 'none'.

Inferencia de esquema de partición

read_files también puede deducir columnas de particiones si los archivos se almacenan en directorios con particiones de estilo Hive, es decir, /column_name=column_value/. Si se proporciona un schema, las columnas de partición detectadas usan los tipos proporcionados en schema. Si las columnas de partición no forman parte del schema proporcionado, se omiten las columnas de partición inferidas.

Si existe una columna en el esquema de partición y en las columnas de datos, se usa el valor que se lee del valor de partición en lugar del valor de datos. Si desea omitir los valores procedentes del directorio y usar la columna de datos, puede proporcionar la lista de columnas de partición en una lista separada por comas con la opción partitionColumns.

La opción partitionColumns también se puede usar para indicar a read_files qué columnas detectadas se van a incluir en el esquema inferido final. Si se proporciona una cadena vacía, se omiten todas las columnas de partición.

También se puede proporcionar la opción schemaHints para invalidar el esquema inferido de una columna de partición.

Los formatos TEXT y BINARYFILE tienen un esquema fijo, pero read_files también intenta deducir la creación de particiones para estos formatos siempre que sea posible.

Uso en tablas de streaming

read_files se puede usar en tablas de streaming para introducir archivos en el Delta Lake. read_files aprovecha Auto Loader cuando se usa en una consulta de tabla de streaming. Debe usar la palabra clave STREAM con read_files. Para obtener más información, consulte ¿Qué es Auto Loader?.

Cuando se usa en una consulta de streaming, read_files usa un ejemplo de los datos para deducir el esquema y puede evolucionar el esquema a medida que procesa más datos. Consulte Configuración de inferencia y evolución de esquemas en Auto Loader para obtener más detalles.

Opciones

Opciones básicas

Opción
format
Tipo: String
El formato del archivo de datos en la ruta de origen. Inferido automáticamente si no se proporciona. Los valores permitidos son:

Valor predeterminado: ninguno
inferColumnTypes
Tipo: Boolean
Indica si se infieren los tipos de columna exactos al aprovechar la inferencia de esquema. De manera predeterminada, las columnas se infieren al inferir conjuntos de datos JSON y CSV. Consulte Inferencia de esquemas para obtener más detalles. Tenga en cuenta que esto es lo contrario del valor predeterminado de Auto Loader.
Valor predeterminado: true
partitionColumns
Tipo: String
Lista separada por comas de columnas de partición de estilo Hive que le gustaría inferir de la estructura de directorios de los archivos. Las columnas de partición de estilo Hive son pares clave-valor combinados por un signo igual, 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 agregarán 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
Si se especifica cloudFiles.partitionColumns como year,month,day, se devolverá
year=2022 para file1.csv, pero las columnas month y day serán null.
month y day se analizarán correctamente para file2.csv y file3.csv.
Valor predeterminado: ninguno
schemaHints
Tipo: String
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.
Valor predeterminado: ninguno
useStrictGlobber
Tipo: Boolean
Si se usa un patrón global estricto que coincida con el comportamiento global predeterminado de otros orígenes de archivos en Apache Spark. Para más detalles, consulte Patrones comunes de carga de datos. Disponible en Databricks Runtime 12.2 LTS y versiones posteriores. Tenga en cuenta que esto es lo contrario del valor predeterminado de Auto Loader.
Valor predeterminado: true

Opciones genéricas

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

Opción
ignoreCorruptFiles
Tipo: Boolean
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. Observable como numSkippedCorruptFiles en la
columna operationMetrics de la historia del Delta Lake. Disponible en Databricks Runtime 11.3 LTS y versiones posteriores.
Valor predeterminado: false
ignoreMissingFiles
Tipo: Boolean
Si se deben omitir los archivos que faltan. Si el valor es verdadero, los trabajos de Spark seguirán ejecutándose incluso si faltan archivos, y se devolverá el contenido que ya se haya leído. Disponible en Databricks Runtime 11.3 LTS y versiones posteriores.
Valor predeterminado: false para Auto Loader, true para COPY INTO (heredado)
modifiedAfter
Tipo: Timestamp String, por ejemplo, 2021-01-01 00:00:00.000000 UTC+0.
Se puede usar una marca de tiempo opcional como filtro para ingerir solo aquellos archivos que tengan una marca de tiempo de modificación posterior a la que se ha proporcionado.
Valor predeterminado: ninguno
modifiedBefore
Tipo: Timestamp String, por ejemplo, 2021-01-01 00:00:00.000000 UTC+0.
Marca de tiempo opcional como filtro para ingerir solo archivos que tengan una marca de tiempo de modificación antes de la marca de tiempo proporcionada.
Valor predeterminado: ninguno
pathGlobFilter o fileNamePattern
Tipo: String
Un posible patrón global para seleccionar archivos. Equivalente a
PATTERN en COPY INTO (heredado). fileNamePattern se puede usar en read_files.
Valor predeterminado: ninguno
recursiveFileLookup
Tipo: Boolean
Esta opción busca en directorios anidados incluso si sus nombres no siguen un esquema de nomenclatura de particiones como date=2019-07-01.
Valor predeterminado: false

JSON opciones

Opción
allowBackslashEscapingAnyCharacter
Tipo: Boolean
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.
Valor predeterminado: false
allowComments
Tipo: Boolean
Si se permite el uso de comentarios de estilo en Java, C y C++ (variedades '/', '*' y '//') dentro del contenido analizado o no.
Valor predeterminado: false
allowNonNumericNumbers
Tipo: Boolean
Si se permite el conjunto de tokens no numéricos (NaN) como valores numéricos flotantes legales.
Valor predeterminado: true
allowNumericLeadingZeros
Tipo: Boolean
Si se permite que los números enteros comiencen con ceros adicionales (que se pueden omitir) (por ejemplo, 000001).
Valor predeterminado: false
allowSingleQuotes
Tipo: Boolean
Si se permite el uso de comillas simples (apóstrofo, carácter '\') para citar cadenas (nombres y valores de cadena).
Valor predeterminado: true
allowUnquotedControlChars
Tipo: Boolean
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.
Valor predeterminado: false
allowUnquotedFieldNames
Tipo: Boolean
Si se permite el uso de nombres de campo sin comillas (permitidos en JavaScript, pero no en la especificación JSON).
Valor predeterminado: false
badRecordsPath
Tipo: String
La ruta para almacenar los archivos para registrar la información sobre los registros JSON defectuosos.
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.

Valor predeterminado: ninguno
columnNameOfCorruptRecord
Tipo: String
La columna para almacenar los registros con formato incorrecto y que no se pueden analizar. Si el mode para el análisis se configura como DROPMALFORMED, esta columna estará vacía.
Valor predeterminado: _corrupt_record
dateFormat
Tipo: String
Formato para analizar las cadenas de fecha.
Valor predeterminado: yyyy-MM-dd
dropFieldIfAllNull
Tipo: Boolean
Si se deben ignorar las columnas que contienen todos los valores null o las matrices y estructuras vacías durante la inferencia del esquema.
Valor predeterminado: false
encoding o charset
Tipo: String
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.
Valor predeterminado: UTF-8
inferTimestamp
Tipo: Boolean
Si se debe intentar inferir cadenas de marcas de tiempo como TimestampType. Cuando se establece en
true, la inferencia de esquema puede tardar notablemente más tiempo. Debe habilitar cloudFiles.inferColumnTypes para usar con Auto Loader.
Valor predeterminado: false
lineSep
Tipo: String
Una cadena entre dos registros JSON consecutivos.
Valor predeterminado: None, que abarca \r, \r\n y \n.
locale
Tipo: String
Un identificador java.util.Locale. Influye en la fecha predeterminada, la marca de tiempo y el análisis decimal dentro de JSON.
Valor predeterminado: US
mode
Tipo: String
Modo de analizador para el control de registros con formato incorrecto. Uno dePERMISSIVE, DROPMALFORMED o FAILFAST.
Valor predeterminado: PERMISSIVE
multiLine
Tipo: Boolean
Si los registros JSON abarcan varias líneas.
Valor predeterminado: false
prefersDecimal
Tipo: Boolean
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 bien usando cloudFiles.inferColumnTypes con el Auto Loader.
Valor predeterminado: false
primitivesAsString
Tipo: Boolean
Si se deben inferir tipos primitivos como números y booleanos como StringType.
Valor predeterminado: false
readerCaseSensitive
Tipo: Boolean
Especifica el comportamiento de distinción entre mayúsculas y minúsculas cuando rescuedDataColumn está habilitado. Si es verdadero, rescata las columnas de datos cuyos nombres difieren por mayúsculas y minúsculas del esquema; en caso contrario, lee los datos de forma que no distingue entre mayúsculas y minúsculas. Disponible en Databricks Runtime
13.3 y versiones posteriores.
Valor predeterminado: true
rescuedDataColumn
Tipo: String
Si se recopilan todos los datos que no se pueden analizar por un error de coincidencia de tipos de datos o a una falta de coincidencia de esquemas (incluido el uso de 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.
Valor predeterminado: ninguno
singleVariantColumn
Tipo: String
Si se debe ingerir todo el documento JSON, analizado en una sola columna Variant con la cadena especificada como el nombre de la columna. Si se deshabilita, los campos JSON serán ingeridos en sus propias columnas.
Valor predeterminado: ninguno
timestampFormat
Tipo: String
Formato para analizar cadenas de marca de tiempo.
Valor predeterminado: yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]
timeZone
Tipo: String
El java.time.ZoneId que se utilizará cuando se analicen marcas de tiempo y fechas.
Valor predeterminado: ninguno

CSV opciones

Opción
badRecordsPath
Tipo: String
La ruta para almacenar los archivos para registrar la información sobre los registros CSV erróneos.
Valor predeterminado: ninguno
charToEscapeQuoteEscaping
Tipo: Char
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].

Valor predeterminado: '\0'
columnNameOfCorruptRecord
Compatible con el Cargador automático. No se admite para COPY INTO (heredado).
Tipo: String
La columna para almacenar los registros con formato incorrecto y que no se pueden analizar. Si el mode para el análisis se configura como DROPMALFORMED, esta columna estará vacía.
Valor predeterminado: _corrupt_record
comment
Tipo: Char
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.
Valor predeterminado: '\u0000'
dateFormat
Tipo: String
Formato para analizar las cadenas de fecha.
Valor predeterminado: yyyy-MM-dd
emptyValue
Tipo: String
Representación de cadena de un valor vacío.
Valor predeterminado: ""
encoding o charset
Tipo: String
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.
Valor predeterminado: UTF-8
enforceSchema
Tipo: Boolean
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.
Valor predeterminado: true
escape
Tipo: Char
Carácter de escape que se usará al analizar los datos.
Valor predeterminado: '\'
header
Tipo: Boolean
Si los archivos CSV contienen encabezado. Auto Loader supone que los archivos tienen encabezados al inferir el esquema.
Valor predeterminado: false
ignoreLeadingWhiteSpace
Tipo: Boolean
Si se omiten los espacios en blanco iniciales en los valores analizados.
Valor predeterminado: false
ignoreTrailingWhiteSpace
Tipo: Boolean
Si se omiten los espacios en blanco finales en los valores analizados.
Valor predeterminado: false
inferSchema
Tipo: Boolean
Si se debe inferir el tipo de dato de los registros CSV analizados o se supone que todas las columnas son de StringType. Requiere una pasada adicional sobre los datos si se establece en true. Para el Cargador automático, use cloudFiles.inferColumnTypes en su lugar.
Valor predeterminado: false
lineSep
Tipo: String
Cadena entre dos registros CSV consecutivos.
Valor predeterminado: None, que abarca \r, \r\n y \n.
locale
Tipo: String
Un identificador java.util.Locale. Influye en la fecha predeterminada, la marca de tiempo y el análisis decimal dentro de CSV.
Valor predeterminado: US
maxCharsPerColumn
Tipo: Int
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.
Valor predeterminado: -1
maxColumns
Tipo: Int
Límite máximo de columnas que puede tener un registro.
Valor predeterminado: 20480
mergeSchema
Tipo: Boolean
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.
Valor predeterminado: false
mode
Tipo: String
Modo de analizador para el control de registros con formato incorrecto. Uno de 'PERMISSIVE',
'DROPMALFORMED' y 'FAILFAST'.
Valor predeterminado: PERMISSIVE
multiLine
Tipo: Boolean
Si los registros CSV abarcan varias líneas.
Valor predeterminado: false
nanValue
Tipo: String
Representación de cadena de un valor no numérico al analizar columnas FloatType y DoubleType.
Valor predeterminado: "NaN"
negativeInf
Tipo: String
Representación de cadena de infinito negativo al analizar columnas FloatType o DoubleType.
Valor predeterminado: "-Inf"
nullValue
Tipo: String
Representación de cadena de un valor NULL.
Valor predeterminado: ""
parserCaseSensitive (en desuso)
Tipo: Boolean
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 difieran según el caso se rescatarán en el rescuedDataColumn si está habilitado. Esta opción ha quedado en desuso en favor de readerCaseSensitive.
Valor predeterminado: false
positiveInf
Tipo: String
Representación de cadena del infinito positivo al analizar columnas FloatType o DoubleType.
Valor predeterminado: "Inf"
preferDate
Tipo: Boolean
Intentar inferir cadenas como fechas en lugar de una marca de tiempo cuando sea posible. También debe usar la inferencia de esquemas, ya sea habilitando inferSchema o usando
cloudFiles.inferColumnTypes con Cargador Automático.
Valor predeterminado: true
quote
Tipo: Char
Carácter utilizado para escapar valores en los que el delimitador de campo forma parte del valor.
Valor predeterminado: "
readerCaseSensitive
Tipo: Boolean
Especifica el comportamiento de distinción entre mayúsculas y minúsculas cuando rescuedDataColumn está habilitado. Si es verdadero, rescata las columnas de datos cuyos nombres difieren por mayúsculas y minúsculas del esquema; en caso contrario, lee los datos de forma que no distingue entre mayúsculas y minúsculas.
Valor predeterminado: true
rescuedDataColumn
Tipo: String
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.
Valor predeterminado: ninguno
sep o delimiter
Tipo: String
Cadena separadora de columnas.
Valor predeterminado: ","
skipRows
Tipo: Int
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.
Valor predeterminado: 0
timestampFormat
Tipo: String
Formato para analizar cadenas de marca de tiempo.
Valor predeterminado: yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]
timeZone
Tipo: String
El java.time.ZoneId que se utilizará cuando se analicen marcas de tiempo y fechas.
Valor predeterminado: ninguno
unescapedQuoteHandling
Tipo: String
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 encontrasen comillas sin escape en la entrada, un
    TextParsingException será producido.

Valor predeterminado: STOP_AT_DELIMITER

XML opciones

Opción Descripción Ámbito
rowTag La etiqueta de fila de los archivos XML que se van a tratar como fila. En el XML <books> <book><book>...<books> de ejemplo, el valor adecuado es book. Esta es una opción necesaria. leer
samplingRatio Define una fracción de filas usadas para la inferencia de esquema. Las funciones integradas XML omiten esta opción. Predeterminado: 1.0. leer
excludeAttribute Si se excluyen los atributos en los elementos. Predeterminado: false. leer
mode 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 mantener los registros corruptos, puede establecer un campo de tipo string nombrado 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.		 leer
inferSchema Si true, intenta inferir un tipo adecuado para cada columna del DataFrame resultante. Si false, todas las columnas resultantes son de tipo string. Valor predeterminado:
true. Las funciones integradas XML omiten esta opción.		 leer
columnNameOfCorruptRecord Permite cambiar el nombre del nuevo campo que contiene una cadena con formato incorrecto creada por el
el modo PERMISSIVE. Predeterminado: spark.sql.columnNameOfCorruptRecord.		 leer
attributePrefix 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. lectura,escritura
valueTag 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. Opción predeterminada: _VALUE lectura,escritura
encoding 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. Predeterminado: UTF-8. lectura,escritura
ignoreSurroundingSpaces Define si deben omitirse los espacios en blanco circundantes de los valores que se están leyendo. Predeterminado: true. Los datos de caracteres de solo espacio en blanco se omiten. leer
rowValidationXSDPath 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 como se mencionó anteriormente. De otro modo, el archivo XSD no afecta al esquema proporcionado o inferido. leer
ignoreNamespace 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 de XML no tiene en cuenta el espacio de nombres incluso si false. Predeterminado: false. leer
timestampFormat Cadena de formato de fecha y hora personalizada que sigue el formato del patrón fecha y hora. Esto se aplica al tipo timestamp. Predeterminado: yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]. lectura,escritura
timestampNTZFormat Cadena de formato personalizada para la marca de tiempo sin zona horaria que sigue el formato del patrón fecha y hora. Esto se aplica al tipo TimestampNTZType. Valor predeterminado:
yyyy-MM-dd'T'HH:mm:ss[.SSS]		 lectura,escritura
dateFormat Cadena de formato de fecha personalizada que sigue el formato de patrón fecha y hora. Esto se aplica al tipo de fecha. Predeterminado: yyyy-MM-dd. lectura,escritura
locale 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. Predeterminado: en-US. leer
rootTag Etiqueta raíz de los archivos XML. Por ejemplo, en <books> <book><book>...</books>, el valor adecuado es books. Puede incluir atributos básicos especificando un valor como books foo="bar". Predeterminado: ROWS. escribir
declaration Contenido de la declaración XML que se va a escribir al principio de cada archivo XML de salida, antes de rootTag. Por ejemplo, un valor de foo hace que se escriba <?xml foo?>. Se establece una cadena vacía para suprimirla. Opción predeterminada: version="1.0"
encoding="UTF-8" standalone="yes".		 escribir
arrayElementName Nombre del elemento XML que incluye cada elemento de una columna con valores de matriz al escribir. Predeterminado: item. escribir
nullValue Establece la representación en cadena de un valor nulo. Predeterminado: cadena null. Cuando se trata de null, el analizador no escribe atributos y elementos para los campos. lectura,escritura
compression Código de compresión a utilizar al guardar en un archivo. Puede ser uno de los nombres abreviados conocidos sin distinción de mayúsculas y minúsculas (none, bzip2, gzip,lz4, snappy y
deflate). Las funciones integradas XML omiten esta opción. Predeterminado: none.		 escribir
validateName Si es true, produce un error si la validación del nombre del elemento XML falla. Por ejemplo, los nombres de campo SQL pueden tener espacios, pero los nombres de elementos XML no. Valor predeterminado:
true.		 escribir
readerCaseSensitive Especifica el comportamiento de distinción entre mayúsculas y minúsculas cuando se habilita rescuedDataColumn. Si es verdadero, rescata las columnas de datos cuyos nombres difieren por mayúsculas y minúsculas del esquema; en caso contrario, lee los datos de forma que no distingue entre mayúsculas y minúsculas. Predeterminado: true. leer
rescuedDataColumn 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.
Predeterminado: Ninguno.		 leer
singleVariantColumn 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. Predeterminado: none. lectura,escritura

PARQUET opciones

Opción
datetimeRebaseMode
Tipo: String
Controla el cambio de base de los valores de fecha y marca de tiempo entre el calendario juliano y gregoriano proléptico. Valores permitidos: EXCEPTION, LEGACY y
CORRECTED.
Valor predeterminado: LEGACY
int96RebaseMode
Tipo: String
Controla el cambio de base de los valores de marca de tiempo INT96 entre el calendario juliano y el gregoriano proléptico. Valores permitidos: EXCEPTION, LEGACY y
CORRECTED.
Valor predeterminado: LEGACY
mergeSchema
Tipo: Boolean
Si se debe inferir el esquema en varios archivos y combinar el esquema de cada archivo.
Valor predeterminado: false
readerCaseSensitive
Tipo: Boolean
Especifica el comportamiento de distinción entre mayúsculas y minúsculas cuando rescuedDataColumn está habilitado. Si es verdadero, rescata las columnas de datos cuyos nombres difieren por mayúsculas y minúsculas del esquema; en caso contrario, lee los datos de forma que no distingue entre mayúsculas y minúsculas.
Valor predeterminado: true
rescuedDataColumn
Tipo: String
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.
Valor predeterminado: ninguno

AVRO opciones

Opción
avroSchema
Tipo: String
Esquema opcional proporcionado por un usuario en formato Avro. Al leer Avro, esta opción se puede establecer en un esquema evolucionado, que es compatible con el esquema de Avro real pero distinto de este. El esquema de deserialización será 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 contendrá también la nueva columna.
Valor predeterminado: ninguno
datetimeRebaseMode
Tipo: String
Controla el cambio de base de los valores de fecha y marca de tiempo entre el calendario juliano y gregoriano proléptico. Valores permitidos: EXCEPTION, LEGACY y
CORRECTED.
Valor predeterminado: LEGACY
mergeSchema
Tipo: Boolean
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.
Valor predeterminado: false
readerCaseSensitive
Tipo: Boolean
Especifica el comportamiento de distinción entre mayúsculas y minúsculas cuando rescuedDataColumn está habilitado. Si es verdadero, rescata las columnas de datos cuyos nombres difieren por mayúsculas y minúsculas del esquema; en caso contrario, lee los datos de forma que no distingue entre mayúsculas y minúsculas.
Valor predeterminado: true
rescuedDataColumn
Tipo: String
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?.
Valor predeterminado: ninguno

BINARYFILE opciones

Los archivos binarios no tienen ninguna opción de configuración adicional.

TEXT opciones

Opción
encoding
Tipo: String
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.
Valor predeterminado: UTF-8
lineSep
Tipo: String
Una cadena entre dos registros TEXT consecutivos.
Valor predeterminado: None, que abarca \r, \r\n y \n
wholeText
Tipo: Boolean
Si se debe leer un archivo como único registro.
Valor predeterminado: false

ORC opciones

Opción
mergeSchema
Tipo: Boolean
Si se debe inferir el esquema en varios archivos y combinar el esquema de cada archivo.
Valor predeterminado: false

Opciones de streaming

Estas opciones se aplican al usar read_files dentro de una tabla de streaming o una consulta de streaming.

Opción
allowOverwrites
Tipo: Boolean
Si se deben volver a procesar los archivos que se han modificado después de la detección. La última versión disponible del archivo se procesará durante una actualización si se ha modificado desde la última consulta de actualización realizada correctamente.
Valor predeterminado: false
includeExistingFiles
Tipo: Boolean
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.
Valor predeterminado: true
maxBytesPerTrigger
Tipo: Byte String
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 máximo blando. Si tiene archivos de 3 GB cada uno, Azure Databricks procesa 12 GB en un microlote. Cuando se usa junto con maxFilesPerTrigger, Azure Databricks consume hasta el límite inferior de maxFilesPerTrigger o maxBytesPerTrigger, lo que se alcance primero.
Nota: En el caso de las tablas de streaming creadas en almacenes de SQL sin servidor, esta opción y maxFilesPerTrigger no debe establecerse para aprovechar el control de admisión dinámico, que se escala según el tamaño de la carga de trabajo y los recursos de proceso sin servidor para proporcionarle la mejor latencia y rendimiento.
Valor predeterminado: ninguno
maxFilesPerTrigger
Tipo: Integer
Número máximo de archivos nuevos que se procesarán en cada desencadenador. Cuando se usa junto con maxBytesPerTrigger, Azure Databricks consume hasta el límite inferior de maxFilesPerTrigger o maxBytesPerTrigger, lo que se alcance primero.
Nota: En el caso de las tablas de streaming creadas en almacenes de SQL sin servidor, esta opción y maxBytesPerTrigger no debe establecerse para aprovechar el control de admisión dinámico, que se escala según el tamaño de la carga de trabajo y los recursos de proceso sin servidor para proporcionarle la mejor latencia y rendimiento.
Valor predeterminado: 1000
schemaEvolutionMode
Tipo: String
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. Esta opción no se aplica a los archivos text y binaryFile.
Valor predeterminado: "addNewColumns" cuando no se proporciona un esquema.
De lo contrario, "none".
schemaLocation
Tipo: String
Ubicación en la que se almacenará el esquema deducido y los cambios posteriores. Consulte Inferencia de esquemas para obtener más detalles. La ubicación del esquema no es necesaria cuando se usa en una consulta de tabla de streaming.
Valor predeterminado: ninguno

Ejemplos

-- Reads the files available in the given path. Auto-detects the format and schema of the data.
> SELECT * FROM read_files('abfss://container@storageAccount.dfs.core.windows.net/base/path');

-- Reads the headerless CSV files in the given path with the provided schema.
> SELECT * FROM read_files(
    's3://bucket/path',
    format => 'csv',
    schema => 'id int, ts timestamp, event string');

-- Infers the schema of CSV files with headers. Because the schema is not provided,
-- the CSV files are assumed to have headers.
> SELECT * FROM read_files(
    's3://bucket/path',
    format => 'csv')

-- Reads files that have a csv suffix.
> SELECT * FROM read_files('s3://bucket/path/*.csv')

-- Reads a single JSON file
> SELECT * FROM read_files(
    'abfss://container@storageAccount.dfs.core.windows.net/path/single.json')

-- Reads JSON files and overrides the data type of the column `id` to integer.
> SELECT * FROM read_files(
    's3://bucket/path',
    format => 'json',
    schemaHints => 'id int')

-- Reads files that have been uploaded or modified yesterday.
> SELECT * FROM read_files(
    'gs://my-bucket/avroData',
    modifiedAfter => date_sub(current_date(), 1),
    modifiedBefore => current_date())

-- Creates a Delta table and stores the source file path as part of the data
> CREATE TABLE my_avro_data
  AS SELECT *, _metadata.file_path
  FROM read_files('gs://my-bucket/avroData')

-- Creates a streaming table that processes files that appear only after the table's creation.
-- The table will most likely be empty (if there's no clock skew) after being first created,
-- and future refreshes will bring new data in.
> CREATE OR REFRESH STREAMING TABLE avro_data
  AS SELECT * FROM STREAM read_files('gs://my-bucket/avroData', includeExistingFiles => false);