Enhance documentation on PostgreSQL identifier handling in datasets and SELECT syntax

Author: lukekim

website/docs/reference/spicepod/datasets.md

@@ -130,6 +130,28 @@ datasets:
 
 The name of the dataset. Used to reference the dataset in the pod manifest, as well as in external data sources. The name cannot be a [reserved keyword](./keywords).
 
+Spice follows PostgreSQL SQL syntax conventions, which normalize unquoted identifiers to lowercase. A dataset named `LINEITEM` is accessible in queries as `lineitem`.
+
+To preserve uppercase or mixed-case names, wrap the name in double quotes. In YAML, this requires an extra layer of quoting:
+
+```yaml
+datasets:
+  - from: snowflake:SNOWFLAKE_SAMPLE_DATA.TPCH_SF100.LINEITEM
+    name: '"LINEITEM"'
+    params:
+      snowflake_account: JYFGIWYEFBW
+      snowflake_warehouse: snowflake_wh
+      snowflake_password: ${secrets:SNOWFLAKE_PASSWORD}
+      snowflake_username: ${secrets:SNOWFLAKE_USERNAME}
+```
+
+```sql
+-- Query using the preserved uppercase name
+SELECT * FROM "LINEITEM";
+```
+
+Without the double quotes, the same dataset would be queryable only as `lineitem`.
+
 ## `description`
 
 The description of the dataset. Used as part of the [Semantic Data Model](../../features/semantic-model).

website/docs/reference/sql/select.md

@@ -13,7 +13,19 @@ Spice is built on [Apache DataFusion](https://datafusion.apache.org/) and uses t
 ## SELECT syntax
 
 The queries in Spice scan data from tables and return 0 or more rows.
-Please be aware that column names in queries are made lower-case, but not on the inferred schema. Accordingly, if you want to query against a capitalized field, make sure to use double quotes.
+
+Spice follows PostgreSQL conventions for identifier handling: unquoted identifiers (table and column names) are normalized to lowercase. To reference a table or column with uppercase or mixed-case characters, wrap the identifier in double quotes.
+
+```sql
+-- These are equivalent (both reference the lowercase table name)
+SELECT * FROM lineitem;
+SELECT * FROM LINEITEM;
+
+-- Double quotes preserve the exact casing
+SELECT * FROM "LINEITEM";
+```
+
+See [dataset `name` configuration](../spicepod/datasets#name) for how to set a case-sensitive dataset name in the Spicepod manifest.
 
 Spice supports the following syntax for queries:
 

website/versioned_docs/version-1.11.x/reference/spicepod/datasets.md

@@ -130,6 +130,28 @@ datasets:
 
 The name of the dataset. Used to reference the dataset in the pod manifest, as well as in external data sources. The name cannot be a [reserved keyword](./keywords).
 
+Spice follows PostgreSQL SQL syntax conventions, which normalize unquoted identifiers to lowercase. A dataset named `LINEITEM` is accessible in queries as `lineitem`.
+
+To preserve uppercase or mixed-case names, wrap the name in double quotes. In YAML, this requires an extra layer of quoting:
+
+```yaml
+datasets:
+  - from: snowflake:SNOWFLAKE_SAMPLE_DATA.TPCH_SF100.LINEITEM
+    name: '"LINEITEM"'
+    params:
+      snowflake_account: JYFGIWYEFBW
+      snowflake_warehouse: snowflake_wh
+      snowflake_password: ${secrets:SNOWFLAKE_PASSWORD}
+      snowflake_username: ${secrets:SNOWFLAKE_USERNAME}
+```
+
+```sql
+-- Query using the preserved uppercase name
+SELECT * FROM "LINEITEM";
+```
+
+Without the double quotes, the same dataset would be queryable only as `lineitem`.
+
 ## `description`
 
 The description of the dataset. Used as part of the [Semantic Data Model](../../features/semantic-model).

website/versioned_docs/version-1.11.x/reference/sql/select.md

@@ -13,7 +13,19 @@ Spice is built on [Apache DataFusion](https://datafusion.apache.org/) and uses t
 ## SELECT syntax
 
 The queries in Spice scan data from tables and return 0 or more rows.
-Please be aware that column names in queries are made lower-case, but not on the inferred schema. Accordingly, if you want to query against a capitalized field, make sure to use double quotes.
+
+Spice follows PostgreSQL conventions for identifier handling: unquoted identifiers (table and column names) are normalized to lowercase. To reference a table or column with uppercase or mixed-case characters, wrap the identifier in double quotes.
+
+```sql
+-- These are equivalent (both reference the lowercase table name)
+SELECT * FROM lineitem;
+SELECT * FROM LINEITEM;
+
+-- Double quotes preserve the exact casing
+SELECT * FROM "LINEITEM";
+```
+
+See [dataset `name` configuration](../spicepod/datasets#name) for how to set a case-sensitive dataset name in the Spicepod manifest.
 
 Spice supports the following syntax for queries: