# Lakehouse Object Naming Rules

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

1. **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.
2. **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.
3. **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.
4. **Language restriction**: Chinese characters are not supported.
5. **Length limit**: 1–256 characters; WORKSPACE NAME is limited to 3–28 characters.

Examples of valid identifiers:

```SQL
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:

```sql
CREATE TABLE my_table(
    `my-col`  INT,
    `my col`  STRING,
    `chinese_col`   DATE,
    `123col`  BIGINT
)
```

**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:

```sql
-- 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

```sql
-- 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 |
|         | Chinese characters | Supported (requires backticks, e.g., `` `chinese_col` ``) |
|         | Reserved words | Reserved words exist |
|         | Duplicates | Not allowed within the current table |
| 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 |

## VOLUME

|         | 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 exist |
|         | Duplicates | Not allowed within the current workspace; cannot duplicate a schema 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); spaces allowed |
|         | Chinese characters | Supported |
|         | Case sensitivity | Case-sensitive |

## FUNCTION

|         | Constraint | Condition |
| ------- | -------- | ------------------------------------------ |
| Name rules | Naming rule | Starts with a letter (A-Z, a-z) or underscore (`_`). Uppercase letters are converted to lowercase; avoid duplicating built-in function names. |
|         | 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 exist |
|         | Duplicates | Duplicates allowed; distinguished by input parameters |
| 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 |

## ROLE

|             | 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 roles exist |
|             | Duplicates | Not allowed within the current instance |
| 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 |
| ROLE_ALIAS | 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-insensitive |

## USER

|         | 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 exist (e.g., `USER`) |
|         | Duplicates | Not allowed within the current Account |
| 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 |

## INDEX

|         | 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 exist |
|         | Duplicates | Not allowed within the current schema; an index must be in the same schema as its table |
| 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 |
