read_files función con valores de tabla

Se aplica a: Databricks SQL 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: expresión constante en la que se va a establecer la opción. Acepta literales y funciones escalares.

Devoluciones

Tabla que contiene los datos de los archivos leídos en el especificado path. El esquema depende del formato de archivo:

• BINARYFILE: devuelve un esquema fijo:

  Columna	Tipo	Descripción
  path	STRING	Ruta de acceso completa al archivo.
  modificationTime	TIMESTAMP	Hora de última modificación del archivo.
  length	LONG	Tamaño de archivo en bytes.
  content	BINARY	Contenido binario del archivo. Use * EXCEPT (content) para excluir contenido binario al consultar metadatos de archivo.

• TEXT: devuelve un esquema fijo con una sola value columna (STRING).

• Todos los demás formatos (JSON, CSV, XML, PARQUET, AVRO, ORC): el esquema se deduce del contenido del archivo o se proporciona explícitamente mediante la schema opción .

_metadata columna

read_files expone una _metadata columna con metadatos de nivel de archivo. Esta columna no se incluye en SELECT * los resultados y debe seleccionarse explícitamente. Contiene los siguientes campos:

Para incluir _metadata en los resultados, selecciónelo explícitamente:

SELECT * EXCEPT (content), _metadata
FROM read_files('/Volumes/my_catalog/my_schema/my_volume', format => 'binaryFile');

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.

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.

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.

Autenticación para el almacenamiento en la nube

read_files lee archivos de ubicaciones externas del catálogo de Unity o volúmenes de catálogo de Unity (tanto administrados como externos). Debe tener el READ FILES privilegio en la ubicación externa o el READ VOLUME privilegio en el volumen que contiene los archivos que desea leer. Consulte Conexión al almacenamiento de objetos en la nube mediante el catálogo de Unity o ¿Qué son los volúmenes del catálogo de Unity?.

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
• Opciones específicas del formato
• Opciones de streaming

Opciones básicas

Opciones específicas del formato

Para obtener opciones específicas de cada formato de archivo (JSON, CSV, XML, Parquet, Avro, text, ORC y binary), consulte Opciones de DataFrameReader.

Opciones de streaming

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

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

Trabajar con archivos no estructurados

En los ejemplos siguientes se usa BINARYFILE el formato para leer y filtrar archivos no estructurados almacenados en volúmenes del catálogo de Unity y combinarlos read_files con funciones de IA para procesar el contenido del archivo.

Enumerar todos los archivos de un volumen: use * EXCEPT (content) para devolver metadatos de archivo sin cargar contenido binario y seleccione _metadata explícitamente para incluir campos de metadatos de nivel de archivo.

SELECT
  * EXCEPT (content),
  _metadata
FROM read_files(
  '/Volumes/<catalog>/<schema>/<volume>',
  format => 'binaryFile'
);

Enumerar archivos de imagen filtrados por tamaño: se usa fileNamePattern para dirigirse a tipos de archivo de imagen específicos y filtrar _metadata.file_size para devolver solo archivos dentro de un intervalo de tamaño determinado.

SELECT
  * EXCEPT (content),
  _metadata
FROM read_files(
  '/Volumes/my_catalog/my_schema/my_volume',
  format => 'binaryFile',
  fileNamePattern => '*.{jpg,jpeg,png,JPG,JPEG,PNG}'
)
WHERE _metadata.file_size BETWEEN 20000 AND 1000000;

Enumerar archivos PDF modificados en el último día: use fileNamePattern para dirigirse a archivos PDF y filtrar modificationTime para devolver solo los archivos modificados en el último día.

SELECT
  * EXCEPT (content),
  _metadata
FROM read_files(
  '/Volumes/my_catalog/my_schema/my_volume',
  format => 'binaryFile',
  fileNamePattern => '*.{pdf,PDF}'
)
WHERE modificationTime >= current_timestamp() - INTERVAL 1 DAY;

Ejecución de una función de IA en archivos de imagen: use ai_query para procesar archivos de imagen leídos desde una ruta de acceso de almacenamiento en la nube. Filtre los _metadata campos para dirigirse a archivos específicos.

SELECT
  path AS file_path,
  ai_query(
    'databricks-llama-4-maverick',
    'Describe this image in ten words or less: ',
    files => content
  ) AS result
FROM read_files(
  's3://my-s3-bucket/path/to/images/',
  format => 'binaryFile',
  fileNamePattern => '*.{jpg,jpeg,png,JPG,JPEG,PNG}'
)
WHERE _metadata.file_size < 1000000
  AND _metadata.file_name LIKE '%robots%';

Análisis de documentos que coinciden con un patrón de nombre de archivo: se usa ai_parse_document para extraer contenido estructurado de archivos PDF e imágenes. Filtre por _metadata.file_name para dirigir archivos específicos.

SELECT
  path AS file_path,
  ai_parse_document(
    content,
    map('version', '2.0')
  ) AS result
FROM read_files(
  '/Volumes/main/public/my_files/',
  format => 'binaryFile',
  fileNamePattern => '*.{jpg,jpeg,pdf,png}'
)
WHERE _metadata.file_name ILIKE '%receipt%';

Combinar archivos con una tabla estructurada: los flujos de trabajo no estructurados suelen requerir la combinación de datos estructurados almacenados en tablas con archivos no estructurados. En el ejemplo siguiente se unen archivos en una ruta de acceso de almacenamiento en la nube con dos tablas estructuradas, filtrando por tamaño de archivo y un atributo de usuario. La combinación con user_files se realiza mediante la extracción del identificador de archivo de la ruta de acceso del archivo mediante split y element_at.

SELECT
  users.user_id,
  user_files.file_id,
  files._metadata.file_name AS file_name,
  files.* EXCEPT (content),
  ai_parse_document(files.content, map('version', '2.0')) AS parsed_document
FROM read_files(
  's3://my-bucket-name/files/',
  format => 'binaryFile',
  fileNamePattern => '*.{pdf,doc,docx,ppt,pptx,png,jpg,jpeg}'
) AS files
JOIN user_files
  ON user_files.file_id = element_at(split(files.path, '/'), -2)
JOIN users
  ON users.user_id = user_files.user_id
WHERE users.email LIKE '%@databricks.com'
  AND files._metadata.file_size < 10000000;

Funciones relacionadas

• list_files función con valores de tabla

Artículos relacionados

• CREATE STREAMING TABLE
• read_kafka función con valores de tabla