feat: expose per-call merge retry controls in Python and Node (#5015)

Python and Node callers could not disable precommit retries for one
merge without changing the connection. Add `execute(..., retries=0)` for
Python sync/async and `execute(data, { retries: 0 })` for TypeScript,
forwarding into the existing Rust control without persisting the
override. Ambiguous 5xx outcomes remain non-replayable; permitted merge
retries now log status and attempt at WARN, and the API docs explain
retry budgets and timeout boundaries.

Validation at `6001300` passed 70 Python HTTP cases, 36 Node HTTP cases,
14 local merge regressions per binding, and 34 scoped Rust tests, with
rebuilt native extensions, TypeScript compilation, Clippy, scoped
formatting/lint, and generated API docs. The public API and feature diff
are unchanged after integrating main and the reviewed ingestion guide;
that binding evidence is retained. Focused merged-tree validation
additionally passed 267 Rust merge/retry/provenance cases and the CI
fixtures. Existing root Ruff issues in docs/web-tests remain; local
fixtures do not establish live proxy/server cancellation behavior.

Refs #4256 and OSS-2370.
This commit is contained in:
Xuanwo
2026-11-14 22:43:56 +08:00
committed by GitHub
parent dc9eb269b1
commit e2f836da99
14 changed files with 433 additions and 10 deletions
+6
View File
@@ -565,6 +565,12 @@ class Table:
allow_external_blob_outside_bases: bool = False,
retries: Optional[int] = None,
) -> AddResult: ...
async def execute_merge_insert(
self,
data: pa.RecordBatchReader,
parameters: Dict[str, Any],
retries: Optional[int] = None,
) -> MergeResult: ...
async def update(
self, updates: Dict[str, str], where: Optional[str]
) -> UpdateResult: ...
+21 -2
View File
@@ -161,6 +161,8 @@ class LanceMergeInsertBuilder(object):
on_bad_vectors: str = "error",
fill_value: float = 0.0,
timeout: Optional[timedelta] = None,
*,
retries: Optional[int] = None,
) -> MergeInsertResult:
"""
Executes the merge insert operation
@@ -189,7 +191,22 @@ class LanceMergeInsertBuilder(object):
first attempt will not be cancelled.
When this is set, the timeout is enforced on all attempts, including
the first.
the first. For remote tables it is sent as a server execution timeout;
it does not extend HTTP read or proxy idle timeouts, or prove that a
failed request did not commit.
retries: int, optional
Override the remote retry budget for this execution only (0 to 255).
Use ``execute(new_data, retries=0)`` to disable even retries after
precommit conflicts (409) or rate limits (429). This does not change
connection-wide/read budgets or local transaction conflict retries.
By default, remote calls use the connection's
[RetryConfig][lancedb.remote.RetryConfig]. Its ``statuses`` (also set
through ``LANCE_CLIENT_RETRY_STATUSES``) selects candidates within
the retry budget; it never permits replay of ambiguous merge outcomes.
In particular, 502, ordinary 503, and 504 are never replayed, even if
configured. Reconcile table contents before manually repeating a merge
whose commit outcome is unknown.
Returns
-------
@@ -198,4 +215,6 @@ class LanceMergeInsertBuilder(object):
"""
if timeout is not None:
self._timeout = timeout
return self._table._do_merge(self, new_data, on_bad_vectors, fill_value)
return self._table._do_merge(
self, new_data, on_bad_vectors, fill_value, retries=retries
)
+2 -1
View File
@@ -945,9 +945,10 @@ class RemoteTable(Table):
new_data: DATA,
on_bad_vectors: str,
fill_value: float,
retries: Optional[int] = None,
) -> MergeResult:
return LOOP.run(
self._table._do_merge(merge, new_data, on_bad_vectors, fill_value)
self._table._do_merge(merge, new_data, on_bad_vectors, fill_value, retries)
)
@_deprecated_keyword("predicate", "where")
+5 -1
View File
@@ -2810,6 +2810,7 @@ class Table(ABC):
new_data: DATA,
on_bad_vectors: OnBadVectorsType,
fill_value: float,
retries: Optional[int] = None,
) -> MergeResult: ...
@abstractmethod
@@ -5443,9 +5444,10 @@ class LanceTable(Table):
new_data: DATA,
on_bad_vectors: OnBadVectorsType,
fill_value: float,
retries: Optional[int] = None,
) -> MergeResult:
return LOOP.run(
self._table._do_merge(merge, new_data, on_bad_vectors, fill_value)
self._table._do_merge(merge, new_data, on_bad_vectors, fill_value, retries)
)
@property
@@ -7777,6 +7779,7 @@ class AsyncTable:
new_data: DATA,
on_bad_vectors: OnBadVectorsType,
fill_value: float,
retries: Optional[int] = None,
) -> MergeResult:
schema = await self.schema()
if on_bad_vectors is None:
@@ -7808,6 +7811,7 @@ class AsyncTable:
use_rte=merge._use_rte,
validate_single_shard=merge._validate_single_shard,
),
retries=retries,
)
async def delete(self, where: Union[str, Expr]) -> DeleteResult:
+158
View File
@@ -310,6 +310,164 @@ async def test_add_retry_override(sync_api, retries, status):
assert attempts == (2 if expected_success else 1)
@pytest.mark.parametrize("sync_api", [False, True])
@pytest.mark.parametrize("namespace_path", [[], ["analytics", "features"]])
@pytest.mark.parametrize("retries", [None, 0, 2])
@pytest.mark.parametrize("status", [409, 429, 502, 503, 504])
@pytest.mark.asyncio
async def test_merge_retry_override(sync_api, namespace_path, retries, status, capfd):
attempts = 0
identifier = "$".join(namespace_path + ["test"])
def handler(request):
nonlocal attempts
if request.path == f"/v1/table/{identifier}/describe/":
send_json(
request,
{
"version": 1,
"schema": {
"fields": [
{"name": "id", "type": {"type": "int64"}, "nullable": True}
]
},
},
)
return
assert urlparse(request.path).path == f"/v1/table/{identifier}/merge_insert/"
query = parse_qs(urlparse(request.path).query)
assert query["use_index"] == ["false"]
assert request.headers["x-request-timeout-ms"] == "10000"
body = bytearray()
if request.headers.get("Transfer-Encoding") == "chunked":
while True:
size = int(request.rfile.readline().strip(), 16)
if size == 0:
request.rfile.readline()
break
body.extend(request.rfile.read(size))
request.rfile.read(2)
else:
body.extend(
request.rfile.read(int(request.headers.get("Content-Length", 0)))
)
assert pa.ipc.open_stream(body).read_all().to_pylist() == [{"id": 1}]
attempts += 1
send_json(request, {"version": 2}, status if attempts == 1 else 200)
config = {
"retry_config": {
"retries": 3,
"statuses": [409, 429, 502, 503, 504],
"backoff_factor": 0,
"backoff_jitter": 0,
}
}
expected_success = status in (409, 429) and retries != 0
async def check(table):
merge = table.merge_insert("id").when_not_matched_insert_all().use_index(False)
options = {"timeout": timedelta(seconds=10)}
if retries is not None:
options["retries"] = retries
if expected_success:
result = merge.execute([{"id": 1}], **options)
if not sync_api:
result = await result
assert result.version == 2
else:
with pytest.raises((HttpError, RetryError)):
result = merge.execute([{"id": 1}], **options)
if not sync_api:
await result
if sync_api:
with mock_lancedb_connection(handler, **config) as db:
await check(db.open_table("test", namespace_path=namespace_path))
else:
async with mock_lancedb_connection_async(handler, **config) as db:
await check(await db.open_table("test", namespace_path=namespace_path))
assert attempts == (2 if expected_success else 1)
warnings = [
line
for line in capfd.readouterr().err.splitlines()
if "Retrying merge insert" in line
]
assert len(warnings) == (1 if expected_success else 0)
if expected_success:
assert "WARN" in warnings[0]
assert f"status Some({status}); attempt 2" in warnings[0]
@pytest.mark.parametrize("sync_api", [False, True])
@pytest.mark.asyncio
async def test_merge_retry_override_isolation(sync_api):
attempts = 0
read_attempts = 0
def handler(request):
nonlocal attempts, read_attempts
if request.path.endswith("/describe/"):
send_json(
request,
{
"version": 1,
"schema": {
"fields": [
{"name": "id", "type": {"type": "int64"}, "nullable": True}
]
},
},
)
elif request.path.endswith("/count_rows/"):
read_attempts += 1
send_json(request, 1, 429 if read_attempts % 2 else 200)
else:
assert urlparse(request.path).path.endswith("/merge_insert/")
attempts += 1
send_json(request, {"version": 2}, 429 if attempts in (1, 2, 4, 6) else 200)
async def check(table):
merge = table.merge_insert("id").when_not_matched_insert_all()
for retries in [-1, 256, 1.5, "1"]:
with pytest.raises((OverflowError, TypeError, ValueError)):
result = merge.execute([{"id": 1}], retries=retries)
if not sync_api:
await result
assert attempts == 0
with pytest.raises((HttpError, RetryError)):
result = merge.execute([{"id": 1}], retries=0)
if not sync_api:
await result
assert attempts == 1
for options in ({}, {"retries": 255}):
result = merge.execute([{"id": 1}], **options)
if not sync_api:
result = await result
assert result.version == 2
assert attempts == 5
result = table.count_rows()
if not sync_api:
result = await result
assert result == 1
assert read_attempts == 2
result = (
table.merge_insert("id").when_not_matched_insert_all().execute([{"id": 1}])
)
if not sync_api:
result = await result
assert result.version == 2
assert attempts == 7
config = {"retry_config": {"retries": 3, "backoff_factor": 0, "backoff_jitter": 0}}
if sync_api:
with mock_lancedb_connection(handler, **config) as db:
await check(db.open_table("test"))
else:
async with mock_lancedb_connection_async(handler, **config) as db:
await check(await db.open_table("test"))
@pytest.fixture
def missing_table_handler(cached, namespace_path):
request_ids = []
+3 -2
View File
@@ -3448,7 +3448,8 @@ def test_merge_insert(mem_db: DBConnection):
table.merge_insert("a")
.when_matched_update_all()
.when_not_matched_insert_all()
.execute(new_data, timeout=timedelta(seconds=10))
.use_index(False)
.execute(new_data, timeout=timedelta(seconds=10), retries=0)
)
assert merge_insert_res.version == 2
assert merge_insert_res.num_inserted_rows == 1
@@ -3527,7 +3528,7 @@ def test_merge_insert(mem_db: DBConnection):
# timeout
with pytest.raises(Exception, match="merge insert timed out"):
table.merge_insert("a").when_matched_update_all().execute(
new_data, timeout=timedelta(0)
new_data, timeout=timedelta(0), retries=255
)
+5
View File
@@ -2269,10 +2269,12 @@ impl Table {
})
}
#[pyo3(signature = (data, parameters, retries=None))]
pub fn execute_merge_insert<'a>(
self_: PyRef<'a, Self>,
data: Bound<'a, PyAny>,
parameters: MergeInsertParams,
retries: Option<u8>,
) -> PyResult<Bound<'a, PyAny>> {
let batches: ArrowArrayStreamReader = ArrowArrayStreamReader::from_pyarrow_bound(&data)?;
let on = parameters.on.iter().map(|s| s.as_str()).collect::<Vec<_>>();
@@ -2295,6 +2297,9 @@ impl Table {
if let Some(timeout) = parameters.timeout {
builder.timeout(timeout);
}
if let Some(retries) = retries {
builder.retries(retries);
}
if let Some(use_index) = parameters.use_index {
builder.use_index(use_index);
}