feat: add view CRUD APIs (#4236)

A view is a named query a database stores and plans on every read. It
holds no rows, which is the whole difference from a materialized view.

## API

| Verb | Route |
| --- | --- |
| `create_view(name, query, namespace_path)` | `POST
/v1/view/{id}/create` |
| `describe_view(name, namespace_path)` | `POST /v1/view/{id}/describe`
|
| `drop_view(name, namespace_path)` | `POST /v1/view/{id}/drop` |
| `list_views(namespace_path)` | `GET /v1/namespace/{id}/view/list` |

On `Connection` and the `Database` trait, with the remote client, Python
(sync and async) and Node bindings. Local databases return
`NotSupported`: the server side is Sophon's, where a view is an object
of the database manifest.

`ViewDescription` carries the defining query, the database *and
namespace path* unqualified names in it resolve against, and the schema
the query resolved to. `create_view` returns one, so a caller has the
schema without a second call.

Both defaults travel with the view because it outlives the session that
declared it: the server re-plans the stored query on every read, so a
reader resolving an unqualified name against its own defaults would read
a different table. `default_namespace_path` crosses the wire as
`default_namespace`, a path like `namespace`, absent for the root.

There is no replace: a name already taken is an error, and changing a
view is a drop followed by a create, each authorized against what it
actually touches.

Querying a view stays SQL's job. There are no rows behind a view, so
there is no `open_view` returning a `Table`.

nodejs/lancedb/connection.ts

@@ -31,6 +31,7 @@ import type {
   ListNamespacesResponse,
   ListTablesResponse,
 } from "./native";
+import { ViewDescription, viewDescriptionFromNative } from "./view";
 export type {
   CreateNamespaceResponse,
   DescribeNamespaceResponse,
@@ -377,6 +378,45 @@ export abstract class Connection {
     namespacePath?: string[],
   ): Promise<Job>;
 
+  /**
+   * Create a view: a named query the database plans on every read.
+   *
+   * The query is planned once, at creation, so one that cannot be planned is
+   * rejected 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.
+   */
+  abstract createView(
+    name: string,
+    query: string,
+    namespacePath?: string[],
+  ): Promise<ViewDescription>;
+
+  /**
+   * What this database records about the view named `name`: its defining
+   * query and the schema that query resolved to.
+   */
+  abstract describeView(
+    name: string,
+    namespacePath?: string[],
+  ): Promise<ViewDescription>;
+
+  /**
+   * Drop the view named `name`.
+   *
+   * The tables it reads are untouched: a view holds no rows of its own.
+   */
+  abstract dropView(name: string, namespacePath?: string[]): Promise<void>;
+
+  /**
+   * The names of the views in one namespace.
+   *
+   * Names only; a definition comes from {@link describeView}.
+   */
+  abstract listViews(namespacePath?: string[]): Promise<string[]>;
+
   abstract openTable(
     name: string,
     namespacePath?: string[],
@@ -696,6 +736,33 @@ export class LocalConnection extends Connection {
     );
   }
 
+  async createView(
+    name: string,
+    query: string,
+    namespacePath?: string[],
+  ): Promise<ViewDescription> {
+    return viewDescriptionFromNative(
+      await this.inner.createView(name, query, namespacePath ?? []),
+    );
+  }
+
+  async describeView(
+    name: string,
+    namespacePath?: string[],
+  ): Promise<ViewDescription> {
+    return viewDescriptionFromNative(
+      await this.inner.describeView(name, namespacePath ?? []),
+    );
+  }
+
+  async dropView(name: string, namespacePath?: string[]): Promise<void> {
+    return this.inner.dropView(name, namespacePath ?? []);
+  }
+
+  async listViews(namespacePath?: string[]): Promise<string[]> {
+    return this.inner.listViews(namespacePath ?? []);
+  }
+
   async listTables(
     namespacePathOrOptions?: string[] | Partial<ListTablesOptions>,
     options?: Partial<ListTablesOptions>,

nodejs/lancedb/index.ts

@@ -26,6 +26,7 @@ export {
   MaterializedViewDefinition,
   MaterializedViewSelect,
 } from "./materialized_view";
+export { ViewDescription } from "./view";
 export { JsHeaderProvider as NativeJsHeaderProvider } from "./native.js";
 
 // OpenTelemetry metrics bridge. Only the high-level entry point is public; the

nodejs/lancedb/view.ts

@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright The LanceDB Authors
+
+import { Schema, tableFromIPC } from "apache-arrow";
+import { ViewDescription as NativeViewDescription } from "./native";
+
+/**
+ * What a database records about one view.
+ *
+ * A view holds no rows: it stores the statement that defines it and the
+ * schema that statement resolved to, so a reader sees its sources as they
+ * are at read time.
+ */
+export interface ViewDescription {
+  /** The view's name within its namespace. */
+  name: string;
+  /** The namespace holding the view; empty is the root namespace. */
+  namespacePath: string[];
+  /** The defining query, as the database stores it. */
+  query: string;
+  /** The database that unqualified table names in {@link query} resolve against. */
+  defaultDatabase: string;
+  /**
+   * The namespace path those unqualified names resolve against; empty is the
+   * root namespace.
+   *
+   * Recorded with the view because it outlives the session that declared it:
+   * a reader resolving the query against its own default namespace could read
+   * a different table than the view was defined over.
+   */
+  defaultNamespacePath: string[];
+  /** The schema the defining query resolved to when the view was created. */
+  schema: Schema;
+}
+
+/** Decode the schema the binding hands over as an Arrow IPC file. */
+export function viewDescriptionFromNative(
+  view: NativeViewDescription,
+): ViewDescription {
+  return {
+    name: view.name,
+    namespacePath: view.namespacePath,
+    query: view.query,
+    defaultDatabase: view.defaultDatabase,
+    defaultNamespacePath: view.defaultNamespacePath,
+    schema: tableFromIPC(view.schema).schema,
+  };
+}