URL

Introduced in: v26.8.0

The URL database engine treats table names as URLs and exposes the data at those URLs as tables. It uses the url table function, which dispatches each URL to the appropriate backend, such as file, s3, HDFS, Azure Blob Storage, or HTTP.

Creating a database

CREATE DATABASE web_data
ENGINE = URL([base_url]);

When base_url is specified, relative table names are resolved against it. Without a base URL, every table name must be a complete URL.

Usage

CREATE DATABASE web_data
ENGINE = URL('https://example.com/data/');

SELECT * FROM web_data.`daily.csv`;

The database owns no table definitions. Each table is resolved from its URL when it is used, so its schema is inferred from the current data. Table names can also use a full URL, for example web_data.s3://bucket/data/events.parquet``.

Access control

Creating this database requires READ and WRITE source grants on URL, regardless of table_engines_require_grant. Reading a table also requires a READ source grant for the resolved backend; writing requires the matching WRITE grant. For example:

GRANT READ, WRITE ON URL TO user_name;
GRANT READ, WRITE ON S3 TO user_name;

For a database with a file:// base URL, a user needs READ ON FILE. On ClickHouse server, local files are additionally restricted to user_files_path.

See the SOURCES privileges for version and compatibility details.

See also

• url table function
• Filesystem database engine
• S3 database engine

Syntax

ENGINE = URL([base_url])

Examples

Reading files of the user_files directory through a database with a file:// base URL

INSERT INTO FUNCTION file('web/daily.csv', 'CSVWithNames', 'day Date, visits UInt32') SETTINGS engine_file_truncate_on_insert = 1 VALUES ('2024-01-01', 100), ('2024-01-02', 150);
CREATE DATABASE web ENGINE = URL('file://web/');
SELECT * FROM web.`daily.csv`;
DROP DATABASE web;

┌────────day─┬─visits─┐
│ 2024-01-01 │    100 │
│ 2024-01-02 │    150 │
└────────────┴────────┘

Related

• Filesystem
• S3
• HDFS