snowflake-connector-python 5.2.0__cp315-cp315-win_amd64.whl

snowflake/connector/cursor/_base.py

@@ -0,0 +1,1169 @@
+"""Base cursor class for database operations (PEP 249)."""
+
+from __future__ import annotations
+
+import abc
+import logging
+
+from collections.abc import Callable, Iterable, Iterator, Sequence
+from typing import TYPE_CHECKING, Any, BinaryIO, Self, cast, overload
+
+from .._common.extras import pandas, pyarrow, requires_dependency
+from .._internal.api_client.client_api import CHUNK_SIZE, core_driver
+from .._internal.arrow_context import ArrowConverterContext
+from .._internal.arrow_stream_utils import (
+    collect_arrow_table,
+    create_row_iterator,
+    create_table_iterator,
+)
+from .._internal.binding_converters import ParamStyle
+from .._internal.cursor import (
+    Args,
+    CursorBaseMixin,
+    DictRow,
+    MultiStatementQueryResultState,
+    QueryResult,
+    QueryResultWaiter,
+    ResultMetadata,
+    ResultMetadataV2,
+    Row,
+)
+from .._internal.cursor.decorators import (
+    requires_open,
+    requires_open_cursor_not_connection,
+    with_prefetch_hook,
+)
+from .._internal.decorators import (
+    api_telemetry,
+    backward_compatibility,
+    pep249,
+    snowpark_compat,
+)
+from .._internal.errorcode import ER_CURSOR_IS_CLOSED, ER_INVALID_VALUE
+from .._internal.errorhandler import simplified_error_handling
+from .._internal.logging import get_logger
+from .._internal.protobuf_gen.database_driver_v1_pb2 import (
+    ABORT_QUERY_OUTCOME_ABORTED,
+    ExecuteQueryResponse,
+    MultiStatementResult,
+    PrepareResult,
+    QueryBindings,
+    ResultSetResponse,
+    StatementHandle,
+)
+from .._internal.statement_utils import statement
+from .._internal.utils import _coerce_executemany_params, _resolve_alias
+from ..errors import InterfaceError, OperationalError, ProgrammingError
+from ..result_batch import ResultBatch
+from ._chunked_download_reader import _ChunkedDownloadReader
+from ._result_set_wrapper import _ResultSetWrapper
+
+
+if TYPE_CHECKING:
+    from pandas import DataFrame
+    from pyarrow import Table
+
+    from .._internal.arrow import ArrowRowIterator
+    from ..connection import Connection
+
+logger = get_logger(__name__)
+
+
+class SnowflakeCursorBase(CursorBaseMixin, abc.ABC):
+    """
+    Base cursor class for database operations (PEP 249).
+
+    This is the abstract base for all cursor types, equivalent to
+    ``SnowflakeCursorBase`` in the old connector. Concrete subclasses
+    must override :pyattr:`_use_dict_result` and :pymeth:`fetchone`.
+    """
+
+    _connection: Connection
+    _iterator: ArrowRowIterator | None
+
+    def __init__(self, connection: Connection) -> None:
+        """
+        Initialize a new cursor object.
+
+        Args:
+            connection: Connection object that created this cursor
+        """
+        self._connection = connection
+        super().__init__()
+        self._iterator = None
+
+        # -- ResultSet guard (set by _execute; released on reset unless reuse_results) --
+        self._result_set = _ResultSetWrapper()
+        # Deferred result loading (set by get_results_from_sfqid, invoked on first fetch)
+        self._prefetch_hook: Callable[[], None] | None = None
+
+    # ------------------------------------------------------------------
+    # PEP 249 attributes
+    # ------------------------------------------------------------------
+
+    @property
+    @pep249
+    @api_telemetry
+    def connection(self) -> Connection:
+        """The :class:`Connection` object that created this cursor."""
+        return self._connection
+
+    # ------------------------------------------------------------------
+    # Result format control
+    # ------------------------------------------------------------------
+
+    @property
+    @abc.abstractmethod
+    def _use_dict_result(self) -> bool:
+        """Whether fetch methods return dicts instead of tuples."""
+
+    # ------------------------------------------------------------------
+    # Error handling
+    # ------------------------------------------------------------------
+
+    @property
+    def _errorhandler_cursor(self) -> SnowflakeCursorBase:
+        return self
+
+    @property
+    def _errorhandler_connection(self) -> Connection:
+        return self._connection
+
+    # ------------------------------------------------------------------
+    # Execution
+    # ------------------------------------------------------------------
+
+    @overload
+    def callproc(self, procname: str) -> tuple: ...
+
+    @overload
+    def callproc(self, procname: str, args: Args) -> Args: ...
+
+    @pep249
+    @api_telemetry
+    @requires_open
+    def callproc(self, procname: str, args: Any = None) -> Any:
+        """Call a stored procedure.
+
+        Args:
+            procname: The stored procedure to be called.
+            args: Parameters to be passed into the stored procedure.
+                  ``None`` is treated as no arguments.
+
+        Returns:
+            The input parameters.
+        """
+        command, args = self._prepare_call_proc_statement(procname, args)
+        self.execute(command, args)
+        return args
+
+    @pep249
+    @api_telemetry
+    @requires_open
+    def execute(
+        self,
+        operation: str,
+        parameters: Sequence[Any] | dict[str, Any] | None = None,
+        _is_put_get: bool | None = None,
+        num_statements: int | None = None,
+        _skip_upload_on_content_match: bool = False,
+        *,
+        params: Sequence[Any] | dict[str, Any] | None = None,
+        _force_qmark_paramstyle: bool = False,
+        _statement_params: dict[str, Any] | None = None,
+        file_stream: BinaryIO | None = None,
+        **kwargs: Any,
+    ) -> Self:
+        """
+        Execute a database operation (query or command).
+        Resets the cursor state before the execution.
+
+        Args:
+            operation (str): SQL statement to execute
+            parameters (sequence or dict): Parameters for the operation.
+                For qmark/numeric paramstyle: sequence of values
+                For pyformat/format paramstyle: sequence (%s) or dict (%(name)s)
+                For format paramstyle: sequence (%s)
+            num_statements (int, optional): Number of statements in a multistatement query.
+            _skip_upload_on_content_match (bool, optional): On PUT, skip
+                re-upload when the remote stored digest metadata (S3
+                ``x-amz-meta-sfc-digest`` / Azure ``x-ms-meta-sfcdigest`` / GCS
+                ``x-goog-meta-sfc-digest``) matches the locally-computed
+                SHA-256. Opt-in optimization for racing concurrent uploaders;
+                only meaningful with ``OVERWRITE=TRUE``. Underscore-prefixed
+                for parity with the legacy Python-connector kwarg name.
+            params: Legacy alias for ``parameters`` (kwarg-only). Cannot be
+                supplied together with ``parameters``.
+            _force_qmark_paramstyle: If True, bind as qmark (``?``) even when
+                the connection's paramstyle is pyformat/format. Used by
+                callers that emit ``?`` placeholders unconditionally.
+            _statement_params: Extra per-statement parameters (e.g. ``QUERY_TAG``)
+                sent to Snowflake with this query only. Never persisted on the
+                cursor; forwarded as query-request parameters, so they tag only
+                this query without mutating session state.
+            file_stream: When set, ``operation`` must be a PUT statement with
+                a ``file://`` path (only the basename is used as the
+                destination filename). Its contents come from this stream
+                instead of disk, forwarded to the core driver in chunks so
+                the whole payload is never buffered in the wrapper. Non-PUT
+                ``operation`` raises ProgrammingError.
+        """
+        parameters = _resolve_alias(parameters, params, "parameters", "params")  # type: ignore[assignment]
+
+        # Per-call params: this execute() only, never persisted on the cursor.
+        statement_parameters = self._collect_statement_params(
+            skip_upload_on_content_match=_skip_upload_on_content_match,
+            num_statements=num_statements,
+            statement_params=_statement_params,
+        )
+
+        self.reset()
+        return self._execute(
+            operation,
+            parameters,
+            _is_put_get,
+            statement_parameters=statement_parameters,
+            _force_qmark_paramstyle=_force_qmark_paramstyle,
+            file_stream=file_stream,
+            **kwargs,
+        )
+
+    def _execute(
+        self,
+        operation: str,
+        parameters: Sequence[Any] | dict[str, Any] | None = None,
+        _is_put_get: bool | None = None,
+        *,
+        statement_parameters: dict[str, Any] | None = None,
+        _force_qmark_paramstyle: bool = False,
+        file_stream: BinaryIO | None = None,
+        **kwargs: Any,
+    ) -> Self:
+        """Execute query logic."""
+        operation = operation.strip(" \t\n\r") if operation else ""
+
+        if file_stream is not None:
+            self._execute_upload_stream(operation, file_stream)
+            self._rownumber = -1
+            return self
+
+        if not operation:
+            logger.warning("execute: no query is given to execute")
+            return self
+
+        if logger.is_enabled_for(logging.INFO) and self._connection.config.log_query_text:
+            logger.info("query: [%s]", self._format_query_for_log(operation))
+
+        query, binding_params = self._prepare_query(
+            operation, parameters, _force_qmark_paramstyle=_force_qmark_paramstyle
+        )
+
+        with statement(self.connection.conn_handle, query) as stmt_handle:  # type: ignore[arg-type]
+            self._apply_statement_parameters(stmt_handle, statement_parameters)
+
+            bindings = self._build_query_bindings(binding_params, query) if binding_params is not None else None
+            try:
+                response = self._execute_query(stmt_handle, bindings)
+            except OperationalError as exc:
+                if not self._should_retry_with_inline_json(bindings, exc):
+                    raise
+                bindings = self._build_query_bindings(cast(Sequence[Any], binding_params), query, force_json=True)
+                response = self._execute_query(stmt_handle, bindings)
+            request_id = response.request_id or None
+
+            if response.HasField("multi"):
+                self._handle_multi_statement_response(response.multi, query, request_id)
+            else:
+                self._apply_result_set(response.single, query, request_id)
+
+        self._rownumber = -1  # reset the rownumber (rownumber is not reset in reset() for backward compatibility)
+        return self
+
+    def _execute_upload_stream(self, query: str, file_stream: BinaryIO) -> None:
+        """Chunked streaming PUT: feed *file_stream* to the core driver in bounded chunks.
+
+        Bytes cross the RPC boundary via begin/chunk/finish, bounding wrapper
+        memory to one chunk. A failure after begin aborts the session
+        server-side before re-raising.
+        """
+        # Callers commonly hand over a stream whose position is not at the start.
+        file_stream.seek(0)
+        upload_handle = core_driver.upload_stream_begin(
+            conn_handle=self._connection.conn_handle,  # type: ignore[arg-type]
+            sql=query,
+        ).upload_handle
+        try:
+            while chunk := file_stream.read(CHUNK_SIZE):
+                core_driver.upload_stream_chunk(upload_handle, chunk)
+            finish_response = core_driver.upload_stream_finish(upload_handle)
+        except BaseException:
+            try:
+                core_driver.upload_stream_abort(upload_handle)
+            except Exception:
+                logger.debug("upload_stream_abort during cleanup failed; propagating original error", exc_info=True)
+            raise
+        self._apply_result_set(finish_response, query)  # type: ignore[arg-type]
+
+    @api_telemetry
+    @requires_open
+    def download_stream(self, stage_location: str, decompress: bool = False) -> BinaryIO:
+        """Return a lazily-read binary stream for a stage file (chunked, bounded memory).
+
+        Splits *stage_location* into stage name and filename on the last ``/``
+        and opens via the Begin RPC. Nothing happens until you read; each read
+        pulls one chunk. Close the stream (or use ``with``) to release the
+        download session early.
+        """
+        logger.info("download_stream: entry")
+        try:
+            stage_name, sep, source_filename = stage_location.rpartition("/")
+            if not sep:
+                # No "/": treat the whole string as the stage name, no filename.
+                stage_name, source_filename = stage_location, ""
+            begin = core_driver.download_stream_begin(
+                conn_handle=self._connection.conn_handle,  # type: ignore[arg-type]
+                stage_name=stage_name,
+                source_filename=source_filename,
+                decompress=decompress,
+            )
+            return _ChunkedDownloadReader(begin.download_handle)  # type: ignore[return-value]
+        finally:
+            logger.info("download_stream: exit")
+
+    @snowpark_compat
+    @backward_compatibility
+    @requires_open
+    def _upload(
+        self,
+        local_file_name: str,
+        stage_location: str,
+        options: dict[str, Any],
+        _do_reset: bool = True,
+    ) -> None:
+        """Synthesize and run the PUT that ``session.file.put`` would otherwise issue as SQL."""
+        from .._internal.snowpark_backcompat_helpers import file_uri, put_get_options, stage_ref
+
+        sql = f"PUT {file_uri(local_file_name)} {stage_ref(stage_location)} {put_get_options(options)}"
+        self._execute_file_transfer(sql.rstrip(), _do_reset=_do_reset)
+
+    @snowpark_compat
+    @backward_compatibility
+    @requires_open
+    def _download(
+        self,
+        stage_location: str,
+        target_directory: str,
+        options: dict[str, Any],
+        _do_reset: bool = True,
+    ) -> None:
+        """Synthesize and run the GET that ``session.file.get`` would otherwise issue as SQL."""
+        from .._internal.snowpark_backcompat_helpers import file_uri, put_get_options, stage_ref
+
+        sql = f"GET {stage_ref(stage_location)} {file_uri(target_directory)} {put_get_options(options)}"
+        self._execute_file_transfer(sql.rstrip(), _do_reset=_do_reset)
+
+    @snowpark_compat
+    @backward_compatibility
+    @requires_open
+    def _upload_stream(
+        self,
+        input_stream: BinaryIO,
+        stage_location: str,
+        options: dict[str, Any],
+        _do_reset: bool = True,
+    ) -> None:
+        """Stream-upload to the file named by *stage_location* (a file, not a directory)."""
+        from .._internal.snowpark_backcompat_helpers import put_get_options, unquoted_stage_ref
+
+        stage_dir, _, filename = unquoted_stage_ref(stage_location).rpartition("/")
+        sql = f"PUT file://{filename} {stage_dir} {put_get_options(options)}"
+        self._execute_file_transfer(sql.rstrip(), _do_reset=_do_reset, file_stream=input_stream)
+
+    @snowpark_compat
+    @backward_compatibility
+    def _download_stream(self, stage_location: str, decompress: bool = False) -> BinaryIO:
+        """Delegate to :meth:`download_stream`, adding the ``@`` prefix Snowpark omits."""
+        from .._internal.snowpark_backcompat_helpers import unquoted_stage_ref
+
+        return self.download_stream(unquoted_stage_ref(stage_location), decompress)
+
+    def _execute_file_transfer(
+        self,
+        sql: str,
+        *,
+        _do_reset: bool,
+        file_stream: BinaryIO | None = None,
+    ) -> None:
+        """Run a synthesized PUT/GET, resetting the cursor first unless told not to."""
+        if _do_reset:
+            self.execute(sql, file_stream=file_stream)
+        else:
+            self._execute(sql, file_stream=file_stream)
+
+    def _execute_query(self, stmt_handle: StatementHandle, bindings: QueryBindings | None) -> ExecuteQueryResponse:
+        """Execute query and return ExecuteQueryResponse (single or multi)."""
+        try:
+            return core_driver.statement_execute_query(stmt_handle=stmt_handle, bindings=bindings)
+        except ProgrammingError as exc:
+            self._query_result = QueryResult.from_programming_error(exc)
+            raise
+
+    def _handle_multi_statement_response(
+        self, result: MultiStatementResult, query: str | None, request_id: str | None
+    ) -> None:
+        self._multi_statement = MultiStatementQueryResultState.from_result(result, request_id)
+
+        # Edge case: empty multi-statement result
+        if self._multi_statement is None:
+            self._query_result = QueryResult(query=query, request_id=request_id)
+            return
+
+        first_qid = self._multi_statement.advance()  # always non-None: from_result() guarantees non-empty children
+        # already populate cursor with first child query results
+        rs_response = self._fetch_result_set_by_query_id(first_qid)  # type: ignore[arg-type]
+        self._apply_result_set(rs_response, query, request_id)
+
+    def _apply_result_set(
+        self, rs_response: ResultSetResponse, query: str | None, request_id: str | None = None
+    ) -> None:
+        self._result_set.replace(rs_response.result_set_handle)
+        self._query_result = QueryResult.from_result_set_response(rs_response, query, request_id)
+
+    def _fetch_result_set_by_query_id(self, query_id: str) -> ResultSetResponse:
+        """Fetch a ResultSetResponse (handle + descriptor) for a given query ID."""
+        try:
+            return core_driver.connection_get_result_set(
+                conn_handle=self._connection.conn_handle,  # type: ignore[arg-type]
+                query_id=query_id,
+            )
+        except Exception as exc:
+            if isinstance(exc, ProgrammingError):
+                raise
+            raise ProgrammingError(msg=f"Failed to fetch result set for query_id={query_id}: {exc}") from exc
+
+    def _prepare(self, stmt_handle: StatementHandle, bindings: QueryBindings | None) -> PrepareResult | None:
+        try:
+            return core_driver.statement_prepare(stmt_handle=stmt_handle, bindings=bindings).result
+        except ProgrammingError as exc:
+            self._query_result = QueryResult.from_programming_error(exc)
+            raise
+
+    def _executemany_per_row(
+        self,
+        operation: str,
+        seq_of_parameters: Sequence[Sequence[Any] | dict[str, Any]],
+        _force_qmark_paramstyle: bool = False,
+        num_statements: int | None = None,
+    ) -> None:
+        """Execute each parameter set individually and aggregate rowcount.
+
+        Used by ``executemany`` whenever array binding does not apply: client-side
+        paramstyles, dict parameters, or statements the server reports as not
+        array-bindable (e.g. UPDATE, DELETE, MERGE).
+        """
+        statement_parameters = None
+        if num_statements is not None:
+            statement_parameters = self._collect_statement_params(
+                skip_upload_on_content_match=False,
+                num_statements=num_statements,
+            )
+        self.reset()
+        total_rowcount = 0
+        unknown_rowcount = False
+        for params in seq_of_parameters:
+            self._execute(
+                operation,
+                params,
+                _force_qmark_paramstyle=_force_qmark_paramstyle,
+                statement_parameters=statement_parameters,
+            )  # no reset between calls
+            rc = self._query_result.rowcount
+            if rc is None or rc == -1:
+                unknown_rowcount = True
+            elif not unknown_rowcount:
+                total_rowcount += rc
+        # Per PEP 249, -1 indicates that the number of rows is unknown,
+        # but for backward compatibility it's set to None.
+        self._query_result.rowcount = None if unknown_rowcount else total_rowcount
+
+    @pep249
+    @api_telemetry
+    @requires_open
+    def executemany(
+        self,
+        operation: str,
+        seq_of_parameters: Iterable[Sequence[Any] | dict[str, Any]] | None = None,
+        num_statements: int | None = None,
+        *,
+        seqparams: Iterable[Sequence[Any] | dict[str, Any]] | None = None,
+        _force_qmark_paramstyle: bool = False,
+    ) -> Self:
+        """
+        Execute a database operation repeatedly for each element in seq_of_parameters.
+
+        For qmark/numeric paramstyles with sequence parameters, issues a describe
+        request first to read the server's ``arrayBindSupported`` flag (the same
+        mechanism used by the JDBC and ODBC drivers). If the server confirms array
+        binding is supported, all rows are transposed into column-major arrays and
+        sent in a single request; when the cell count meets
+        ``CLIENT_STAGE_ARRAY_BINDING_THRESHOLD`` the bindings are serialized to CSV
+        and staged. If the server reports array binding is not supported (e.g. for
+        UPDATE, DELETE, MERGE), each parameter set is executed individually with
+        scalar JSON binding.
+
+        For pyformat/format paramstyles and dict parameters, executes each row
+        individually with client-side interpolation.
+
+        Args:
+            operation (str): SQL statement (INSERT, UPDATE, DELETE, etc.)
+            seq_of_parameters: Iterable of parameter sequences or dicts. Generators
+                and other one-shot iterators are materialized so the first row can
+                be inspected and array-binding can walk the collection more than once.
+            num_statements (int, optional): Number of statements in a
+                multistatement query. Forwarded to each ``execute()`` call.
+            seqparams: Legacy alias for ``seq_of_parameters`` (kwarg-only).
+                Cannot be supplied together with ``seq_of_parameters``.
+            _force_qmark_paramstyle: If True, treat as qmark even when the
+                connection's paramstyle is pyformat/format.
+
+        Returns:
+            The cursor itself (``self``), so callers can read ``.sfqid`` after
+            execution — matching the legacy connector.
+
+        Raises:
+            InterfaceError: If parameter sequences have inconsistent lengths.
+            ProgrammingError: If both ``seq_of_parameters`` and ``seqparams`` are
+                supplied, or if ``seq_of_parameters`` is not iterable.
+        """
+        seq_of_parameters = _coerce_executemany_params(
+            _resolve_alias(seq_of_parameters, seqparams, "seq_of_parameters", "seqparams")
+        )
+
+        if not seq_of_parameters:
+            return self  # Empty sequence - no-op per PEP 249
+
+        paramstyle = ParamStyle.QMARK if _force_qmark_paramstyle else self._connection.paramstyle
+        first_params = seq_of_parameters[0]
+
+        # Execute individually for:
+        # - Client-side binding (pyformat/format)
+        # - Dict parameters (server-side doesn't support named binding)
+        if paramstyle.is_client_side() or isinstance(first_params, dict):
+            # A caller-supplied count other than 1 is a multi-statement batch.
+            # Rewriting that into one INSERT would drop the later statements.
+            if paramstyle.is_client_side() and num_statements in (None, 1):
+                # INSERT with client-side binding: rewrite into a single
+                # multi-row INSERT to avoid one HTTP request per row.
+                rewritten = self._rewrite_multirow_insert(operation, seq_of_parameters)
+                if rewritten is not None:
+                    # Values were already interpolated and escaped by
+                    # ClientSideBindingConverter.interpolate_query — no further binding needed.
+                    return self.execute(rewritten, num_statements=num_statements)
+            self._executemany_per_row(
+                operation,
+                seq_of_parameters,
+                _force_qmark_paramstyle,
+                num_statements=num_statements,
+            )
+            return self
+
+        # A caller-supplied count other than 1 is a multi-statement batch.
+        # Array binding sends one statement, so each row is executed on its own.
+        if num_statements not in (None, 1):
+            self._executemany_per_row(
+                operation,
+                seq_of_parameters,
+                _force_qmark_paramstyle,
+                num_statements=num_statements,
+            )
+            return self
+
+        # Validate row widths and pre-compute column-major layout before the server
+        # round-trip so InterfaceError from mismatched lengths surfaces early.
+        transposed = self._build_array_binding_params(operation, seq_of_parameters, first_params)
+
+        # Ask the server whether array binding is supported for this statement.
+        # This mirrors how JDBC (describeSqlIfNotTried) and the C/ODBC driver
+        # (_snowflake_execute_ex describe-only request) gate batch execution.
+        with statement(self.connection.conn_handle, operation) as stmt_handle:  # type: ignore[arg-type]
+            prepare_result = self._prepare(stmt_handle, None)
+
+        if prepare_result is None or not prepare_result.array_bind_supported:
+            # Per-row fallback: server does not support array binding for this
+            # statement type (e.g. UPDATE, DELETE, MERGE).
+            self._executemany_per_row(
+                operation,
+                seq_of_parameters,
+                _force_qmark_paramstyle,
+                num_statements=num_statements,
+            )
+            return self
+
+        # Server confirmed array binding: use pre-computed column-major params.
+        return self.execute(
+            operation,
+            transposed,
+            _force_qmark_paramstyle=_force_qmark_paramstyle,
+            num_statements=num_statements,
+        )
+
+    @api_telemetry
+    @requires_open
+    def describe(
+        self,
+        operation: str,
+        parameters: Sequence[Any] | dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> list[ResultMetadata] | None:
+        """Obtain the schema of the result without executing the query.
+
+        This method prepares the query on the server with describeOnly=true to obtain
+        column metadata without actually executing the query or returning data rows.
+
+        Args:
+            operation: SQL statement to describe
+            parameters: Parameters for the SQL statement (same as execute())
+            **kwargs: Additional keyword arguments (for future compatibility)
+
+        Returns:
+            List of ResultMetadata tuples describing result columns, or None if the
+            statement produces no result set (e.g., INSERT, UPDATE, DELETE, DDL).
+
+        Side effects:
+            - Updates cursor.description with the column metadata
+        """
+        self.reset()
+        query, binding_params = self._prepare_query(operation, parameters)
+
+        prepare_result: PrepareResult | None = None
+        with statement(self.connection.conn_handle, query) as stmt_handle:  # type: ignore[arg-type]
+            bindings = self._build_query_bindings(binding_params, query) if binding_params is not None else None
+            prepare_result = self._prepare(stmt_handle, bindings)
+
+        self._query_result = QueryResult.from_prepare_result(prepare_result)
+
+        if self._query_result.description:
+            self._rownumber = -1
+
+        return self._query_result.description
+
+    @snowpark_compat
+    @backward_compatibility
+    @requires_open
+    def _describe_internal(
+        self,
+        operation: str,
+        parameters: Sequence[Any] | dict[str, Any] | None = None,
+        *,
+        params: Sequence[Any] | dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> list[ResultMetadataV2] | None:
+        """Describe-only path returning new-format metadata.
+
+        Returns ``list[ResultMetadataV2]`` with ``vector_dimension`` and
+        ``fields`` populated. ``fields`` carries nested metadata for structured
+        types and is ``None`` for every other type.
+        """
+        parameters = _resolve_alias(parameters, params, "parameters", "params")  # type: ignore[assignment]
+        self.reset()
+        query, binding_params = self._prepare_query(operation, parameters)
+        prepare_result: PrepareResult | None = None
+        with statement(self.connection.conn_handle, query) as stmt_handle:  # type: ignore[arg-type]
+            bindings = self._build_query_bindings(binding_params, query) if binding_params is not None else None
+            prepare_result = self._prepare(stmt_handle, bindings)
+        self._query_result = QueryResult.from_prepare_result(prepare_result)
+        if self._query_result.description:
+            self._rownumber = -1
+        return self._query_result.description_v2
+
+    @property
+    @snowpark_compat
+    @with_prefetch_hook
+    def _query_result_format(self) -> str | None:
+        """Like the base property, but loads a deferred async result first."""
+        return super()._query_result_format
+
+    # ------------------------------------------------------------------
+    # Fetch – shared implementation
+    # Intentionally no @api_telemetry on fetch methods - they are hot paths.
+    # fetchone / fetchmany use @simplified_error_handling so the success path
+    # avoids a ContextVar round-trip per call.
+    # ------------------------------------------------------------------
+
+    def _prepare_fetch(self) -> None:
+        # Consciously skip @requires_open_cursor_not_connection and
+        # @with_prefetch_hook on fetch hot paths - both checks live here.
+        if self._closed:
+            raise InterfaceError(msg="Cursor is closed.", errno=ER_CURSOR_IS_CLOSED)
+        if self._prefetch_hook is not None:
+            self._prefetch_hook()
+
+    def _fetchone(self) -> Row | DictRow | None:
+        """Fetch the next row internally.
+
+        Return a dict if ``_use_dict_result`` is True, otherwise a tuple.
+        Concrete subclasses expose this through a type-safe ``fetchone``.
+        """
+        try:
+            self._prepare_fetch()
+            if not self._iterator:
+                self._iterator = self._create_row_iterator()
+            row: Row | DictRow = next(self._iterator)
+            self._rownumber += 1
+            return row
+        except StopIteration:
+            return None
+
+    @pep249
+    @simplified_error_handling
+    @abc.abstractmethod
+    def fetchone(self) -> Row | DictRow | None:
+        """Fetch the next row of a query result set."""
+
+    @pep249
+    @simplified_error_handling
+    def fetchmany(self, size: int | None = None) -> list[Any]:
+        """
+        Fetch the next set of rows of a query result.
+
+        Args:
+            size (int): Number of rows to fetch (defaults to arraysize)
+
+        Returns:
+            sequence: List of rows
+
+        Raises:
+            ProgrammingError: If the number of rows is not zero or positive number
+        """
+        self._prepare_fetch()
+        if size is None:
+            size = self.arraysize
+
+        if size < 0:
+            raise ProgrammingError(
+                msg=f"The number of rows is not zero or positive number: {size}", errno=ER_INVALID_VALUE
+            )
+
+        if size == 0:
+            return []
+
+        if not self._iterator:
+            self._iterator = self._create_row_iterator()
+        rows = self._iterator.fetch_many(size)
+        self._rownumber += len(rows)
+        return rows
+
+    @pep249
+    def fetchall(self) -> list[Any]:
+        """
+        Fetch all (remaining) rows of a query result.
+
+        Returns:
+            sequence: List of all remaining rows
+        """
+        self._prepare_fetch()
+        if not self._iterator:
+            self._iterator = self._create_row_iterator()
+        rows = self._iterator.fetch_all()
+        self._rownumber += len(rows)
+        return rows
+
+    # ------------------------------------------------------------------
+    # Iterator protocol
+    # ------------------------------------------------------------------
+
+    def _create_row_iterator(self) -> ArrowRowIterator:
+        stream_ptr = self._result_set.get_arrow_stream_ptr()
+        return create_row_iterator(
+            stream_ptr=stream_ptr,
+            context=ArrowConverterContext.create(self._connection),
+            use_dict_result=self._use_dict_result,
+            use_numpy=bool(self._connection.config.numpy),
+            use_core_arrow=bool(self._connection.config.use_core_arrow),
+        )
+
+    @pep249
+    def __iter__(self) -> Self:
+        """Return the cursor itself as an iterator."""
+        return self
+
+    def __next__(self) -> Row | DictRow:
+        """
+        Fetch the next row from the currently executed statement.
+
+        Returns:
+            sequence: Next row
+
+        Raises:
+            StopIteration: When no more rows are available
+        """
+        row = self.fetchone()
+        if row is None:
+            raise StopIteration
+        return row
+
+    @pep249
+    def next(self) -> Row | DictRow:
+        """Python 2 compatibility method."""
+        return self.__next__()
+
+    # ------------------------------------------------------------------
+    # PEP 249 optional / no-op methods
+    # ------------------------------------------------------------------
+
+    @pep249
+    @api_telemetry
+    @requires_open
+    @with_prefetch_hook
+    def nextset(self) -> SnowflakeCursorBase | None:
+        """
+        Skip to the next available result set, discarding remaining rows from current set.
+
+        This method is used for multi-statement queries where a single execute() produces
+        multiple result sets. Call nextset() to advance to the next query's results.
+
+        Loads a deferred async result first.
+
+        Returns:
+            SnowflakeCursorBase: Self if next set is available.
+            None: If no more result sets are available.
+
+        Raises:
+            InterfaceError: If cursor is closed.
+
+        Example:
+            cursor.set_statement_parameter("MULTI_STATEMENT_COUNT", 3)
+            cursor.execute("SELECT 1; SELECT 2; SELECT 3")
+            print(cursor.fetchone())  # (1,)
+            cursor.nextset()
+            print(cursor.fetchone())  # (2,)
+            cursor.nextset()
+            print(cursor.fetchone())  # (3,)
+            result = cursor.nextset()  # None - no more results
+        """
+        if self._multi_statement is None:
+            return None
+
+        query_id = self._multi_statement.advance()
+        if query_id is None:
+            return None
+
+        # Detach multi-statement state so reset() doesn't clear it
+        ms = self._multi_statement
+        self._multi_statement = None
+        self.reset()
+        self._multi_statement = ms
+
+        rs_response = self._fetch_result_set_by_query_id(query_id)
+        self._apply_result_set(rs_response, query=None, request_id=ms.request_id)
+        self._rownumber = -1
+
+        return self
+
+    # ------------------------------------------------------------------
+    # Context manager
+    # ------------------------------------------------------------------
+
+    def __enter__(self) -> Self:
+        """Enter the runtime context for the cursor."""
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Exit the runtime context for the cursor."""
+        self.close()
+
+    @api_telemetry
+    @requires_open_cursor_not_connection
+    def reset(self, closing: bool = False) -> None:
+        """Reset the result set.
+
+        Frees heavy result data (arrow streams, multi-statement state) while
+        for backward compatibility preserving metadata that the old driver
+        also keeps across resets: ``description``, ``rownumber``, ``sfqid``,
+        ``query``, and ``sqlstate``.
+
+        Also clears the ``messages`` list so that errors from previous
+        operations do not leak into the next one.
+
+        When the connection was created with ``reuse_results=True``, the result
+        handle is kept so a later fetch can re-read the same rows. ``close()``
+        always releases the handle.
+
+        Args:
+            closing: If True, do not reset rowcount,
+                     see: SNOW-647539: Do not erase the rowcount information when closing the cursor.
+                     If False, reset rowcount to None.
+        """
+        del self._messages[:]
+        self._query_result.reset(closing=closing)
+        if closing or self._connection._reuse_results is not True:
+            self._result_set.release()
+        self._iterator = None
+        self._binding_data = None
+        self._prefetch_hook = None
+        # Clear multistatement state
+        self._multi_statement = None
+
+    # ------------------------------------------------------------------
+    # Fetch – Arrow / Pandas
+    # ------------------------------------------------------------------
+
+    @requires_dependency(pyarrow)
+    @api_telemetry
+    @requires_open
+    @with_prefetch_hook
+    def fetch_arrow_batches(
+        self,
+        force_microsecond_precision: bool | None = None,
+    ) -> Iterator[Table]:
+        """Fetch Arrow Tables in batches.
+
+        Timestamp values stay at nanosecond precision unless
+        ``force_microsecond_precision`` is true. When the argument is omitted,
+        the connection's ``force_microsecond_precision`` is used.
+        """
+        force_microsecond_precision = self._resolve_force_microsecond_precision(force_microsecond_precision)
+        stream_ptr = self._result_set.get_arrow_stream_ptr()
+        iterator = create_table_iterator(
+            stream_ptr=stream_ptr,
+            context=ArrowConverterContext.create(self._connection),
+            number_to_decimal=self._connection.arrow_number_to_decimal,
+            force_microsecond_precision=force_microsecond_precision,
+            use_core_arrow=bool(self._connection.config.use_core_arrow),
+        )
+        for batch in iterator:
+            yield pyarrow.Table.from_batches([batch])
+
+    @requires_dependency(pyarrow)
+    @api_telemetry
+    @requires_open
+    @with_prefetch_hook
+    def fetch_arrow_all(
+        self,
+        force_return_table: bool = False,
+        force_microsecond_precision: bool | None = None,
+    ) -> Table | None:
+        """Fetch all results as a single Arrow Table.
+
+        Timestamp values stay at nanosecond precision unless
+        ``force_microsecond_precision`` is true. When the argument is omitted,
+        the connection's ``force_microsecond_precision`` is used.
+        """
+        force_microsecond_precision = self._resolve_force_microsecond_precision(force_microsecond_precision)
+        stream_ptr = self._result_set.get_arrow_stream_ptr()
+        iterator = create_table_iterator(
+            stream_ptr=stream_ptr,
+            context=ArrowConverterContext.create(self._connection),
+            number_to_decimal=self._connection.arrow_number_to_decimal,
+            force_microsecond_precision=force_microsecond_precision,
+            use_core_arrow=bool(self._connection.config.use_core_arrow),
+        )
+        return collect_arrow_table(
+            table_iterator=iterator,
+            columns_metadata=self._query_result.description,
+            force_return_table=force_return_table,
+        )
+
+    @requires_dependency(pandas)
+    @api_telemetry
+    @requires_open
+    def fetch_pandas_batches(self, **kwargs: Any) -> Iterator[DataFrame]:
+        """Fetch Pandas DataFrames in batches.
+
+        ``force_microsecond_precision`` overrides the connection setting for
+        the Arrow conversion when the caller passes it, and is taken from the
+        connection when omitted. Every other kwarg is forwarded to
+        ``pyarrow.Table.to_pandas`` (for example ``split_blocks``).
+        """
+        force_microsecond_precision = self._resolve_force_microsecond_precision(
+            kwargs.pop("force_microsecond_precision", None)
+        )
+        for table in self.fetch_arrow_batches(force_microsecond_precision=force_microsecond_precision):
+            yield table.to_pandas(**kwargs)
+
+    @requires_dependency(pandas)
+    @api_telemetry
+    @requires_open
+    def fetch_pandas_all(self, **kwargs: Any) -> DataFrame:
+        """Fetch all results as a single Pandas DataFrame.
+
+        ``force_microsecond_precision`` overrides the connection setting for
+        the Arrow conversion when the caller passes it, and is taken from the
+        connection when omitted. Every other kwarg is forwarded to
+        ``pyarrow.Table.to_pandas``.
+        """
+        force_microsecond_precision = self._resolve_force_microsecond_precision(
+            kwargs.pop("force_microsecond_precision", None)
+        )
+        table: Table = self.fetch_arrow_all(
+            force_return_table=True, force_microsecond_precision=force_microsecond_precision
+        )
+        return table.to_pandas(**kwargs)
+
+    # ------------------------------------------------------------------
+    # Distributed fetch
+    # ------------------------------------------------------------------
+
+    @api_telemetry
+    @requires_open
+    @with_prefetch_hook
+    def get_result_batches(self) -> list[ResultBatch] | None:
+        """Get the previously executed query's ResultBatches if available."""
+        result_chunks = self._result_set.get_chunks()
+        if result_chunks is None:
+            return None
+        return ResultBatch.from_chunks(
+            list(result_chunks.chunks),
+            self._query_result.description,
+            self._connection,
+            list(result_chunks.columns),
+        )
+
+    # ------------------------------------------------------------------
+    # Async query support
+    # ------------------------------------------------------------------
+
+    @api_telemetry
+    @requires_open
+    def query_result(self, qid: str) -> SnowflakeCursorBase:
+        """
+        Fetch the result of a previously executed query by its Snowflake Query ID.
+
+        Resets the cursor and populates it with the results from the specified
+        query, making them available through the standard fetch methods
+        (fetchone, fetchall, fetch_arrow_all, etc.).
+
+        Args:
+            qid: Snowflake Query ID (sfqid) of the previously executed query.
+
+        Returns:
+            This cursor instance, now populated with the query results.
+
+        Raises:
+            ProgrammingError: If the query ID is invalid, the query is still
+                running, or the results are no longer available.
+        """
+        self.reset()
+
+        response = core_driver.connection_get_query_result(
+            conn_handle=self._connection.conn_handle,  # type: ignore[arg-type]
+            query_id=qid,
+        )
+
+        if response.HasField("multi"):
+            self._handle_multi_statement_response(response.multi, query=None, request_id=None)
+        else:
+            rs_response = response.single
+            self._apply_result_set(rs_response, query=None)
+
+        self._rownumber = -1
+
+        return self
+
+    @api_telemetry
+    @requires_open
+    def get_results_from_sfqid(self, sfqid: str) -> None:
+        """Get results from a previously executed query.
+
+        Polls query status until completion, then loads results lazily
+        on first fetch call.
+
+        Before the first fetch triggers the prefetch hook, result-dependent
+        cursor attributes and methods such as ``description``, ``rowcount``,
+        and ``fetch*`` are not populated and MUST NOT be relied upon.
+
+        Args:
+            sfqid: Snowflake Query ID of the target query.
+
+        Raises:
+            ProgrammingError: If the query has already failed at call time,
+                or if it reaches a terminal error status while being polled
+                for completion.
+            DatabaseError: If the server stops returning status information
+                while polling for query completion.
+        """
+        self.reset()
+        self.connection.get_query_status_throw_if_error(sfqid)
+        self._query_result.sfqid = sfqid
+        waiter = QueryResultWaiter(self._connection, sfqid)
+
+        def prefetch_hook() -> None:
+            waiter.wait()
+            self._prefetch_hook = None
+            self.query_result(sfqid)
+
+        self._prefetch_hook = prefetch_hook
+
+    @api_telemetry
+    @requires_open
+    def execute_async(
+        self,
+        command: str,
+        params: Sequence[Any] | dict[str, Any] | None = None,
+        num_statements: int | None = None,
+        *,
+        _statement_params: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> dict[str, str | None]:
+        """Submit a query for async execution and return immediately with the query ID.
+
+        This is the first step in the async query lifecycle::
+
+            # 1. Submit the query
+            result = cursor.execute_async("SELECT ...")
+            query_id = result["queryId"]
+
+            # 2. Poll until complete
+            status = connection.get_query_status(query_id)
+
+            # 3. Retrieve results
+            cursor.get_results_from_sfqid(query_id)
+
+        Args:
+            command: SQL statement to execute.
+            params: Parameters for the operation (sequence or dict).
+            num_statements: Number of statements in a multistatement query.
+            _statement_params: Extra per-statement parameters (e.g. ``QUERY_TAG``)
+                sent to Snowflake with this query only. Never persisted on the cursor.
+
+        Returns:
+            dict with a ``queryId`` key containing the Snowflake Query ID.
+        """
+        statement_parameters = self._collect_statement_params(
+            skip_upload_on_content_match=False,
+            num_statements=num_statements,
+            statement_params=_statement_params,
+        )
+        # TODO: deprecate returning the dict, return just the sfqid itself
+        self.reset()
+        return self._execute_async(command, params, statement_parameters=statement_parameters)
+
+    def _execute_async(
+        self,
+        command: str,
+        params: Sequence[Any] | dict[str, Any] | None,
+        *,
+        statement_parameters: dict[str, Any] | None = None,
+    ) -> dict[str, str | None]:
+        query, binding_params = self._prepare_query(command, params)
+
+        with statement(self._connection.conn_handle, query) as stmt_handle:  # type: ignore[arg-type]
+            self._apply_statement_parameters(stmt_handle, statement_parameters)
+            bindings = self._build_query_bindings(binding_params, query) if binding_params is not None else None
+            response = core_driver.statement_execute_async(stmt_handle=stmt_handle, bindings=bindings)
+
+        query_id = response.query_id or None
+        request_id = response.request_id or None
+        self._query_result = QueryResult(sfqid=query_id, request_id=request_id)
+
+        return {"queryId": query_id}
+
+    @api_telemetry
+    @requires_open
+    def abort_query(self, qid: str) -> bool:
+        """Abort a running query."""
+        response = core_driver.connection_abort_query(
+            conn_handle=self._connection.conn_handle,  # type: ignore[arg-type]
+            query_id=qid,
+        )
+        return response.outcome == ABORT_QUERY_OUTCOME_ABORTED