snowflake-sql-api 0.1.4__tar.gz → 0.1.5__tar.gz

{snowflake_sql_api-0.1.4 → snowflake_sql_api-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: snowflake-sql-api
-Version: 0.1.4
+Version: 0.1.5
 Summary: Lightweight, pure-Python client for Snowflake's SQL API v2
 Project-URL: Homepage, https://github.com/hampsterx/snowflake-sql-api
 Project-URL: Repository, https://github.com/hampsterx/snowflake-sql-api
@@ -95,6 +95,7 @@ stays small and cold-starts quickly. Core dependencies: `httpx`, `PyJWT`,
 - Multi-partition result handling for large result sets
 - Lazy row streams and bounded row batches, with CSV and JSONL exports
 - Query helpers, DML, batch insert, async statement submission
+- Caller-owned submission UUIDs and explicit replay across worker restarts
 - A small CLI for ad-hoc queries
 - Optional pandas (`[pandas]`) and typed-row (`[pydantic]`) helpers, kept out of
   the default install
@@ -174,6 +175,33 @@ do not resume with the same advanced iterator. The async equivalent is awaited a
 accepts the same synchronous iterable, whose production can block the event loop.
 See [batch writes](docs/batch-writes.md) for limits and recovery semantics.
 
+## Replayable submissions
+
+For a queued job, allocate a UUID and persist it with the SQL, typed inputs and
+explicit execution context **before** calling `submit()`. Pass that saved ID:
+
+```python
+handle = client.submit(job["sql"], job["params"], request_id=job["request_id"])
+# Persist handle.statement_handle when it reaches the worker.
+
+# After a restart with no saved statement handle, rebuild identical inputs:
+handle = client.resubmit(job["sql"], job["params"], request_id=job["request_id"])
+rows = handle.result()  # Only then mark the durable job complete.
+```
+
+`resubmit()` sends the same ID with `retry=true` on its first HTTP attempt.
+A saved statement handle can instead be attached with `QueryHandle(client, saved_handle)`
+and polled without another submission. Both clients expose `handle.request_id`, and
+submission errors in the `SnowflakeError` family carry the allocated ID. Async
+submission, resubmission and result methods are awaited.
+
+The application owns durable storage, identical payload reconstruction, UUID
+uniqueness and reconciliation. Retained Snowflake history governs recovery; there
+is no unlimited replay window or exactly-once processing guarantee. Live restart
+verification requires the opt-in disposable-resource probes. See
+[replayable submissions](docs/submissions.md) for the complete persistence recipe,
+limits and verification status.
+
 ## Prior art and alternatives
 
 `snowflake-sql-api` is not the first REST-based Snowflake client. If it does not

{snowflake_sql_api-0.1.4 → snowflake_sql_api-0.1.5}/README.md

@@ -31,6 +31,7 @@ stays small and cold-starts quickly. Core dependencies: `httpx`, `PyJWT`,
 - Multi-partition result handling for large result sets
 - Lazy row streams and bounded row batches, with CSV and JSONL exports
 - Query helpers, DML, batch insert, async statement submission
+- Caller-owned submission UUIDs and explicit replay across worker restarts
 - A small CLI for ad-hoc queries
 - Optional pandas (`[pandas]`) and typed-row (`[pydantic]`) helpers, kept out of
   the default install
@@ -110,6 +111,33 @@ do not resume with the same advanced iterator. The async equivalent is awaited a
 accepts the same synchronous iterable, whose production can block the event loop.
 See [batch writes](docs/batch-writes.md) for limits and recovery semantics.
 
+## Replayable submissions
+
+For a queued job, allocate a UUID and persist it with the SQL, typed inputs and
+explicit execution context **before** calling `submit()`. Pass that saved ID:
+
+```python
+handle = client.submit(job["sql"], job["params"], request_id=job["request_id"])
+# Persist handle.statement_handle when it reaches the worker.
+
+# After a restart with no saved statement handle, rebuild identical inputs:
+handle = client.resubmit(job["sql"], job["params"], request_id=job["request_id"])
+rows = handle.result()  # Only then mark the durable job complete.
+```
+
+`resubmit()` sends the same ID with `retry=true` on its first HTTP attempt.
+A saved statement handle can instead be attached with `QueryHandle(client, saved_handle)`
+and polled without another submission. Both clients expose `handle.request_id`, and
+submission errors in the `SnowflakeError` family carry the allocated ID. Async
+submission, resubmission and result methods are awaited.
+
+The application owns durable storage, identical payload reconstruction, UUID
+uniqueness and reconciliation. Retained Snowflake history governs recovery; there
+is no unlimited replay window or exactly-once processing guarantee. Live restart
+verification requires the opt-in disposable-resource probes. See
+[replayable submissions](docs/submissions.md) for the complete persistence recipe,
+limits and verification status.
+
 ## Prior art and alternatives
 
 `snowflake-sql-api` is not the first REST-based Snowflake client. If it does not

{snowflake_sql_api-0.1.4 → snowflake_sql_api-0.1.5}/snowflake_sql_api/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.1.4'
-__version_tuple__ = version_tuple = (0, 1, 4)
+__version__ = version = '0.1.5'
+__version_tuple__ = version_tuple = (0, 1, 5)
 
 __commit_id__ = commit_id = None

{snowflake_sql_api-0.1.4 → snowflake_sql_api-0.1.5}/snowflake_sql_api/aclient.py

@@ -30,11 +30,12 @@ import httpx
 from .auth import KeypairAuthenticator, account_hostname
 from .batches import BatchWriteResult, _BatchExecution, _BatchPlanner
 from .bindings import to_bindings
-from .client import DEFAULT_POLL_TIMEOUT, _columns_from, _rows_affected
+from .client import DEFAULT_POLL_TIMEOUT, _columns_from, _rows_affected, _submission_id
 from .escaping import quote_identifier, quote_name
 from .exceptions import (
     ResultNotReady,
     SnowflakeConfigError,
+    SnowflakeError,
     SnowflakeRequestError,
     SnowflakeTimeoutError,
 )
@@ -61,9 +62,16 @@ OnQuery = Callable[[str, "Params"], None]
 class AsyncQueryHandle:
     """Async handle to a submitted statement (see :class:`~snowflake_sql_api.client.QueryHandle`)."""
 
-    def __init__(self, client: AsyncSnowflakeClient, statement_handle: str) -> None:
+    def __init__(
+        self,
+        client: AsyncSnowflakeClient,
+        statement_handle: str,
+        *,
+        request_id: Optional[str] = None,
+    ) -> None:
         self._client = client
         self.statement_handle = statement_handle
+        self.request_id = request_id
 
     async def result(
         self, *, poll: bool = True, timeout: Optional[float] = None
@@ -436,13 +444,54 @@ class AsyncSnowflakeClient:
             del batch
         return planner.result()
 
-    async def submit(self, sql: str, params: Params = None) -> AsyncQueryHandle:
-        """Submit a long-running statement and return an :class:`AsyncQueryHandle`."""
-        response = await self._run(sql, params, async_exec=True)
-        handle = response.statement_handle
-        if handle is None:
-            raise SnowflakeRequestError("async submit returned no statement handle")
-        return AsyncQueryHandle(self, handle)
+    async def submit(
+        self,
+        sql: str,
+        params: Params = None,
+        *,
+        request_id: str | uuid.UUID | None = None,
+    ) -> AsyncQueryHandle:
+        """Submit once with a caller-owned UUID, or generate a fresh UUID4.
+
+        Persist the ID and identical inputs before calling for restart recovery.
+        Use :meth:`resubmit` once a previous attempt might have reached Snowflake.
+        """
+        return await self._submit_handle(
+            sql, params, request_id=request_id, retry=False
+        )
+
+    async def resubmit(
+        self, sql: str, params: Params = None, *, request_id: str | uuid.UUID
+    ) -> AsyncQueryHandle:
+        """Replay identical saved inputs with the same UUID and ``retry=true``.
+
+        The caller owns durable storage, payload consistency and reconciliation
+        when Snowflake's retained history cannot resolve an uncertain outcome.
+        """
+        return await self._submit_handle(sql, params, request_id=request_id, retry=True)
+
+    async def _submit_handle(
+        self,
+        sql: str,
+        params: Params,
+        *,
+        request_id: str | uuid.UUID | None,
+        retry: bool,
+    ) -> AsyncQueryHandle:
+        canonical_id = _submission_id(request_id, retry=retry)
+        self._notify(sql, params)
+        try:
+            payload = self._build_payload(sql, params)
+            response = await self._transport.submit(
+                payload, request_id=canonical_id, async_exec=True, retry=retry
+            )
+            handle = response.statement_handle
+            if handle is None:
+                raise SnowflakeRequestError("async submit returned no statement handle")
+            return AsyncQueryHandle(self, handle, request_id=canonical_id)
+        except SnowflakeError as exc:
+            exc.request_id = canonical_id
+            raise
 
     # -- lifecycle --------------------------------------------------------
 

{snowflake_sql_api-0.1.4 → snowflake_sql_api-0.1.5}/snowflake_sql_api/client.py

@@ -35,6 +35,7 @@ from .escaping import quote_identifier, quote_name
 from .exceptions import (
     ResultNotReady,
     SnowflakeConfigError,
+    SnowflakeError,
     SnowflakeRequestError,
     SnowflakeTimeoutError,
 )
@@ -61,6 +62,20 @@ OnQuery = Callable[[str, "Params"], None]
 DEFAULT_POLL_TIMEOUT = 600.0
 
 
+def _submission_id(request_id: str | uuid.UUID | None, *, retry: bool) -> str:
+    """Allocate or canonicalize an identity before hooks, binding or HTTP."""
+    if request_id is None and not retry:
+        return str(uuid.uuid4())
+    if isinstance(request_id, uuid.UUID):
+        return str(request_id)
+    if not isinstance(request_id, str):
+        raise SnowflakeConfigError("request_id must be a UUID string or UUID object")
+    try:
+        return str(uuid.UUID(request_id))
+    except ValueError as exc:
+        raise SnowflakeConfigError("request_id must be a valid UUID") from exc
+
+
 def _affected_count(value: Any, strict: bool) -> int:
     if strict and (isinstance(value, bool) or not isinstance(value, (int, str))):
         raise ValueError("rows-affected count must be an integer")
@@ -108,9 +123,16 @@ class QueryHandle:
     (regression bug #3).
     """
 
-    def __init__(self, client: SnowflakeClient, statement_handle: str) -> None:
+    def __init__(
+        self,
+        client: SnowflakeClient,
+        statement_handle: str,
+        *,
+        request_id: Optional[str] = None,
+    ) -> None:
         self._client = client
         self.statement_handle = statement_handle
+        self.request_id = request_id
 
     def result(
         self, *, poll: bool = True, timeout: Optional[float] = None
@@ -483,13 +505,52 @@ class SnowflakeClient:
 
     # -- async submit -----------------------------------------------------
 
-    def submit(self, sql: str, params: Params = None) -> QueryHandle:
-        """Submit a long-running statement and return a :class:`QueryHandle`."""
-        response = self._run(sql, params, async_exec=True)
-        handle = response.statement_handle
-        if handle is None:
-            raise SnowflakeRequestError("async submit returned no statement handle")
-        return QueryHandle(self, handle)
+    def submit(
+        self,
+        sql: str,
+        params: Params = None,
+        *,
+        request_id: str | uuid.UUID | None = None,
+    ) -> QueryHandle:
+        """Submit once with a caller-owned UUID, or generate a fresh UUID4.
+
+        Persist the ID and identical inputs before calling for restart recovery.
+        Use :meth:`resubmit` once a previous attempt might have reached Snowflake.
+        """
+        return self._submit_handle(sql, params, request_id=request_id, retry=False)
+
+    def resubmit(
+        self, sql: str, params: Params = None, *, request_id: str | uuid.UUID
+    ) -> QueryHandle:
+        """Replay identical saved inputs with the same UUID and ``retry=true``.
+
+        The caller owns durable storage, payload consistency and reconciliation
+        when Snowflake's retained history cannot resolve an uncertain outcome.
+        """
+        return self._submit_handle(sql, params, request_id=request_id, retry=True)
+
+    def _submit_handle(
+        self,
+        sql: str,
+        params: Params,
+        *,
+        request_id: str | uuid.UUID | None,
+        retry: bool,
+    ) -> QueryHandle:
+        canonical_id = _submission_id(request_id, retry=retry)
+        self._notify(sql, params)
+        try:
+            payload = self._build_payload(sql, params)
+            response = self._transport.submit(
+                payload, request_id=canonical_id, async_exec=True, retry=retry
+            )
+            handle = response.statement_handle
+            if handle is None:
+                raise SnowflakeRequestError("async submit returned no statement handle")
+            return QueryHandle(self, handle, request_id=canonical_id)
+        except SnowflakeError as exc:
+            exc.request_id = canonical_id
+            raise
 
     # -- lifecycle --------------------------------------------------------
 

{snowflake_sql_api-0.1.4 → snowflake_sql_api-0.1.5}/snowflake_sql_api/exceptions.py

@@ -34,6 +34,8 @@ class SnowflakeError(Exception):
     errors outside statement submission (including GET requests).
     """
 
+    request_id: Optional[str] = None
+
     def __init__(
         self, *args: object, submission_attempts: Optional[int] = None
     ) -> None:

{snowflake_sql_api-0.1.4 → snowflake_sql_api-0.1.5}/snowflake_sql_api/retry.py

@@ -2,10 +2,10 @@
 
 Defines which conditions are retryable (connect/read timeout, HTTP 429, 5xx,
 status-poll, partition fetch) and the backoff schedule. Retries reuse the
-statement ``requestId`` so a retried DML submit cannot double-apply
-(idempotency); the transport owns that wiring.
-
-Scaffold only: the retry decision and backoff loop land in Phase 2.
+statement ``requestId`` and add ``retry=true`` after the initial attempt.
+Snowflake uses retained statement history to resolve an identical submission;
+this is not an unlimited deduplication or exactly-once guarantee. The transport
+owns this wiring.
 """
 
 from __future__ import annotations
@@ -32,7 +32,7 @@ class RetryPolicy:
     multiplier: float = 2.0
     jitter: bool = True
     retry_statuses: FrozenSet[int] = field(
-        # 408 (request timeout) is safe to retry: submits reuse their requestId.
+        # Submissions retain their requestId and use retry=true after a timeout.
         default_factory=lambda: frozenset({408, 429, 500, 502, 503, 504})
     )
 

{snowflake_sql_api-0.1.4 → snowflake_sql_api-0.1.5}/snowflake_sql_api/transport.py

@@ -4,8 +4,9 @@ Owns the actual ``httpx`` calls (sync and async), status-code interpretation
 (200 success, 202 long-running/async, 422 execution failure, 401 auth,
 403 forbidden, 429/5xx retryable), the retry loop, and ``requestId`` reuse for
 idempotent retries. A retried submit re-POSTs the identical body with the same
-``requestId`` and ``retry=true`` so Snowflake deduplicates instead of
-double-applying DML.
+``requestId`` and ``retry=true``. Snowflake resolves identical submissions
+through retained statement history, with no unlimited replay window or
+application-wide exactly-once guarantee.
 
 Higher layers (``client``/``aclient``) talk to the transport, not to ``httpx``.
 """
@@ -156,8 +157,12 @@ class _TransportBase:
             "User-Agent": self._user_agent,
         }
 
-    def _submit_params(self, request_id: str, async_exec: bool) -> Dict[str, str]:
+    def _submit_params(
+        self, request_id: str, async_exec: bool, retry: bool = False
+    ) -> Dict[str, str]:
         params = {"requestId": request_id}
+        if retry:
+            params["retry"] = "true"
         if async_exec:
             params["async"] = "true"
         return params
@@ -196,13 +201,14 @@ class Transport(_TransportBase):
         *,
         request_id: str,
         async_exec: bool = False,
+        retry: bool = False,
         content: Optional[bytes] = None,
     ) -> StatementResponse:
         """POST a statement, retrying idempotently on transient failure."""
         return self._send(
             "POST",
             STATEMENTS_PATH,
-            params=self._submit_params(request_id, async_exec),
+            params=self._submit_params(request_id, async_exec, retry),
             json=payload if content is None else None,
             content=content,
             is_submit=True,
@@ -308,12 +314,13 @@ class AsyncTransport(_TransportBase):
         *,
         request_id: str,
         async_exec: bool = False,
+        retry: bool = False,
         content: Optional[bytes] = None,
     ) -> StatementResponse:
         return await self._send(
             "POST",
             STATEMENTS_PATH,
-            params=self._submit_params(request_id, async_exec),
+            params=self._submit_params(request_id, async_exec, retry),
             json=payload if content is None else None,
             content=content,
             is_submit=True,