apache / apache/iceberg

Docs: Improve catalog documentation

Open
#7,785 5 comments 10 reactions 1 assignee Claimed by @bitsondatadev View on GitHub
docs not-stale
Dominant language
Java
Stars
9.2k
Forks
3.5k
Avg merge
2d 11h
Merged PRs (30d)
132

Description

### Feature Request / Improvement

One common point of confusion that I've seen in the Trino and Iceberg communities, is the lack of a general definition of what a catalog is in the context of Iceberg. The term `catalog` is an incredibly overloaded word in the data space in general, and we need a clear section that defines and establishes what a catalog is.

The documentation on catalogs is fragmented. The [Nessie](https://iceberg.apache.org/docs/latest/nessie/) and [JDBC](https://iceberg.apache.org/docs/latest/jdbc/) catalogs are under the Integrations section. The main way you hear about catalogs is through the [Java API quickstart](https://iceberg.apache.org/docs/latest/java-api-quickstart/) and custom catalog docs under the API section. The [Spark catalog docs](https://iceberg.apache.org/spark-quickstart/#adding-a-catalog) are under the Spark page rather than the integrations page where Nessie and JDBC are located.

The REST catalog documentation is nowhere to be found.

It's a mess.

I think we should have a central location that defines and showcases the documentation for all catalogs, their settings, and other properties or setup needed. Any other locations that currently have them will reference to this central page.

### Query engine

None

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.