Add REST catalog support in docs (#1)

[somratdutta]

Summary

This PR adds comprehensive documentation for ClickHouse's REST Catalog integration.

Checklist

• Delete items not relevant to your PR
• URL changes should add a redirect to the old URL via https://github.com/ClickHouse/clickhouse-docs/blob/main/docusaurus.config.js
• If adding a new integration page, also add an entry to the integrations list here: https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/integrations/index.mdx

[vercel]

@somratdutta is attempting to deploy a commit to the ClickHouse Team on Vercel.

A member of the Team first needs to authorize it.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
clickhouse-docs	✅ Ready (Inspect)	Visit Preview	Jul 9, 2025 8:43am

[Blargian]

@somratdutta would you mind to merge main into your branch? The error the vercel deployment is failing on is unrelated to your changes and was fixed yesterday.

[somratdutta]

Sure @Blargian.
I would do it, thanks for reviewing my PR.

[Blargian]

@somratdutta firstly, thank you so much for this contribution, I am really excited to see it! I've left a few comments. I was unable to get this working following these steps. Let's put together an example which can be easily reproduced.

[Blargian]

Suggested change

	`SET allow_experimental_database_rest_catalog = 1;`
	`SET allow_experimental_database_iceberg = 1;`

[Blargian]

Suggested change

	clickhouse:
	image: clickhouse/clickhouse-server:main
	container_name: clickhouse
	user: '0:0' # Ensures root permissions
	networks:
	iceberg_net:
	ports:
	- "8123:8123"
	- "9002:9000"
	volumes:
	- ./clickhouse:/var/lib/clickhouse
	- ./clickhouse/data_import:/var/lib/clickhouse/data_import # Mount dataset folder
	networks:
	- iceberg_net
	environment:
	- CLICKHOUSE_DB=default
	- CLICKHOUSE_USER=default
	- CLICKHOUSE_DO_NOT_CHOWN=1
	- CLICKHOUSE_PASSWORD=
	clickhouse:
	image: clickhouse/clickhouse-server:25.5.6
	container_name: clickhouse
	user: '0:0' # Ensures root permissions
	networks:
	iceberg_net:
	ports:
	- "8123:8123"
	- "9002:9000"
	volumes:
	- ./clickhouse:/var/lib/clickhouse
	- ./clickhouse/data_import:/var/lib/clickhouse/data_import # Mount dataset folder
	networks:
	- iceberg_net
	environment:
	- CLICKHOUSE_DB=default
	- CLICKHOUSE_USER=default
	- CLICKHOUSE_DO_NOT_CHOWN=1
	- CLICKHOUSE_PASSWORD=

[Blargian]

Suggested change

	CREATE DATABASE demo
	ENGINE = DataLakeCatalog('http://rest:8181/v1', 'admin', 'password')
	SETTINGS
	catalog_type = 'rest',
	storage_endpoint = 'http://minio:9000/lakehouse',
	warehouse = 'demo'
	SET allow_experimental_database_iceberg = 1;
	CREATE DATABASE demo
	ENGINE = DataLakeCatalog('http://rest:8181/v1', 'admin', 'password')
	SETTINGS
	catalog_type = 'rest',
	storage_endpoint = 'http://minio:9000/lakehouse',
	warehouse = 'demo'

[Blargian]

I unfortunately don't get this when I try to run the steps. I'm getting back:

SHOW TABLES IN demo

Query id: 4411372a-a71c-44e9-b27b-146af2048670

Ok.

0 rows in set. Elapsed: 0.047 sec.

demo is however created:

SHOW DATABASES

Query id: 70f26176-08cd-4e5e-b788-44ce1adf10eb

   ┌─name───────────────┐
1. │ INFORMATION_SCHEMA │
2. │ default            │
3. │ demo               │
4. │ information_schema │
5. │ system             │
   └────────────────────┘

Can you confirm you were able to get this working locally?

[Blargian]

Let's write here some short set up steps, something like:

Create a new folder in which to run the example, then create a file docker-compose.yml with the configuration from Databricks docker-spark-iceberg.

Next, create a file docker-compose.override.yml and place the following ClickHouse container configuration into it

(After the code block we can say to run docker compose up)

[Blargian]

Suggested change

	networks:
	iceberg_net:

With this line I get an error. Works without it.

[Blargian]

Let's update this description, no S3 buckets involved in this guide.