{"record":{"id":"f388cf00a8a31efa","repo":"pola-rs/polars","slug":"response-result-cursor-proxies","errorCode":null,"errorMessage":"{response[\"result\"]}","messagePattern":"\\{response\\[\"result\"\\]\\}","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/io/database/_cursor_proxies.py","lineNumber":99,"sourceCode":"    \"\"\"Cursor proxy for both SurrealDB and AsyncSurrealDB connections.\"\"\"\n\n    _cached_result: list[dict[str, Any]] | None = None\n\n    def __init__(self, client: Any) -> None:\n        surrealdb = import_optional(\"surrealdb\")\n        self.is_async = isinstance(client, surrealdb.AsyncSurrealDB)\n        self.execute_options: dict[str, Any] = {}\n        self.client = client\n        self.query: str = None  # type: ignore[assignment]\n\n    @staticmethod\n    async def _unpack_result_async(\n        result: Coroutine[Any, Any, list[dict[str, Any]]],\n    ) -> Coroutine[Any, Any, list[dict[str, Any]]]:\n        \"\"\"Unpack the async query result.\"\"\"\n        response = (await result)[0]\n        if response[\"status\"] != \"OK\":\n            raise RuntimeError(response[\"result\"])\n        return response[\"result\"]\n\n    @staticmethod\n    def _unpack_result(\n        result: list[dict[str, Any]],\n    ) -> list[dict[str, Any]]:\n        \"\"\"Unpack the query result.\"\"\"\n        response = result[0]\n        if response[\"status\"] != \"OK\":\n            raise RuntimeError(response[\"result\"])\n        return response[\"result\"]\n\n    def close(self) -> None:\n        \"\"\"Close the cursor.\"\"\"\n        # no-op; never close a user's Surreal session\n\n    def execute(self, query: str, **execute_options: Any) -> Self:\n        \"\"\"Execute a query (n/a: just store query for the fetch* methods).\"\"\"","sourceCodeStart":81,"sourceCodeEnd":117,"githubUrl":"https://github.com/pola-rs/polars/blob/fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e/py-polars/src/polars/io/database/_cursor_proxies.py#L81-L117","documentation":"`ALTS cursor proxies` (used by the `alts` database adapter in `pl.read_database`) expect each async query result envelope to have `status == \"OK\"`. `_unpack_result_async` raises `RuntimeError(response[\"result\"])` when the remote ALTS/service reports a non-OK status, surfacing the server-provided error string directly to the caller.","triggerScenarios":"Calling `fetchall()` on an async ALTS cursor proxy where the first response dict has `status != \"OK\"` — e.g. a failed SQL query, auth failure, or server-side error returned in the `result` field.","commonSituations":"Broken or invalid SQL sent through the ALTS endpoint; expired credentials or insufficient permissions on the remote service; the ALTS service returning an error payload that polars unwraps verbatim; network/service outages producing error envelopes.","solutions":["Read the RuntimeError message — it is the server's `result` field — and fix the underlying query or permission it reports.","Validate/limit the SQL query before executing (correct table/column names, syntax).","Re-authenticate or refresh credentials for the ALTS connection.","Retry with backoff if the status reflects a transient service issue, and check service health."],"exampleFix":"// before\ncursor.execute(\"SELCT * FROM t\")  # typo, server returns non-OK status\nrows = await cursor.fetchall()  # RuntimeError: parse error...\n// after\ncursor.execute(\"SELECT * FROM t\")\nrows = await cursor.fetchall()","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try:\n    rows = await cursor.fetchall()\nexcept RuntimeError as e:\n    log.error(\"ALTS query failed: %s\", e)\n    # inspect e.args for the server-provided reason; fix query/creds or retry","preventionTips":["Validate SQL syntax and object names before executing against ALTS.","Refresh credentials/session tokens before long-running jobs.","Wrap remote query execution with retry/backoff for transient statuses and log the server result message."],"tags":["python","database","async","sql"],"backgroundTag":"sql-query-failed","analyzedSha":"fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e","analyzedAt":"2026-09-18T22:14:11.667Z","contentChangedAt":"2026-09-18T22:14:11.667Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}