SNOW-2910128: enable_decdloat in dialect

Author: sfc-gh-mraba

README.md

@@ -303,6 +303,57 @@ The following `NumPy` data types are supported:
 - numpy.float64
 - numpy.datatime64
 
+### DECFLOAT Data Type Support
+
+Snowflake SQLAlchemy supports the `DECFLOAT` data type, which provides decimal floating-point with up to 38 significant digits. For more information, see the [Snowflake DECFLOAT documentation](https://docs.snowflake.com/en/sql-reference/data-types-numeric#decfloat).
+
+```python
+from sqlalchemy import Column, Integer, MetaData, Table
+from snowflake.sqlalchemy import DECFLOAT
+
+metadata = MetaData()
+t = Table('my_table', metadata,
+    Column('id', Integer, primary_key=True),
+    Column('value', DECFLOAT()),
+)
+metadata.create_all(engine)
+```
+
+#### DECFLOAT Precision
+
+The Snowflake Python connector uses Python's `decimal` module context when converting `DECFLOAT` values to Python `Decimal` objects. Python's default decimal context precision is 28 digits, which can truncate `DECFLOAT` values that use up to 38 digits.
+
+To preserve full 38-digit precision, add `enable_decfloat=True` to the connection URL:
+
+```python
+from sqlalchemy import create_engine
+
+engine = create_engine(
+    'snowflake://testuser1:0123456@abc123/testdb/public?warehouse=testwh&enable_decfloat=True'
+)
+```
+
+Or using the `snowflake.sqlalchemy.URL` helper:
+
+```python
+from snowflake.sqlalchemy import URL
+from sqlalchemy import create_engine
+
+engine = create_engine(URL(
+    account = 'abc123',
+    user = 'testuser1',
+    password = '0123456',
+    database = 'testdb',
+    schema = 'public',
+    warehouse = 'testwh',
+    enable_decfloat = True,
+))
+```
+
+**Note**: `DECFLOAT` does not support special values (`inf`, `-inf`, `NaN`) unlike `FLOAT`.
+
+**Why is `enable_decfloat` not enabled by default?** Enabling it sets `decimal.getcontext().prec = 38`, which modifies Python's thread-local decimal context and affects all `Decimal` operations in that thread, not just database queries. To avoid unexpected side effects on application code, the dialect emits a warning when `DECFLOAT` values are retrieved without full precision enabled, guiding users to opt-in explicitly.
+
 ### Cache Column Metadata
 
 SQLAlchemy provides [the runtime inspection API](http://docs.sqlalchemy.org/en/latest/core/inspection.html) to get the runtime information about the various objects. One of the common use case is get all tables and their column metadata in a schema in order to construct a schema catalog. For example, [alembic](http://alembic.zzzcomputing.com/) on top of SQLAlchemy manages database schema migrations. A pseudo code flow is as follows:

src/snowflake/sqlalchemy/custom_types.py

@@ -1,12 +1,16 @@
 #
 # Copyright (c) 2012-2023 Snowflake Computing Inc. All rights reserved.
 #
+import decimal
+import warnings
 from typing import Optional, Tuple, Union
 
 import sqlalchemy.types as sqltypes
 import sqlalchemy.util as util
 from sqlalchemy.types import TypeEngine
 
+DECFLOAT_PRECISION = 38
+
 TEXT = sqltypes.VARCHAR
 CHARACTER = sqltypes.CHAR
 DEC = sqltypes.DECIMAL
@@ -126,9 +130,47 @@ class DECFLOAT(SnowflakeType):
     - Cannot be stored in VARIANT, OBJECT, or ARRAY
     - Not supported in Iceberg or Hybrid tables
     - Does NOT support special values (inf, -inf, NaN) unlike FLOAT
+
+    Precision: The Snowflake Python connector uses Python's decimal context
+    when converting DECFLOAT to Decimal. Default context precision is 28 digits,
+    which truncates values. For full 38-digit precision, use the dialect parameter::
+
+        engine = create_engine('snowflake://...?enable_decfloat=True')
+
+    Or set manually::
+
+        import decimal
+        decimal.getcontext().prec = 38
     """
 
     __visit_name__ = "DECFLOAT"
+    _warned_precision = False
+
+    def result_processor(self, dialect, coltype):
+        """Check decimal context precision and warn if it may truncate DECFLOAT values."""
+        # Check if dialect has enable_decfloat configured
+        decfloat_enabled = getattr(dialect, "_enable_decfloat", False)
+
+        def process(value):
+            if value is not None and not DECFLOAT._warned_precision:
+                # Skip warning if dialect has DECFLOAT support enabled
+                if decfloat_enabled:
+                    return value
+
+                current_prec = decimal.getcontext().prec
+                if current_prec < DECFLOAT_PRECISION:
+                    warnings.warn(
+                        f"Python decimal context precision ({current_prec}) is less than "
+                        f"DECFLOAT precision ({DECFLOAT_PRECISION}). Values may be truncated. "
+                        f"Set enable_decfloat=True in connection URL or "
+                        f"decimal.getcontext().prec = {DECFLOAT_PRECISION} for full precision.",
+                        UserWarning,
+                        stacklevel=2,
+                    )
+                    DECFLOAT._warned_precision = True
+            return value
+
+        return process
 
 
 class _CUSTOM_Date(SnowflakeType, sqltypes.Date):

src/snowflake/sqlalchemy/snowdialect.py

@@ -1,6 +1,7 @@
 #
 # Copyright (c) 2012-2023 Snowflake Computing Inc. All rights reserved.
 #
+import decimal
 import operator
 from collections import defaultdict
 from enum import Enum
@@ -39,6 +40,7 @@
     SnowflakeTypeCompiler,
 )
 from .custom_types import (
+    DECFLOAT_PRECISION,
     StructuredType,
     _CUSTOM_Date,
     _CUSTOM_DateTime,
@@ -163,12 +165,14 @@ def __init__(
         self,
         force_div_is_floordiv: bool = True,
         isolation_level: Optional[str] = SnowflakeIsolationLevel.READ_COMMITTED.value,
+        enable_decfloat: bool = False,
         **kwargs: Any,
     ):
         super().__init__(isolation_level=isolation_level, **kwargs)
         self.force_div_is_floordiv = force_div_is_floordiv
         self.div_is_floordiv = force_div_is_floordiv
         self.name_utils = _NameUtils(self.identifier_preparer)
+        self._enable_decfloat = enable_decfloat
 
     def initialize(self, connection):
         super().initialize(connection)
@@ -238,6 +242,11 @@ def create_connect_args(self, url: URL):
             parse_url_boolean(cache_column_metadata) if cache_column_metadata else False
         )
 
+        # Handle enable_decfloat URL parameter
+        enable_decfloat = query.pop("enable_decfloat", None)
+        if enable_decfloat is not None:
+            self._enable_decfloat = parse_url_boolean(enable_decfloat)
+
         # URL sets the query parameter values as strings, we need to cast to expected types when necessary
         for name, value in query.items():
             opts[name] = self.parse_query_param_type(name, value)
@@ -910,6 +919,10 @@ def connect(self, *cargs, **cparams):
         if _ENABLE_SQLALCHEMY_AS_APPLICATION_NAME:
             cparams = _update_connection_application_name(**cparams)
 
+        # Set decimal precision for full DECFLOAT support (38 digits)
+        if self._enable_decfloat:
+            decimal.getcontext().prec = DECFLOAT_PRECISION
+
         connection = super().connect(*cargs, **cparams)
         self._log_new_connection_event(connection)
 

tests/README.rst

@@ -49,3 +49,51 @@ Run the test:
     .. code-block:: bash
 
         py.test test
+
+
+DECFLOAT Precision
+================================================================================
+
+Snowflake's DECFLOAT type supports up to 38 significant digits. However, Python's
+default decimal context precision is 28 digits, which can truncate values when
+reading from the database.
+
+To preserve full 38-digit precision, add ``enable_decfloat=True`` to the connection URL:
+
+    .. code-block:: python
+
+        from decimal import Decimal
+        from sqlalchemy import create_engine, Column, Integer, MetaData, Table, select
+        from snowflake.sqlalchemy import DECFLOAT
+
+        # Use enable_decfloat=True in the connection URL for full precision
+        engine = create_engine(
+            'snowflake://user:password@account/database/schema?enable_decfloat=True'
+        )
+        metadata = MetaData()
+
+        prices = Table(
+            'prices', metadata,
+            Column('id', Integer, primary_key=True),
+            Column('value', DECFLOAT()),
+        )
+        metadata.create_all(engine)
+
+        with engine.connect() as conn:
+            # Insert a value with 38 significant digits
+            conn.execute(prices.insert().values(
+                id=1,
+                value=Decimal('12345678901234567890123456789.123456789')
+            ))
+            conn.commit()
+
+            # Query returns full precision with enable_decfloat=True
+            result = conn.execute(select(prices)).fetchone()
+            print(result[1])  # 12345678901234567890123456789.123456789
+
+Alternatively, you can set Python's decimal context manually:
+
+    .. code-block:: python
+
+        import decimal
+        decimal.getcontext().prec = 38