mirror of
https://github.com/lancedb/lancedb.git
synced 2026-11-16 07:36:50 +00:00
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:
@@ -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: ...
|
||||
|
||||
@@ -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
|
||||
)
|
||||
|
||||
@@ -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")
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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 = []
|
||||
|
||||
@@ -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
|
||||
)
|
||||
|
||||
|
||||
|
||||
@@ -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);
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user