apache / apache/iceberg

[REST Catalog] Case-insensitive identifier matching for Polaris and similar catalogs

Open
#14,386 1 comment 12 reactions 0 assignees View on GitHub
improvement stale
Dominant language
Java
Stars
9.2k
Forks
3.5k
Avg merge
2d 11h
Merged PRs (30d)
132

Description

### Feature Request / Improvement

### Description

When using the **Iceberg REST catalog** with services like **Polaris**, schema and table names are stored **preserving their exact case** (e.g., `CustomerDB.Orders`).

As a result, queries that use different casing (e.g., `customerdb.orders`) fail with `SCHEMA_NOT_FOUND` or `TABLE_NOT_FOUND`, even though the underlying object exists.

This behavior causes friction for users and tools that expect case-insensitive resolution (as seen in other engines like Trino, Spark, and Snowflake).

---

### Steps to Reproduce

1. Configure Spark to use a REST catalog pointing to Polaris.
2. Run:

```sql
CREATE TABLE test_catalog.CustomerDB.Orders (id INT);
SELECT * FROM test_catalog.customerdb.orders;
```
3. Query fails because identifiers are matched case-sensitively.

---

### Expected Behavior

Iceberg should optionally allow **case-insensitive identifier matching** for namespace, table, and view lookups when interacting with REST catalogs that preserve case.

---

### Proposed Solution

Introduce an optional configuration flag (disabled by default):

```
iceberg.rest-catalog.case-insensitive-name-matching=true
```

When enabled, lookups in the REST catalog (namespace, table, view) should be performed case-insensitively.

---

### Additional Context

* Polaris stores identifiers with case preserved.
* Gravitino has a similar enhancement request: [https://github.com/apache/gravitino/issues/1853](https://github.com/apache/gravitino/issues/1853)
* Trino implemented case-insensitive matching at the connector layer:

* [https://github.com/trinodb/trino/issues/23715](https://github.com/trinodb/trino/issues/23715)
* [https://github.com/trinodb/trino/pull/23867](https://github.com/trinodb/trino/pull/23867)

This issue requests adding the logic inside the **Iceberg REST catalog layer**, so clients don’t need to handle it individually.

---

### Environment

* Spark: 3.5.x
* Iceberg version: (current master / 1.x)
* Catalog: REST (Polaris)
* Behavior observed on both driver and executor when case differs.

---

### Impact

* Affects interoperability between Iceberg and Polaris.
* Users must currently match exact case to query objects.
* Impacts mixed-client ecosystems (Spark, Flink) that normalize identifiers differently.

### Query engine

Spark

### Willingness to contribute

- [x] I can contribute this improvement/feature independently
- [ ] I would be willing to contribute this improvement/feature with guidance from the Iceberg community
- [ ] I cannot contribute this improvement/feature at this time

Contributor guide

Open the contributing guide

Research direction

Start by locating the REST catalog implementation and its namespace, table, and view lookup entry points, then review how REST catalog configuration flags are handled. Trace the existing exact-case resolution behavior and identify the relevant test coverage. Done means the opt-in setting works for all three lookup types while the default behavior remains unchanged.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
api, databases
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.