Skip to content

Commit 5668a0e

Browse files
vuanhphungIsaac
andcommitted
perf(kernel): cut per-query Python work for small results
Each query rebuilt the cursor description and a Row factory from the Arrow schema, and each row fetch combined the record batches into a Table, whose construction releases and re-takes the GIL. Connections now keep what they derive from the last result schema and reuse it while statements return an equal schema, and small results are converted from the batches directly (falling back to the Table when a batch schema does not match). Closing a sync result skips the async-handle bookkeeping, and staging-verb detection no longer copies the statement. Signed-off-by: Vu Anh Phung <vu.phung@databricks.com> Co-authored-by: Isaac <no-reply@databricks.com>
1 parent 51214d2 commit 5668a0e

5 files changed

Lines changed: 283 additions & 50 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
- Fix inline parameters (`use_inline_params=True`) so a sequence directly after `IN` renders as a list again: `x IN %(ids)s` renders as `x IN (1,2,3)` instead of `x IN ARRAY(1,2,3)`, which Spark rejects. Inside the list, tuples render as rows for a multi-column `IN`, and a `set` or `frozenset` is accepted again. Sequences anywhere else still render as `ARRAY(...)` ([#629](https://github.com/databricks/databricks-sql-python/issues/629))
66
- Speed up Thrift response handling: read replies in 1 MiB chunks and decode them with Thrift's C-accelerated protocol, and stop stringifying every request/response for the default no-op debug logger. Wide result schemas, metadata calls with many rows, and inline Arrow results benefit most.
77
- Speed up fetching small results on the kernel backend (`use_kernel=True`): they are converted to rows without building a pandas DataFrame when that is cheaper and gives the same values, which cut client CPU per query by 47% in a local benchmark of 200 concurrent sessions running one-row queries against a mock server.
8+
- Cut more per-query work on the kernel backend: reuse the cursor description while a connection's statements return the same result schema, and build small results' rows straight from the record batches instead of first combining them into a table.
89

910
# 4.9.0 (2026-11-04)
1011
- Upgrade Databricks SQL Kernel to 1.4.0, which keeps Lakehouse Real-Time session affinity and flushes shared telemetry only after the final session closes.

‎src/databricks/sql/backend/kernel/client.py‎

Lines changed: 17 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@
4545
wrap_kernel_exception as _wrap_kernel_exception,
4646
)
4747
from databricks.sql.backend.kernel.auth_bridge import kernel_auth_kwargs
48-
from databricks.sql.backend.kernel.result_set import KernelResultSet
48+
from databricks.sql.backend.kernel.result_set import KernelResultSet, _SchemaCache
4949
from databricks.sql.backend.kernel.type_mapping import bind_tspark_params
5050
from databricks.sql.backend.types import (
5151
BackendType,
@@ -90,10 +90,9 @@
9090
_STAGING_VERBS = ("PUT", "GET", "REMOVE")
9191

9292

93-
def _strip_leading_sql_comments(sql: str) -> str:
94-
"""Strip leading whitespace and SQL comments (``-- …`` line and
95-
``/* … */`` block, possibly several) from ``sql``, returning the
96-
remainder.
93+
def _sql_start(sql: str) -> int:
94+
"""Index of the first character of ``sql`` after leading whitespace and
95+
SQL comments (``-- …`` line and ``/* … */`` block, possibly several).
9796
9897
Needed so staging detection sees the real leading verb: a
9998
comment-prefixed staging op (``-- upload\\nPUT …`` or
@@ -117,7 +116,7 @@ def _strip_leading_sql_comments(sql: str) -> str:
117116
i = n if close == -1 else close + 2
118117
else:
119118
break
120-
return sql[i:]
119+
return i
121120

122121

123122
def _is_not_found(exc: BaseException) -> bool:
@@ -164,9 +163,11 @@ def _is_staging_statement(operation: str) -> bool:
164163
only — so a normal query that merely *contains* the word (e.g.
165164
``SELECT 'GET' AS x``) isn't misflagged.
166165
"""
167-
stripped = _strip_leading_sql_comments(operation)
168-
# First whitespace-delimited token, uppercased.
169-
verb = stripped.split(None, 1)[0].upper() if stripped.strip() else ""
166+
start = _sql_start(operation)
167+
# First whitespace-delimited token, uppercased. The verbs have at most 6
168+
# characters, so the first 7 decide it without copying the statement.
169+
head = operation[start : start + 7]
170+
verb = head.split(None, 1)[0].upper() if head.strip() else ""
170171
return verb in _STAGING_VERBS
171172

172173

@@ -436,6 +437,7 @@ def __init__(
436437
# Guarded by its own lock — cancel can race execute teardown.
437438
self._sync_cancellers: Dict[int, Any] = {}
438439
self._sync_cancellers_lock = threading.RLock()
440+
self._schema_cache = _SchemaCache()
439441

440442
# ── Session lifecycle ──────────────────────────────────────────
441443

@@ -822,6 +824,11 @@ def cancel_running_cursor(self, cursor: "Cursor") -> bool:
822824
return True
823825

824826
def close_command(self, command_id: CommandId) -> None:
827+
guid = command_id.guid
828+
if guid not in self._async_handles and guid not in self._async_statements:
829+
# Sync and metadata results are never tracked, so there is nothing
830+
# to close or clean up.
831+
return
825832
with self._async_handles_lock:
826833
handle = self._async_handles.pop(command_id.guid, None)
827834
stmt = self._async_statements.pop(command_id.guid, None)
@@ -1056,6 +1063,7 @@ def _make_result_set(
10561063
command_id=command_id,
10571064
arraysize=cursor.arraysize,
10581065
buffer_size_bytes=cursor.buffer_size_bytes,
1066+
schema_cache=self._schema_cache,
10591067
)
10601068

10611069
def _synthetic_command_id(self) -> CommandId:

‎src/databricks/sql/backend/kernel/result_set.py‎

Lines changed: 97 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@
3232

3333
import logging
3434
from collections import deque
35-
from typing import Any, Deque, List, Optional, Tuple, TYPE_CHECKING, cast
35+
from typing import Any, Deque, List, Optional, TYPE_CHECKING, cast
3636

3737
import pyarrow
3838

@@ -119,36 +119,76 @@ def _max_rows_without_pandas(types: List[pyarrow.DataType]) -> int:
119119
return min(_MAX_ROWS_WITHOUT_PANDAS, _MAX_COST_WITHOUT_PANDAS // total)
120120

121121

122+
class _ResultSchema:
123+
"""What a result set derives from its Arrow schema."""
124+
125+
__slots__ = (
126+
"schema",
127+
"description",
128+
"row_factory",
129+
"max_rows_without_pandas",
130+
"float_columns",
131+
)
132+
133+
def __init__(self, schema: pyarrow.Schema):
134+
self.schema = schema
135+
self.description = tuple(description_from_arrow_schema(schema))
136+
self.row_factory = Row(*[c[0] for c in self.description])
137+
types = schema.types
138+
self.max_rows_without_pandas = _max_rows_without_pandas(types)
139+
self.float_columns = tuple(
140+
i for i, t in enumerate(types) if t.id in _FLOAT_TYPE_IDS
141+
)
142+
143+
144+
class _SchemaCache:
145+
"""Keeps the last ``_ResultSchema`` of a connection, since repeated
146+
statements return equal schemas."""
147+
148+
__slots__ = ("_last",)
149+
150+
def __init__(self) -> None:
151+
self._last: Optional[_ResultSchema] = None
152+
153+
def get(self, schema: pyarrow.Schema) -> _ResultSchema:
154+
last = self._last
155+
if last is not None and schema.equals(last.schema, check_metadata=True):
156+
return last
157+
last = self._last = _ResultSchema(schema)
158+
return last
159+
160+
122161
def _rows_without_pandas(
123-
table: pyarrow.Table, description: List[Tuple]
162+
batches: List[pyarrow.RecordBatch], result_schema: _ResultSchema
124163
) -> Optional[List[Row]]:
125-
"""The rows of ``table`` built from ``to_pylist()``, or None if the table
126-
must go through pandas (too costly, or a column whose values could
127-
differ)."""
128-
num_rows = table.num_rows
129-
# No weight is below 1, so this rules out larger results without
130-
# looking at every column type.
131-
if num_rows * table.num_columns > _MAX_COST_WITHOUT_PANDAS:
132-
return None
133-
if num_rows > _max_rows_without_pandas(table.schema.types):
134-
return None
135-
columns = []
136-
for column in table.itercolumns():
137-
try:
138-
values = column.to_pylist()
139-
except Exception:
140-
# E.g. a date past 9999-12-31: pandas then raises its own error,
141-
# as it does without this fast path.
142-
logger.debug(
143-
"to_pylist() failed for a %s column; using pandas",
144-
column.type,
145-
exc_info=True,
146-
)
164+
"""The rows of ``batches`` built from ``to_pylist()``, or None if they
165+
must go through a Table and pandas (too costly, a column whose values
166+
could differ, or a batch whose schema does not match)."""
167+
num_rows = 0
168+
for batch in batches:
169+
if not batch.schema.equals(result_schema.schema):
147170
return None
148-
if column.type.id in _FLOAT_TYPE_IDS and any(v != v for v in values):
171+
num_rows += batch.num_rows
172+
if num_rows > result_schema.max_rows_without_pandas:
173+
return None
174+
columns: List[List[Any]] = [[] for _ in result_schema.description]
175+
for batch in batches:
176+
for values, column in zip(columns, batch.columns):
177+
try:
178+
values.extend(column.to_pylist())
179+
except Exception:
180+
# E.g. a date past 9999-12-31: pandas then raises its own
181+
# error, as it does without this fast path.
182+
logger.debug(
183+
"to_pylist() failed for a %s column; using pandas",
184+
column.type,
185+
exc_info=True,
186+
)
187+
return None
188+
for i in result_schema.float_columns:
189+
if any(v != v for v in columns[i]):
149190
return None
150-
columns.append(values)
151-
row_factory = Row(*[c[0] for c in description])
191+
row_factory = result_schema.row_factory
152192
return [row_factory(*values) for values in zip(*columns)]
153193

154194

@@ -170,11 +210,16 @@ def __init__(
170210
command_id: CommandId,
171211
arraysize: int,
172212
buffer_size_bytes: int,
213+
schema_cache: Optional[_SchemaCache] = None,
173214
):
174215
try:
175216
schema = kernel_handle.arrow_schema()
176217
except Exception as exc:
177218
raise wrap_kernel_exception("KernelResultSet.arrow_schema", exc) from exc
219+
if schema_cache is None:
220+
self._result_schema = _ResultSchema(schema)
221+
else:
222+
self._result_schema = schema_cache.get(schema)
178223
super().__init__(
179224
connection=connection,
180225
backend=backend,
@@ -185,7 +230,7 @@ def __init__(
185230
has_been_closed_server_side=False,
186231
has_more_rows=True,
187232
results_queue=None,
188-
description=description_from_arrow_schema(schema),
233+
description=list(self._result_schema.description),
189234
is_staging_operation=False,
190235
lz4_compressed=False,
191236
arrow_schema_bytes=None,
@@ -237,8 +282,14 @@ def _ensure_buffered(self, n_rows: int) -> int:
237282
def _buffered_rows(self) -> int:
238283
return self._buffered_count
239284

285+
def _to_table(self, batches: List[pyarrow.RecordBatch]) -> pyarrow.Table:
286+
return pyarrow.Table.from_batches(batches, schema=self._schema)
287+
240288
def _take_buffered(self, n: int) -> pyarrow.Table:
241289
"""Slice up to ``n`` rows out of the buffer; advances state."""
290+
return self._to_table(self._take_buffered_batches(n))
291+
292+
def _take_buffered_batches(self, n: int) -> List[pyarrow.RecordBatch]:
242293
slices: List[pyarrow.RecordBatch] = []
243294
remaining = n
244295
while remaining > 0 and self._buffer:
@@ -254,13 +305,14 @@ def _take_buffered(self, n: int) -> pyarrow.Table:
254305
taken = n - remaining
255306
self._buffered_count -= taken
256307
self._next_row_index += taken
257-
if not slices:
258-
return pyarrow.Table.from_batches([], schema=self._schema)
259-
return pyarrow.Table.from_batches(slices, schema=self._schema)
308+
return slices
260309

261310
def _drain(self) -> pyarrow.Table:
262311
"""Consume everything left in the buffer + kernel stream
263312
and return as a single Table."""
313+
return self._to_table(self._drain_batches())
314+
315+
def _drain_batches(self) -> List[pyarrow.RecordBatch]:
264316
chunks: List[pyarrow.RecordBatch] = []
265317
if self._buffer and self._buffer_offset > 0:
266318
head = self._buffer.popleft()
@@ -286,9 +338,7 @@ def _drain(self) -> pyarrow.Table:
286338
rows = sum(c.num_rows for c in chunks)
287339
self._buffered_count = 0
288340
self._next_row_index += rows
289-
if not chunks:
290-
return pyarrow.Table.from_batches([], schema=self._schema)
291-
return pyarrow.Table.from_batches(chunks, schema=self._schema)
341+
return chunks
292342

293343
# ----- Arrow fetches -----
294344

@@ -305,9 +355,18 @@ def fetchmany_arrow(self, size: int) -> pyarrow.Table:
305355

306356
# ----- Row fetches -----
307357

358+
def _rows(self, batches: List[pyarrow.RecordBatch]) -> List[Row]:
359+
# Small results skip building a Table, which releases and re-takes
360+
# the GIL, as well as pandas.
361+
if self.connection.disable_pandas is not True:
362+
rows = _rows_without_pandas(batches, self._result_schema)
363+
if rows is not None:
364+
return rows
365+
return super()._convert_arrow_table(self._to_table(batches))
366+
308367
def _convert_arrow_table(self, table):
309368
if self.connection.disable_pandas is not True:
310-
rows = _rows_without_pandas(table, self.description)
369+
rows = _rows_without_pandas(table.to_batches(), self._result_schema)
311370
if rows is not None:
312371
return rows
313372
return super()._convert_arrow_table(table)
@@ -316,8 +375,7 @@ def fetchone(self) -> Optional[Row]:
316375
self._ensure_buffered(1)
317376
if self._buffered_rows() == 0:
318377
return None
319-
table = self._take_buffered(1)
320-
rows = self._convert_arrow_table(table)
378+
rows = self._rows(self._take_buffered_batches(1))
321379
return rows[0] if rows else None
322380

323381
def fetchmany(self, size: int) -> List[Row]:
@@ -326,11 +384,10 @@ def fetchmany(self, size: int) -> List[Row]:
326384
if size == 0:
327385
return []
328386
self._ensure_buffered(size)
329-
table = self._take_buffered(size)
330-
return self._convert_arrow_table(table)
387+
return self._rows(self._take_buffered_batches(size))
331388

332389
def fetchall(self) -> List[Row]:
333-
return self._convert_arrow_table(self._drain())
390+
return self._rows(self._drain_batches())
334391

335392
def close(self) -> None:
336393
"""Close the underlying kernel handle and notify the backend.

‎tests/unit/test_kernel_client.py‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1066,6 +1066,15 @@ def test_staging_operation_raises_not_supported(operation):
10661066
("INSERT INTO t VALUES (1)", False),
10671067
("", False),
10681068
("-- just a comment", False), # comment only, no statement
1069+
# Only the leading token counts, however long it is.
1070+
("PUT", True),
1071+
("remove\t'/v'", True),
1072+
("GET/* c */ '/v' TO '/f'", False),
1073+
("PUTX '/f'", False),
1074+
("REMOVED '/v'", False),
1075+
("REMOVEX", False),
1076+
("GETTING_STARTED", False),
1077+
(" -- c\n" + "x" * 10_000, False),
10691078
],
10701079
)
10711080
def test_is_staging_statement(operation, is_staging):
@@ -1285,6 +1294,22 @@ def test_close_command_tolerant_when_handle_missing():
12851294
c.close_command(fake_command_id) # must not raise
12861295

12871296

1297+
def test_close_command_closes_a_statement_tracked_without_its_handle():
1298+
c = _make_client()
1299+
c._async_handles_lock = MagicMock()
1300+
untracked = CommandId.from_sea_statement_id("sync")
1301+
c.close_command(untracked)
1302+
# Sync results were never tracked, so closing them takes no lock.
1303+
c._async_handles_lock.__enter__.assert_not_called()
1304+
1305+
stmt = MagicMock()
1306+
cid = CommandId.from_sea_statement_id("async")
1307+
c._async_statements[cid.guid] = stmt
1308+
c.close_command(cid)
1309+
stmt.close.assert_called_once()
1310+
assert cid.guid not in c._async_statements
1311+
1312+
12881313
def _attach_returns(c, *, status=None, status_error=None, await_result=None):
12891314
"""Wire ``_kernel_session.attach_async_statement`` to return a fake
12901315
handle. ``status`` is a ``(state, failure)`` tuple for ``handle.status()``;

0 commit comments

Comments
 (0)