SNOW-1875145: change json_element to _is_qualified_name (#2946)

<!---
Please answer these questions before creating your pull request. Thanks!
--->

1. Which Jira issue is this PR addressing? Make sure that there is an
accompanying issue to your PR.

   <!---
   In this section, please add a Snowflake Jira issue number.

Note that if a corresponding GitHub issue exists, you should still
include
   the Snowflake Jira issue number. For example, for GitHub issue
#1400, you should
   add "SNOW-1335071" here.
    --->

   Fixes SNOW-1875145

2. Fill out the following pre-review checklist:

- [x] I am adding a new automated test(s) to verify correctness of my
new code
- [ ] If this test skips Local Testing mode, I'm requesting review from
@snowflakedb/local-testing
   - [ ] I am adding new logging messages
   - [ ] I am adding a new telemetry message
   - [ ] I am adding new credentials
   - [ ] I am adding a new dependency
- [ ] If this is a new feature/behavior, I'm adding the Local Testing
parity changes.
- [x] I acknowledge that I have ensured my changes to be thread-safe.
Follow the link for more information: [Thread-safe Developer
Guidelines](https://github.com/snowflakedb/snowpark-python/blob/main/CONTRIBUTING.md#thread-safe-development)

3. Please describe how your code solves the related issue.

Please write a short description of how your code change solves the
related issue.

Author: sfc-gh-jdu

CHANGELOG.md

@@ -60,7 +60,6 @@
 #### Experimental Features
 
 - Added `Catalog` class to manage snowflake objects. It can be accessed via `Session.catalog`.
-- Added support for querying json element of a VARIANT column in `functions.col` and `functions.column` with an optional keyword argument `json_element`.
 - Allow user input schema when reading JSON file on stage.
 - Added support for specifying a schema string (including implicit struct syntax) when calling `DataFrame.create_dataframe`.
   - `snowflake.core` is a dependency required for this feature.

src/snowflake/snowpark/column.py

@@ -252,13 +252,14 @@ def __init__(
         self,
         expr1: Union[str, Expression],
         expr2: Optional[str] = None,
-        json_element: bool = False,
         _ast: Optional[proto.Expr] = None,
         _emit_ast: bool = True,
+        *,
+        _is_qualified_name: bool = False,
     ) -> None:
         self._ast = _ast
 
-        def derive_json_element_expr(
+        def derive_qualified_name_expr(
             expr: str, df_alias: Optional[str] = None
         ) -> UnresolvedAttribute:
             parts = expr.split(".")
@@ -281,8 +282,8 @@ def derive_json_element_expr(
 
             if expr2 == "*":
                 self._expression = Star([], df_alias=expr1)
-            elif json_element:
-                self._expression = derive_json_element_expr(expr2, expr1)
+            elif _is_qualified_name:
+                self._expression = derive_qualified_name_expr(expr2, expr1)
             else:
                 self._expression = UnresolvedAttribute(
                     quote_name(expr2), df_alias=expr1
@@ -297,8 +298,8 @@ def derive_json_element_expr(
         elif isinstance(expr1, str):
             if expr1 == "*":
                 self._expression = Star([])
-            elif json_element:
-                self._expression = derive_json_element_expr(expr1)
+            elif _is_qualified_name:
+                self._expression = derive_qualified_name_expr(expr1)
             else:
                 self._expression = UnresolvedAttribute(quote_name(expr1))
 
@@ -1505,12 +1506,13 @@ class CaseExpr(Column):
     def __init__(
         self,
         expr: CaseWhen,
-        json_element: bool = False,
         _ast: Optional[proto.Expr] = None,
         _emit_ast: bool = True,
+        *,
+        _is_qualified_name: bool = False,
     ) -> None:
         super().__init__(
-            expr, json_element=json_element, _ast=_ast, _emit_ast=_emit_ast
+            expr, _is_qualified_name=_is_qualified_name, _ast=_ast, _emit_ast=_emit_ast
         )
         self._branches = expr.branches
 

src/snowflake/snowpark/functions.py

@@ -263,30 +263,30 @@ def _check_column_parameters(name1: str, name2: Optional[str]) -> None:
 
 @overload
 @publicapi
-def col(col_name: str, json_element: bool = False, _emit_ast: bool = True) -> Column:
+def col(
+    col_name: str, _emit_ast: bool = True, *, _is_qualified_name: bool = False
+) -> Column:
     """Returns the :class:`~snowflake.snowpark.Column` with the specified name.
 
     Args:
         col_name: The name of the column.
-        json_element: Whether the column is a JSON element. If a column is a VARIANT column in Snowflake,
-            you can dot notation `.` to query the nested json element, e.g., "name.firstname" and "name.lastname".
 
     Example::
         >>> df = session.sql("select 1 as a")
         >>> df.select(col("a")).collect()
         [Row(A=1)]
-
-        >>> df = session.sql("select parse_json('{\"firstname\": \"John\", \"lastname\": \"Doe\"}') as name")
-        >>> df.select(col("name.firstname", json_element=True)).collect()
-        [Row(FIRSTNAME='John')]
     """
     ...  # pragma: no cover
 
 
 @overload
 @publicapi
 def col(
-    df_alias: str, col_name: str, json_element: bool = False, _emit_ast: bool = True
+    df_alias: str,
+    col_name: str,
+    _emit_ast: bool = True,
+    *,
+    _is_qualified_name: bool = False,
 ) -> Column:
     """Returns the :class:`~snowflake.snowpark.Column` with the specified dataframe alias and column name.
 
@@ -302,8 +302,9 @@ def col(
 def col(
     name1: str,
     name2: Optional[str] = None,
-    json_element: bool = False,
     _emit_ast: bool = True,
+    *,
+    _is_qualified_name: bool = False,
 ) -> Column:
 
     _check_column_parameters(name1, name2)
@@ -313,37 +314,37 @@ def col(
         ast = create_ast_for_column(name1, name2, "col")
 
     if name2 is None:
-        return Column(name1, json_element=json_element, _ast=ast)
+        return Column(name1, _is_qualified_name=_is_qualified_name, _ast=ast)
     else:
-        return Column(name1, name2, json_element=json_element, _ast=ast)
+        return Column(name1, name2, _is_qualified_name=_is_qualified_name, _ast=ast)
 
 
 @overload
 @publicapi
-def column(col_name: str, json_element: bool = False, _emit_ast: bool = True) -> Column:
+def column(
+    col_name: str, _emit_ast: bool = True, *, _is_qualified_name: bool = False
+) -> Column:
     """Returns a :class:`~snowflake.snowpark.Column` with the specified name. Alias for col.
 
     Args:
          col_name: The name of the column.
-         json_element: Whether the column is a JSON element. If a column is a VARIANT column in Snowflake,
-             you can dot notation `.` to query the nested json element, e.g., "name.firstname" and "name.lastname".
 
     Example::
          >>> df = session.sql("select 1 as a")
          >>> df.select(column("a")).collect()
          [Row(A=1)]
-
-         >>> df = session.sql("select parse_json('{\"firstname\": \"John\", \"lastname\": \"Doe\"}') as name")
-         >>> df.select(column("name.firstname", json_element=True)).collect()
-         [Row(FIRSTNAME='John')]
     """
     ...  # pragma: no cover
 
 
 @overload
 @publicapi
 def column(
-    df_alias: str, col_name: str, json_element: bool = False, _emit_ast: bool = True
+    df_alias: str,
+    col_name: str,
+    _emit_ast: bool = True,
+    *,
+    _is_qualified_name: bool = False,
 ) -> Column:
     """Returns a :class:`~snowflake.snowpark.Column` with the specified name and dataframe alias name. Alias for col.
 
@@ -359,17 +360,18 @@ def column(
 def column(
     name1: str,
     name2: Optional[str] = None,
-    json_element: bool = False,
     _emit_ast: bool = True,
+    *,
+    _is_qualified_name: bool = False,
 ) -> Column:
     _check_column_parameters(name1, name2)
 
     ast = create_ast_for_column(name1, name2, "column") if _emit_ast else None
 
     if name2 is None:
-        return Column(name1, json_element=json_element, _ast=ast)
+        return Column(name1, _is_qualified_name=_is_qualified_name, _ast=ast)
     else:
-        return Column(name1, name2, json_element=json_element, _ast=ast)
+        return Column(name1, name2, _is_qualified_name=_is_qualified_name, _ast=ast)
 
 
 @publicapi

tests/integ/test_function.py

@@ -187,46 +187,54 @@
 
 @pytest.mark.skipif(
     "config.getoption('local_testing_mode', default=False)",
-    reason="querying json element is not supported in local testing",
+    reason="querying qualified name is not supported in local testing",
 )
-def test_col_json_element(session):
+def test_col_is_qualified_name(session):
     # 2-level deep
     df = session.sql(
         'select parse_json(\'{"firstname": "John", "lastname": "Doe"}\') as name'
     )
     Utils.check_answer(
         df.select(
-            col("name.firstname", json_element=True),
-            col("name.lastname", json_element=True),
+            col("name.firstname", _is_qualified_name=True),
+            col("name.lastname", _is_qualified_name=True),
         ),
         [Row('"John"', '"Doe"')],
     )
     Utils.check_answer(
         df.select(
-            col('name."firstname"', json_element=True),
-            col('NAME."lastname"', json_element=True),
+            col('name."firstname"', _is_qualified_name=True),
+            col('NAME."lastname"', _is_qualified_name=True),
         ),
         [Row('"John"', '"Doe"')],
     )
-    Utils.check_answer(df.select(col("name.FIRSTNAME", json_element=True)), [Row(None)])
+    Utils.check_answer(
+        df.select(col("name.FIRSTNAME", _is_qualified_name=True)), [Row(None)]
+    )
 
     # 3-level deep
     with pytest.raises(SnowparkSQLException, match="invalid identifier"):
-        df.select(col("name:firstname", json_element=True)).collect()
+        df.select(col("name:firstname", _is_qualified_name=True)).collect()
 
     with pytest.raises(SnowparkSQLException, match="invalid identifier"):
         df.select(col("name.firstname")).collect()
 
     df = session.sql('select parse_json(\'{"l1": {"l2": "xyz"}}\') as value')
-    Utils.check_answer(df.select(col("value.l1.l2", json_element=True)), Row('"xyz"'))
     Utils.check_answer(
-        df.select(col('value."l1"."l2"', json_element=True)), Row('"xyz"')
+        df.select(col("value.l1.l2", _is_qualified_name=True)), Row('"xyz"')
+    )
+    Utils.check_answer(
+        df.select(col('value."l1"."l2"', _is_qualified_name=True)), Row('"xyz"')
+    )
+    Utils.check_answer(
+        df.select(col("value.L1.l2", _is_qualified_name=True)), Row(None)
+    )
+    Utils.check_answer(
+        df.select(col("value.l1.L2", _is_qualified_name=True)), Row(None)
     )
-    Utils.check_answer(df.select(col("value.L1.l2", json_element=True)), Row(None))
-    Utils.check_answer(df.select(col("value.l1.L2", json_element=True)), Row(None))
 
     with pytest.raises(SnowparkSQLException, match="invalid identifier"):
-        df.select(col("value:l1.l2", json_element=True)).collect()
+        df.select(col("value:l1.l2", _is_qualified_name=True)).collect()
 
     with pytest.raises(SnowparkSQLException, match="invalid identifier"):
         df.select(col("value.l1.l2")).collect()