@Rocky Hi Rocky, I have a question about using Iceberg tables in StarRocks. When querying Iceberg tables through the Iceberg catalog in StarRocks, identifiers (database names, table names, and column names) appear to be folded to lowercase, even when the underlying Iceberg table was created with mixed-case or uppercase identifiers. This causes issues when our Iceberg tables have case-sensitive names (e.g., MyTable, userID). Is there a configuration option (FE or CN config, session variable, or catalog property) in StarRocks that preserves case sensitivity for Iceberg identifiers? Specifically: 1. Is there a flag to make StarRocks treat Iceberg table/column identifiers as case-sensitive? 2. If not natively supported, is there a recommended workaround (e.g., quoting identifiers, catalog-level setting)? 3. Does this behavior differ between versions? We are currently running both 3.5.x and 4.0.4 in our environment. Any pointers to the relevant code path or documentation would be greatly appreciated.

Hi there! I'm Rocky, and I'd be happy to help you with your question about Iceberg identifier case sensitivity in StarRocks. Based on the current StarRocks documentation and system behavior for versions 3.5.x and 4.0.4, here is the breakdown of how identifiers are handled and what you can do: 1. Handling of Case Sensitivity for Identifiers In StarRocks, there is a distinction between different types of identifiers: * Catalog, Database, and Table Names: These are case-sensitive by default in StarRocks. If they appear to be folded to lowercase in your queries, it is typically because the SQL parser follows standard SQL behavior where unquoted identifiers are case-folded. * Column and Partition Names: These are not case-sensitive in StarRocks. They are always folded to lowercase internally. This is a core part of the StarRocks metadata model and applies to all table types, including Iceberg. 2. Is there a flag to preserve case? There is no specific "global preserve case" flag for Iceberg catalogs, but here is how you can manage this: * For Database and Table names: You should use double quotes to preserve the case. For example:

sql
    SELECT * FROM "MyIcebergCatalog"."MyDatabase"."MyTable";

* For Column names: Since StarRocks treats columns as case-insensitive, it will look for your columns (e.g.,

userID

) using their lowercase version (

userid

). * The Good News: The StarRocks Iceberg connector is designed to map these lowercase identifiers to the remote Iceberg schema. In most cases, if you have a column

userID

in Iceberg, querying

select userid ...

in StarRocks will correctly find and map to the remote

userID

field. * The Limitation: If your Iceberg table has two columns that differ only by case (e.g.,

userID

and

userid

), StarRocks will encounter a conflict because it treats them as the same identifier. 3. Recommended Workarounds * Quoting: Always use double quotes for Catalog, Database, and Table names if they contain mixed-case or uppercase letters. * Alias Columns: If you need the output of a query to reflect a specific case for a client application, use an alias in double quotes:

sql
    SELECT userid AS "userID" FROM "MyTable";

* Catalog Configuration: Ensure that the

iceberg.catalog.type

and other properties are correctly set. For REST catalogs, version 4.0.x introduced improvements to make property checks (like

ICEBERG_CATALOG_SECURITY

) more robust. 4. Version Differences (3.5.x vs. 4.0.4) * StarRocks 4.0: Introduced a new FE configuration called

enable_table_name_case_insensitive

(Default:

false

). * If you set this to

true

, StarRocks will treat all table/database/catalog names as case-insensitive by folding them to lowercase. * Caution: If your goal is to preserve uppercase names in a case-sensitive remote metastore, you should keep this as

false

(the default) and continue using double quotes. * StarRocks 3.5.x: This version does not have the

enable_table_name_case_insensitive

configuration. It always treats table names as case-sensitive (requiring quotes for mixed case) and columns as case-insensitive. Summary Table Identifier Type | Case-Sensitive? | How to preserve mixed-case? Catalog/DB/Table | Yes (Default) | Use double quotes (e.g.,

"MyTable"

) Column/Partition | No | Folded to lowercase; mapped by the connector If you are experiencing a specific query failure (e.g., "Table not found" or "Column not found"), double-check that you are using quotes for the table name and that there are no conflicting column names in the underlying Iceberg schema! References • data_source/External_table.md • data_source/feature-support-data-lake-analytics.md

@Rocky Does enable_table_name_case_insensitive=true apply to external Iceberg catalog identifiers (database/table names exposed through the Iceberg connector), or only to internal StarRocks tables? The official docs only explicitly exclude JDBC.

In StarRocks v4.0.x, the behavior of identifier case sensitivity has been expanded with a new configuration, but there are important distinctions between how internal tables and external catalogs (like Iceberg) are handled. To answer your specific questions: 1. Does

enable_table_name_case_insensitive=true

apply to Iceberg? Yes. In StarRocks 4.0, the FE configuration

enable_table_name_case_insensitive

applies to catalog names, database names, and table names across the system, including external Iceberg catalogs. * When

false

(Default): StarRocks is case-sensitive for these identifiers. If your Iceberg table is named

MyTable

, you must use double quotes in your SQL:

SELECT _ FROM "MyTable"

. If you query

SELECT _ FROM MyTable

, StarRocks folds the unquoted name to lowercase (

mytable

) and will fail to find the table. * When `true`: StarRocks folds all names to lowercase internally. If you query

MyTable

, it searches for

mytable

. * Caveat: This is only helpful if your underlying Iceberg metastore (e.g., Hive Metastore or Glue) is also case-insensitive (which most are). If your metastore is truly case-sensitive and contains two different tables named

MyTable

and

mytable

, enabling this flag will cause a conflict. * Restriction: This flag cannot be changed after the cluster is initialized. It must be set in the

fe.conf

before the first start. 2. Is there a flag to preserve case sensitivity for columns? No. In all versions of StarRocks (including 3.5.x and 4.0.x), column names and partition names are always case-insensitive. They are folded to lowercase internally. * How it works for Iceberg: The StarRocks Iceberg connector automatically handles the mapping. If you have a column named

userID

in Iceberg, StarRocks sees it as

userid

. When you query

SELECT userid...

, the connector maps this to the remote field

userID

. * The Conflict: If your Iceberg table has two columns that differ only by case (e.g.,

userID

and

userid

), StarRocks cannot distinguish between them and will typically return an error or only see one of them. There is currently no configuration to change this behavior for columns. 3. Recommended Workarounds If you are dealing with mixed-case table or database names: * Use Double Quotes: This is the standard SQL way to preserve case.

sql
    SELECT "userID" FROM "IcebergCatalog"."MyDatabase"."MyTable";

Note: Even if you quote

"userID"

, StarRocks still treats it as case-insensitive internally, but the quotes ensure the parser doesn't mangle the name before it reaches the connector logic. * Check the Metastore: If using a REST catalog or a custom metastore, ensure it supports case-insensitive lookups if you want to avoid quoting. Most common environments like AWS Glue or Hive Metastore (HMS) are case-insensitive for lookups by default. 4. Version Differences (3.5.x vs 4.0.4) * StarRocks 3.5.x: Does not have the

enable_table_name_case_insensitive

flag. Table and database names are strictly case-sensitive (requiring quotes for mixed case), and columns are strictly case-insensitive. * StarRocks 4.0.4: Introduced

enable_table_name_case_insensitive

. As noted in the documentation, this feature is explicitly not supported for JDBC/ODBC catalogs because those external systems often have complex case-sensitivity rules. However, it is supported for Iceberg, Hive, and other data lake catalogs. Summary Feature | StarRocks 3.5.x | StarRocks 4.0.4 Default behavior | Case-sensitive (Tables), Insensitive (Columns) | Case-sensitive (Tables), Insensitive (Columns)

enable_table_name_case_insensitive

| Not available | Available (FE config, requires cluster init) External Iceberg Support | Manual quoting required for mixed-case | Can be made insensitive for Tables/DBs JDBC/ODBC Support | Manual quoting required | Excluded from the new flag (remains case-sensitive)