Skip to main content
Last updated on

LIST

Applies to: check marked yes Databricks SQL check marked yes Databricks Runtime 10.4 LTS and above check marked yes Unity Catalog only

Lists the objects immediately contained at the URL.

Syntax​

LIST url [ WITH ( CREDENTIAL credential_name ) ] [ LIMIT limit ]

Parameters​

  • url

    A STRING literal with the location of the cloud storage described as an absolute URL.

  • credential_name

    An optional named credential used to access this URL. If you supply a credential it must be sufficient to access the URL. If you do not supply a credential the URL must be contained in an external location to to which you have access.

  • limit

    An optional INTEGER constant used to limit the number of objects returned.

    In Databricks Runtime 10.4 LTS the default limit is 1001 and only values between 1 and 1001 are supported.

Returns​

A result set with the following columns:

  • path STRING NOT NULL: The full URI of the storage object.
  • name STRING NOT NULL: The name of the storage object, including its extension.
  • size BIGINT NOT NULL: The size of the object in bytes. 0 for directories.
  • modification_time BIGINT NOT NULL: The Unix timestamp of the object's last modification time in milliseconds. To convert this value to a TIMESTAMP type, use CAST(modification_time / 1000 AS TIMESTAMP) or to_timestamp(modification_time / 1000).

Examples​

SQL
> LIST 's3://us-east-1-dev/some_dir' WITH (CREDENTIAL aws_some_dir) LIMIT 2
  path                               name   size modification_time
  ---------------------------------- ------ ---- -----------------
  s3://us-east-1-dev/some_dir/table1 table1 0    1706105124000
  s3://us-east-1-dev/some_dir/table2 table2 1024 1706201562000
On this page