feat(python): support exist_ok when cloning tables (#4990)

Adds `exist_ok=False` to Python table cloning and `.exist_ok(true)` to
the Rust clone builder. An existing target is returned with its data and
version history unchanged; strict duplicate errors remain the default.

```python
snapshot = db.clone_table("snapshot", source_uri, exist_ok=True)
```

Embedded cloning skips source reads for an existing target and handles
typed creation conflicts. Remote cloning forwards the option to the
server. Includes sync/async preservation and remote request coverage,
plus SQL syntax documentation for `CREATE TABLE IF NOT EXISTS target
CLONE source`. Requires a server supporting the option for remote
clones.

BREAKING CHANGE: Rust `CloneTableRequest` struct literals must
initialize the new `exist_ok` field; `CloneTableRequest::new` remains
compatible.

No local builds or tests were run, as requested.
This commit is contained in:
Jack Ye
2026-11-14 10:48:26 +08:00
committed by GitHub
parent a0eb6b4b71
commit 4db0d5c7f5
11 changed files with 162 additions and 30 deletions
+2
View File
@@ -347,6 +347,8 @@ class Connection(object):
source_version: Optional[int] = None,
source_tag: Optional[str] = None,
is_shallow: bool = True,
*,
exist_ok: bool = False,
) -> Table: ...
async def rename_table(
self,
+8
View File
@@ -2271,6 +2271,7 @@ class LanceDBConnection(DBConnection):
source_version: Optional[int] = None,
source_tag: Optional[str] = None,
is_shallow: bool = True,
exist_ok: bool = False,
) -> LanceTable:
"""Clone a table from a source table.
@@ -2295,6 +2296,8 @@ class LanceDBConnection(DBConnection):
is_shallow: bool, default True
Whether to perform a shallow clone (True) or deep clone (False).
Currently only shallow clone is supported.
exist_ok: bool, default False
Return the existing target unchanged instead of cloning over it.
Returns
-------
@@ -2310,6 +2313,7 @@ class LanceDBConnection(DBConnection):
source_version=source_version,
source_tag=source_tag,
is_shallow=is_shallow,
exist_ok=exist_ok,
)
)
return LanceTable.open(
@@ -3595,6 +3599,7 @@ class AsyncConnection(object):
source_version: Optional[int] = None,
source_tag: Optional[str] = None,
is_shallow: bool = True,
exist_ok: bool = False,
) -> AsyncTable:
"""Clone a table from a source table.
@@ -3619,6 +3624,8 @@ class AsyncConnection(object):
is_shallow: bool, default True
Whether to perform a shallow clone (True) or deep clone (False).
Currently only shallow clone is supported.
exist_ok: bool, default False
Return the existing target unchanged instead of cloning over it.
Returns
-------
@@ -3633,6 +3640,7 @@ class AsyncConnection(object):
source_version=source_version,
source_tag=source_tag,
is_shallow=is_shallow,
exist_ok=exist_ok,
)
return AsyncTable(table)
+4
View File
@@ -576,6 +576,7 @@ class RemoteDBConnection(DBConnection):
source_version: Optional[int] = None,
source_tag: Optional[str] = None,
is_shallow: bool = True,
exist_ok: bool = False,
) -> Table:
"""Clone a table from a source table.
@@ -595,6 +596,8 @@ class RemoteDBConnection(DBConnection):
is_shallow: bool, default True
Whether to perform a shallow clone (True) or deep clone (False).
Currently only shallow clone is supported.
exist_ok: bool, default False
Return the existing target unchanged instead of cloning over it.
Returns
-------
@@ -612,6 +615,7 @@ class RemoteDBConnection(DBConnection):
source_version=source_version,
source_tag=source_tag,
is_shallow=is_shallow,
exist_ok=exist_ok,
)
)
return RemoteTable(
@@ -0,0 +1,36 @@
# SPDX-License-Identifier: Apache-2.0
# SPDX-FileCopyrightText: Copyright The LanceDB Authors
import pytest
import lancedb
@pytest.mark.asyncio
@pytest.mark.parametrize("asynchronous", [False, True])
async def test_clone_exist_ok_preserves_target(tmp_path, asynchronous):
source_uri = str(tmp_path / "source.lance")
if asynchronous:
db = await lancedb.connect_async(tmp_path)
await db.create_table("source", [{"id": 1}])
table = await db.clone_table("target", source_uri, exist_ok=True)
assert (await table.to_arrow()).to_pylist() == [{"id": 1}]
await table.add([{"id": 2}])
version = await table.version()
with pytest.raises(ValueError, match="already exists"):
await db.clone_table("target", source_uri)
kept = await db.clone_table("target", "missing.lance", exist_ok=True)
assert await kept.version() == version
assert (await kept.to_arrow()).to_pylist() == [{"id": 1}, {"id": 2}]
else:
db = lancedb.connect(tmp_path)
db.create_table("source", [{"id": 1}])
table = db.clone_table("target", source_uri, exist_ok=True)
assert table.to_arrow().to_pylist() == [{"id": 1}]
table.add([{"id": 2}])
version = table.version
with pytest.raises(ValueError, match="already exists"):
db.clone_table("target", source_uri)
kept = db.clone_table("target", "missing.lance", exist_ok=True)
assert kept.version == version
assert kept.to_arrow().to_pylist() == [{"id": 1}, {"id": 2}]
+4 -2
View File
@@ -457,7 +457,8 @@ impl Connection {
})
}
#[pyo3(signature = (target_table_name, source_uri, target_namespace_path=None, source_version=None, source_tag=None, is_shallow=true))]
#[allow(clippy::too_many_arguments)]
#[pyo3(signature = (target_table_name, source_uri, target_namespace_path=None, source_version=None, source_tag=None, is_shallow=true, *, exist_ok=false))]
pub fn clone_table(
self_: PyRef<'_, Self>,
target_table_name: String,
@@ -466,6 +467,7 @@ impl Connection {
source_version: Option<u64>,
source_tag: Option<String>,
is_shallow: bool,
exist_ok: bool,
) -> PyResult<Bound<'_, PyAny>> {
let inner = self_.get_inner()?.clone();
@@ -477,7 +479,7 @@ impl Connection {
if let Some(tag) = source_tag {
builder = builder.source_tag(tag);
}
builder = builder.is_shallow(is_shallow);
builder = builder.is_shallow(is_shallow).exist_ok(exist_ok);
future_into_py(self_.py(), async move {
let table = builder.execute().await.infer_error()?;