feat(python): support exist_ok when creating views (#4984)

Add `exist_ok=False` to synchronous and asynchronous Python view
creation. Passing `True` sends `CREATE VIEW IF NOT EXISTS` and returns
the existing view's stored query and schema unchanged; the default
continues to fail on an existing name.

```python
view = db.create_view("recent_orders", query, exist_ok=True)
view = await async_db.create_view("recent_orders", query, exist_ok=True)
```

Requires a SQL server supporting `CREATE VIEW IF NOT EXISTS`. Rust gains
an awaitable builder with `.exist_ok(true)`. Existing
`.create_view(...).await` calls continue to work; callers requiring
`Future` must convert the builder, and custom `Database` implementations
must accept the new `exist_ok` argument. Includes Python round-trip
coverage and Rust coverage for direct/deferred results and metadata
preservation.
This commit is contained in:
Jack Ye
2026-11-14 10:35:52 +08:00
committed by GitHub
parent 7d50d2d28f
commit b061c3627c
12 changed files with 239 additions and 25 deletions
+6 -1
View File
@@ -253,7 +253,12 @@ class Connection(object):
self, name: str, namespace_path: Optional[List[str]] = None
) -> Tuple[str, int, int]: ...
async def create_view(
self, name: str, query: str, namespace_path: Optional[List[str]] = None
self,
name: str,
query: str,
namespace_path: Optional[List[str]] = None,
*,
exist_ok: bool = False,
) -> Tuple[str, List[str], str, str, List[str], pa.Schema]: ...
async def describe_view(
self, name: str, namespace_path: Optional[List[str]] = None
+28 -8
View File
@@ -1273,7 +1273,12 @@ class DBConnection(EnforceOverrides):
)
def create_view(
self, name: str, query: str, *, namespace_path: Optional[List[str]] = None
self,
name: str,
query: str,
*,
exist_ok: bool = False,
namespace_path: Optional[List[str]] = None,
) -> ViewDescription:
"""Create a view: a named query the database plans on every read.
@@ -1281,9 +1286,10 @@ class DBConnection(EnforceOverrides):
is refused now rather than at the first read. A view holds no rows, and
its readers see its sources as they are at read time.
There is no replace: a name already taken is an error, and changing a
view is a drop followed by a create. LanceDB Embedded connections raise
``NotImplementedError``.
A name already taken is an error unless ``exist_ok=True``, which returns
the existing view's stored query and schema without changing them.
Changing a view is a drop followed by a create. LanceDB Embedded
connections raise ``NotImplementedError``.
>>> import lancedb
>>> db = lancedb.connect("db://my_database") # doctest: +SKIP
@@ -2592,10 +2598,17 @@ class LanceDBConnection(DBConnection):
@override
def create_view(
self, name: str, query: str, *, namespace_path: Optional[List[str]] = None
self,
name: str,
query: str,
*,
exist_ok: bool = False,
namespace_path: Optional[List[str]] = None,
) -> ViewDescription:
return LOOP.run(
self._conn.create_view(name, query, namespace_path=namespace_path)
self._conn.create_view(
name, query, exist_ok=exist_ok, namespace_path=namespace_path
)
)
@override
@@ -4107,7 +4120,12 @@ class AsyncConnection(object):
)
async def create_view(
self, name: str, query: str, *, namespace_path: Optional[List[str]] = None
self,
name: str,
query: str,
*,
exist_ok: bool = False,
namespace_path: Optional[List[str]] = None,
) -> ViewDescription:
"""Create a view: a named query the database plans on every read.
@@ -4115,7 +4133,9 @@ class AsyncConnection(object):
[DBConnection.create_view][lancedb.DBConnection.create_view].
"""
return _view_description(
await self._inner.create_view(name, query, list(namespace_path or []))
await self._inner.create_view(
name, query, list(namespace_path or []), exist_ok=exist_ok
)
)
async def describe_view(
+9 -2
View File
@@ -1197,10 +1197,17 @@ class RemoteDBConnection(DBConnection):
@override
def create_view(
self, name: str, query: str, *, namespace_path: Optional[List[str]] = None
self,
name: str,
query: str,
*,
exist_ok: bool = False,
namespace_path: Optional[List[str]] = None,
) -> ViewDescription:
return LOOP.run(
self._conn.create_view(name, query, namespace_path=namespace_path)
self._conn.create_view(
name, query, exist_ok=exist_ok, namespace_path=namespace_path
)
)
@override
+71
View File
@@ -0,0 +1,71 @@
# SPDX-License-Identifier: Apache-2.0
# SPDX-FileCopyrightText: Copyright The LanceDB Authors
import json
import pyarrow as pa
import pytest
import lancedb
@pytest.mark.asyncio
@pytest.mark.parametrize("asynchronous", [False, True])
@pytest.mark.parametrize(
("exist_ok", "existing"),
[(None, False), (False, False), (True, False), (True, True)],
)
async def test_create_view_exist_ok_preserves_server_metadata(
asynchronous, exist_ok, existing
):
flight = pytest.importorskip("pyarrow.flight")
original_query = "SELECT 'original' AS original"
submitted_query = (
"SELECT 'replacement' AS replacement" if existing else original_query
)
schema = {
"fields": [{"name": "original", "nullable": True, "type": {"type": "utf8"}}],
"metadata": {
"lancedb::view::default_db": "analytics",
"lancedb::view::default_namespace": "team",
},
}
result = pa.table(
{"name": ["saved"], "query": [original_query], "schema": [json.dumps(schema)]}
)
class ViewServer(flight.FlightServerBase):
def __init__(self):
super().__init__("grpc://127.0.0.1:0")
self.requests = []
def do_get(self, context, ticket):
self.requests.append(ticket.ticket)
return flight.RecordBatchStream(result)
with ViewServer() as server:
connection_options = {
"api_key": "test-key",
"host_override": "http://localhost:10024",
"sql_host_override": f"grpc://127.0.0.1:{server.port}",
}
kwargs = {} if exist_ok is None else {"exist_ok": exist_ok}
if asynchronous:
db = await lancedb.connect_async("db://analytics", **connection_options)
view = await db.create_view(
"saved", submitted_query, namespace_path=["team"], **kwargs
)
else:
db = lancedb.connect("db://analytics", **connection_options)
view = db.create_view(
"saved", submitted_query, namespace_path=["team"], **kwargs
)
(request,) = server.requests
prefix = "CREATE VIEW IF NOT EXISTS" if exist_ok else "CREATE VIEW"
assert f'{prefix} "saved" AS {submitted_query}'.encode() in request
assert view.name == "saved"
assert view.namespace_path == ["team"]
assert view.default_namespace_path == ["team"]
assert view.query == original_query
assert view.schema.names == ["original"]
+3 -1
View File
@@ -1158,18 +1158,20 @@ impl Connection {
})
}
#[pyo3(signature = (name, query, namespace_path=None))]
#[pyo3(signature = (name, query, namespace_path=None, *, exist_ok=false))]
pub fn create_view(
self_: PyRef<'_, Self>,
name: String,
query: String,
namespace_path: Option<Vec<String>>,
exist_ok: bool,
) -> PyResult<Bound<'_, PyAny>> {
let inner = self_.get_inner()?.clone();
let namespace_path = namespace_path.unwrap_or_default();
future_into_py(self_.py(), async move {
let view = inner
.create_view(name, query, &namespace_path)
.exist_ok(exist_ok)
.await
.infer_error()?;
view_description_to_py(view)