fix: bracket access for object keys containing special characters (e.g. periods) (#309)

## Problem

`col['key.with.period']` silently returns `NULL` instead of the key's
value.

This affects any Snowflake VARIANT column whose JSON was produced by a
system that uses dotted strings as flat key names — a common pattern in
tracing and observability platforms (e.g. OpenTelemetry attributes,
Braintrust span metadata).

## Root cause: two separate bugs in `indices_to_json_extract`

### Bug 1 — dot in key name treated as JSONPath path separator

`col['a.b']` was transformed to:

```sql
col -> '$.a.b'
```

DuckDB's JSONPath engine interprets `.` as a path separator, so this
traverses *into* a nested object (`a` → `b`) rather than looking up the
literal key `"a.b"`. If no nested structure exists the result is `NULL`.

The fix exploits a DuckDB feature: [a path that does not start with `$`
is treated as a direct key
name](https://duckdb.org/docs/extensions/json#json-extraction-functions),
bypassing JSONPath interpretation entirely. Keys that aren't simple
identifiers (`[A-Za-z0-9_]+`) now omit the `$.` prefix:

```
col['simple']   → col -> '$.simple'   (unchanged)
col['a.b']      → col -> 'a.b'        (direct key lookup, no JSONPath)
```

### Bug 2 — `::string` / `::text` not recognised as string casts

In Snowflake, `::varchar`, `::string`, and `::text` are all equivalent
string casts. However sqlglot parses them to different `DataType`
values:

| Snowflake syntax | sqlglot `DataType.Type` |
|---|---|
| `::varchar` | `VARCHAR` |
| `::string` / `::text` | `TEXT` |
| `::nvarchar` | `NVARCHAR` |

The existing check was `== exp.DataType.Type.VARCHAR` only, so
`::string` fell through to `JSONExtract` (`->`) instead of
`JSONExtractScalar` (`->>`). This returned the JSON-encoded value (e.g.
`'"sess1"'` with surrounding quotes) rather than the plain string
(`'sess1'`).

The fix introduces `_STRING_CAST_TYPES = {VARCHAR, TEXT, NVARCHAR}` and
checks `in _STRING_CAST_TYPES`.

**Note:** these two bugs interact. In the common real-world pattern
`metadata['request_context.channel_session_id']::string`, both bugs fire
simultaneously — the key returns `NULL` (bug 1), and even if it didn't,
the string value would still be returned JSON-quoted (bug 2).

## Changes

**`fakesnow/transforms/transforms.py`**
- Add `import re`
- Add module-level `_SIMPLE_JSON_KEY` regex and `_STRING_CAST_TYPES` set
- `indices_to_json_extract`: expand string-type check from `== VARCHAR`
to `in _STRING_CAST_TYPES`
- `indices_to_json_extract`: for string keys that don't match
`_SIMPLE_JSON_KEY`, emit the key directly instead of prefixing with `$.`

**`tests/test_semis.py`**
- `test_object_key_with_period`: end-to-end test — inserts a row with a
period-containing key, asserts correct values for bare access
(JSON-typed result with surrounding quotes) and `::string`-cast access
(unquoted plain string), and `NULL` for a missing dotted key

**`tests/test_transforms.py`**
- `test_indices_to_object`: two new assertions — `->` output for a
period key without cast, and `->>` output for a period key with
`::varchar` cast

## Verification

```
310 passed, 1 xfailed in 26.84s
```

No regressions against the existing suite.

Co-authored-by: Andy Mackinlay <andy.mackinlay@xero.com>

Author: admackin

fakesnow/transforms/transforms.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import re
 from pathlib import Path
 from string import Template
 from typing import ClassVar, cast
@@ -583,6 +584,18 @@ def identifier(expression: exp.Expression, params: MutableParams | None) -> exp.
     return expression
 
 
+_SIMPLE_JSON_KEY = re.compile(r"^[A-Za-z0-9_]+$")
+
+# Snowflake string-like types that warrant using JSONExtractScalar (->>)
+# to return an unquoted string rather than a JSON-encoded value.
+# ::varchar -> VARCHAR, ::string / ::text -> TEXT, ::nvarchar -> NVARCHAR
+_STRING_CAST_TYPES = {
+    exp.DataType.Type.VARCHAR,
+    exp.DataType.Type.TEXT,
+    exp.DataType.Type.NVARCHAR,
+}
+
+
 def indices_to_json_extract(expression: exp.Expression) -> exp.Expression:
     """Convert indices on objects and arrays to json_extract or json_extract_string
 
@@ -603,14 +616,19 @@ def indices_to_json_extract(expression: exp.Expression) -> exp.Expression:
         and isinstance(index, exp.Literal)
         and index.this
     ):
-        if isinstance(expression.parent, exp.Cast) and expression.parent.to.this == exp.DataType.Type.VARCHAR:
-            # If the parent is a cast to varchar, we need to use JSONExtractScalar
-            # to get the unquoted string value.
+        if isinstance(expression.parent, exp.Cast) and expression.parent.to.this in _STRING_CAST_TYPES:
+            # If the parent is a cast to a string type (::varchar, ::string, ::text, ::nvarchar),
+            # use JSONExtractScalar to return an unquoted string value.
             klass = exp.JSONExtractScalar
         else:
             klass = exp.JSONExtract
         if index.is_string:
-            return klass(this=expression.this, expression=exp.Literal(this=f"$.{index.this}", is_string=True))
+            key = index.this
+            # Simple identifiers use standard JSONPath dot notation ($.key).
+            # Keys with special characters (e.g. periods) are passed without the $. prefix so
+            # DuckDB treats the value as a direct key lookup, bypassing JSONPath path separation.
+            path = f"$.{key}" if _SIMPLE_JSON_KEY.match(key) else key
+            return klass(this=expression.this, expression=exp.Literal(this=path, is_string=True))
         else:
             return klass(this=expression.this, expression=exp.Literal(this=f"$[{index.this}]", is_string=True))
 

tests/test_semis.py

@@ -162,6 +162,23 @@ def test_semi_structured_types(cur: snowflake.connector.cursor.SnowflakeCursor):
     ]
 
 
+def test_object_key_with_period(cur: snowflake.connector.cursor.SnowflakeCursor):
+    # Keys that contain periods must be treated as literal key names, not JSONPath expressions.
+    # e.g. obj['a.b'] is a single key containing a period, not a nested path a -> b.
+    cur.execute("""create or replace table dotkeys (obj variant)""")
+    cur.execute("""insert into dotkeys select parse_json('{"a.b": "val1"}')""")
+
+    cur.execute("select obj['a.b'] from dotkeys")
+    assert cur.fetchall() == [('"val1"',)]
+
+    cur.execute("select obj['a.b']::string from dotkeys")
+    assert cur.fetchall() == [("val1",)]
+
+    # A missing key should return NULL, not raise an error
+    cur.execute("select obj['x.y']::string from dotkeys")
+    assert cur.fetchall() == [(None,)]
+
+
 def test_try_parse_json(dcur: snowflake.connector.cursor.DictCursor):
     dcur.execute("""SELECT TRY_PARSE_JSON('{"first":"foo", "last":"bar"}') AS j""")
     assert dindent(dcur.fetchall()) == [{"J": '{\n  "first": "foo",\n  "last": "bar"\n}'}]

tests/test_transforms.py

@@ -463,6 +463,22 @@ def test_indices_to_object() -> None:
         == "SELECT name -> '$.k' FROM semi"
     )
 
+    # Keys with special characters (e.g. periods) must use direct key lookup instead of
+    # JSONPath dot notation, otherwise DuckDB interprets dots as path separators.
+    assert (
+        sqlglot.parse_one("SELECT meta['key.with.period'] FROM semi")
+        .transform(indices_to_json_extract)
+        .sql(dialect="duckdb")
+        == "SELECT meta -> 'key.with.period' FROM semi"
+    )
+
+    assert (
+        sqlglot.parse_one("SELECT meta['key.with.period']::varchar FROM semi", read="snowflake")
+        .transform(indices_to_json_extract)
+        .sql(dialect="duckdb")
+        == "SELECT CAST(meta ->> 'key.with.period' AS TEXT) FROM semi"
+    )
+
 
 def test_integer_precision() -> None:
     assert (