In Lakehouse, a set of naming rules has been established to ensure consistency and readability in metadata naming (such as databases, tables, views, users, etc.) and to avoid potential issues. This document describes these rules in detail to help you better understand and use Lakehouse.
Identifier Types
Lakehouse supports the following types of identifier naming:
Regular identifiers: No quotes required, but must comply with specific naming rules.
Double-quoted identifiers: Must be surrounded by double quotes ("), allowing keywords to be used as identifier names. Disabled by default; enable with SET cz.sql.double.quoted.identifiers=true (session level only). Note: Once enabled, double quotes no longer represent strings — "hello" is parsed as an identifier, not a string value.
Backtick identifiers: Must be surrounded by backticks (`). For column names, backticks allow any characters (hyphens, spaces, Chinese characters, numeric prefixes, etc.); for table names, schema names, and other object names, backticks only bypass keyword restrictions and numeric-prefix restrictions — special characters such as hyphens, spaces, and Chinese characters are still not allowed. Backticks are used by default; switch to double quotes with SET cz.sql.double.quoted.identifiers=true.
Naming Rules
Regular Identifier Naming Conventions
Starting character: Identifiers must start with a letter (uppercase A-Z or lowercase a-z) or an underscore (_). Starting with a digit or other special character is not allowed.
Character composition: Identifiers may only contain letters, underscores, and decimal digits (0-9). Other special characters and keywords such as hyphens (-), spaces, or other non-alphanumeric characters are not allowed.
Case sensitivity: Metadata undergoes case conversion during storage. Most objects (schema, table, view, column, etc.) are stored in lowercase; VCluster names are an exception and are stored in uppercase. References are case-insensitive — MyTable and mytable are treated as the same identifier. Backticks also cannot preserve case. Note: Column aliases in SELECT queries (AS MyAlias) preserve their original case and are not converted.
Language restriction: Chinese characters are not supported.
Length limit: 1–256 characters; WORKSPACE NAME is limited to 3–28 characters.
Examples of valid identifiers:
my_table
table1
table_2
Backtick Identifiers
The behavior of backticks differs by object type:
For column names: Backticks bypass all naming restrictions, allowing hyphens, spaces, Chinese characters, numeric prefixes, and any other characters:
For table names, schema names, and other object names: Backticks only bypass keyword restrictions and numeric-prefix restrictions; special characters such as hyphens, spaces, and Chinese characters are still not allowed:
-- Numeric prefix allowed
CREATE SCHEMA `123`;
-- Keyword as name allowed
CREATE SCHEMA `select`;
-- Chinese column names (column names only)
CREATE TABLE my_table(`chinese_col` STRING);
⚠️ Note: Backticks cannot preserve case. Whether for table names or column names, objects created with backticks are still stored in lowercase. For example, `MyTable` is stored as mytable.
Use backticks only when necessary.
Double-Quoted Identifiers
After enabling SET cz.sql.double.quoted.identifiers=true, double quotes act as identifier delimiters, compatible with SQL ANSI/ISO standard behavior. After enabling, note:
Double quotes no longer represent strings; "hello" is parsed as an identifier (column name/object name), not a string value
Objects created with keywords using double quotes must be referenced with double quotes
-- Enable double-quoted identifier mode
SET cz.sql.double.quoted.identifiers=true;
-- Use a keyword as a schema name
CREATE SCHEMA "select";
-- Must use double quotes when referencing
SELECT * FROM "select".my_table;
Naming Rules for Each Object Type
Instance (INSTANCE NAME)
Constraint
Condition
Name rules
Naming rule
Generated by the system; starts with a letter (A-Z, a-z) or underscore (_). Uppercase letters are converted to lowercase.
Length limit
3–28 characters
Special characters
Only letters, underscores, and decimal digits (0-9); spaces not allowed
Chinese characters
Not supported
Reserved words
None
Duplicates
Unique identifier for the user's Lakehouse
WORKSPACE
Constraint
Condition
Name rules
Naming rule
Starts with a letter (A-Z, a-z) or underscore (_). Uppercase letters are converted to lowercase.
Length limit
3–28 characters
Special characters
Only letters, underscores, and decimal digits (0-9); spaces not allowed
Chinese characters
Not supported
Reserved words
Reserved word: sys
Duplicates
Not allowed within the current instance
COMMENT
Naming rule
Starts with a letter or Chinese character
Length limit
No more than 1024 characters
Special characters
Letters, Chinese characters, underscores, decimal digits (0-9); spaces allowed in the middle
Chinese characters
Supported
Case sensitivity
Case-sensitive
SCHEMA
Constraint
Condition
Name rules
Naming rule
Starts with a letter (A-Z, a-z) or underscore (_). Uppercase letters are converted to lowercase.
Length limit
Maximum 1–256 characters
Special characters
Only letters, underscores, and decimal digits (0-9); spaces not allowed
Chinese characters
Not supported
Reserved words
Reserved words: information_schema, public
Duplicates
Not allowed within the current WORKSPACE; cannot duplicate a VOLUME name
COMMENT
Naming rule
Starts with a letter or Chinese character
Length limit
1024 characters
Special characters
Letters, Chinese characters, underscores, decimal digits (0-9)
Chinese characters
Supported
Case sensitivity
Case-sensitive
TABLE
Constraint
Condition
Name rules
Naming rule
Starts with a letter (A-Z, a-z) or underscore (_). Uppercase letters are converted to lowercase.
Length limit
Maximum 1–256 characters
Special characters
Only letters, underscores, and decimal digits (0-9); spaces not allowed
Chinese characters
Not supported
Reserved words
None
Duplicates
Not allowed within the current schema
COMMENT
Naming rule
Starts with a letter or Chinese character
Length limit
1024 characters
Special characters
Letters, Chinese characters, underscores, decimal digits (0-9); spaces allowed
Chinese characters
Supported
Case sensitivity
Case-sensitive
VIEW
Constraint
Condition
Name rules
Naming rule
Starts with a letter (A-Z, a-z) or underscore (_). Uppercase letters are converted to lowercase.
Length limit
Maximum 1–256 characters
Special characters
Only letters, underscores, and decimal digits (0-9); spaces not allowed
Chinese characters
Not supported
Reserved words
None
Duplicates
Not allowed within the current schema
COMMENT
Naming rule
Starts with a letter or Chinese character
Length limit
1024 characters
Special characters
Letters, Chinese characters, underscores, decimal digits (0-9); spaces allowed
Chinese characters
Supported
Case sensitivity
Case-sensitive
VIRTUAL CLUSTER
Constraint
Condition
Name rules
Naming rule
Starts with a letter (A-Z, a-z) or underscore (_). Lowercase letters are converted to uppercase (opposite of other objects).
Length limit
Maximum 1–256 characters
Special characters
Only letters, underscores, and decimal digits (0-9); spaces not allowed
Chinese characters
Not supported
Duplicates
Not allowed within the current workspace
COMMENT
Naming rule
Starts with a letter or Chinese character
Length limit
1024 characters
Special characters
Letters, Chinese characters, underscores, decimal digits (0-9); spaces allowed
Chinese characters
Supported
Case sensitivity
Case-sensitive
COLUMN
Constraint
Condition
Name rules
Naming rule
Starts with a letter (A-Z, a-z) or underscore (_). Uppercase letters are converted to lowercase; backticks support special characters, Chinese characters, and numeric prefixes.
Length limit
Maximum 1–256 characters
Special characters
Not supported for regular identifiers; backtick identifiers support hyphens, spaces, and other special characters
