READ_FILE

Reads a file from a stage and returns its contents as raw bytes.

READ_FILE is useful when you want to package staged assets such as documents, images, or model inputs into downstream datasets, for example when unloading training data to Lance.

Syntax

READ_FILE('@<stage>/<path-to-file>')
READ_FILE('@<stage>', '<path-to-file>')

Arguments

Return Type

BINARY

If any argument is NULL, the result is NULL.

Usage Notes

• READ_FILE reads files from a stage. It does not read local files from the TiDB Cloud Lake server.
• The target must be a file, not a directory.
• The caller must have permission to read the stage.

Examples

Read a file with the full stage path:

SELECT TO_HEX(READ_FILE('@data/csv/prefix/ab.csv'));

Result:

31

Read a file with a stage name plus a relative path:

SELECT TO_HEX(READ_FILE('@data', 'csv/prefix/ab.csv'));

Result:

31

Read multiple files by combining a constant stage with per-row relative paths:

CREATE OR REPLACE TABLE read_file_rel_paths(path STRING);

INSERT INTO read_file_rel_paths VALUES
  ('csv/prefix/ab.csv'),
  ('csv/prefix/ab/cd.csv'),
  (NULL);

SELECT path, TO_HEX(READ_FILE('@data', path))
FROM read_file_rel_paths
ORDER BY path;

Result:

+----------------------+--------------------------------+
| path                 | to_hex(read_file('@data',path)) |
+----------------------+--------------------------------+
| csv/prefix/ab.csv    | 31                             |
| csv/prefix/ab/cd.csv | 32                             |
| NULL                 | NULL                           |
+----------------------+--------------------------------+