lance_namespace/
namespace.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright The Lance Authors
3
4//! Lance Namespace base interface and implementations.
5
6use async_trait::async_trait;
7use bytes::Bytes;
8use lance_core::{Error, Result};
9use snafu::Location;
10
11use lance_namespace_reqwest_client::models::{
12    AlterTransactionRequest, AlterTransactionResponse, CountTableRowsRequest,
13    CreateEmptyTableRequest, CreateEmptyTableResponse, CreateNamespaceRequest,
14    CreateNamespaceResponse, CreateTableIndexRequest, CreateTableIndexResponse, CreateTableRequest,
15    CreateTableResponse, DeleteFromTableRequest, DeleteFromTableResponse, DeregisterTableRequest,
16    DeregisterTableResponse, DescribeNamespaceRequest, DescribeNamespaceResponse,
17    DescribeTableIndexStatsRequest, DescribeTableIndexStatsResponse, DescribeTableRequest,
18    DescribeTableResponse, DescribeTransactionRequest, DescribeTransactionResponse,
19    DropNamespaceRequest, DropNamespaceResponse, DropTableRequest, DropTableResponse,
20    InsertIntoTableRequest, InsertIntoTableResponse, ListNamespacesRequest, ListNamespacesResponse,
21    ListTableIndicesRequest, ListTableIndicesResponse, ListTablesRequest, ListTablesResponse,
22    MergeInsertIntoTableRequest, MergeInsertIntoTableResponse, NamespaceExistsRequest,
23    QueryTableRequest, RegisterTableRequest, RegisterTableResponse, TableExistsRequest,
24    UpdateTableRequest, UpdateTableResponse,
25};
26
27/// Base trait for Lance Namespace implementations.
28///
29/// This trait defines the interface that all Lance namespace implementations
30/// must provide. Each method corresponds to a specific operation on namespaces
31/// or tables.
32#[async_trait]
33pub trait LanceNamespace: Send + Sync + std::fmt::Debug {
34    /// List namespaces.
35    async fn list_namespaces(
36        &self,
37        _request: ListNamespacesRequest,
38    ) -> Result<ListNamespacesResponse> {
39        Err(Error::NotSupported {
40            source: "list_namespaces not implemented".into(),
41            location: Location::new(file!(), line!(), column!()),
42        })
43    }
44
45    /// Describe a namespace.
46    async fn describe_namespace(
47        &self,
48        _request: DescribeNamespaceRequest,
49    ) -> Result<DescribeNamespaceResponse> {
50        Err(Error::NotSupported {
51            source: "describe_namespace not implemented".into(),
52            location: Location::new(file!(), line!(), column!()),
53        })
54    }
55
56    /// Create a new namespace.
57    async fn create_namespace(
58        &self,
59        _request: CreateNamespaceRequest,
60    ) -> Result<CreateNamespaceResponse> {
61        Err(Error::NotSupported {
62            source: "create_namespace not implemented".into(),
63            location: Location::new(file!(), line!(), column!()),
64        })
65    }
66
67    /// Drop a namespace.
68    async fn drop_namespace(
69        &self,
70        _request: DropNamespaceRequest,
71    ) -> Result<DropNamespaceResponse> {
72        Err(Error::NotSupported {
73            source: "drop_namespace not implemented".into(),
74            location: Location::new(file!(), line!(), column!()),
75        })
76    }
77
78    /// Check if a namespace exists.
79    async fn namespace_exists(&self, _request: NamespaceExistsRequest) -> Result<()> {
80        Err(Error::NotSupported {
81            source: "namespace_exists not implemented".into(),
82            location: Location::new(file!(), line!(), column!()),
83        })
84    }
85
86    /// List tables in a namespace.
87    async fn list_tables(&self, _request: ListTablesRequest) -> Result<ListTablesResponse> {
88        Err(Error::NotSupported {
89            source: "list_tables not implemented".into(),
90            location: Location::new(file!(), line!(), column!()),
91        })
92    }
93
94    /// Describe a table.
95    async fn describe_table(
96        &self,
97        _request: DescribeTableRequest,
98    ) -> Result<DescribeTableResponse> {
99        Err(Error::NotSupported {
100            source: "describe_table not implemented".into(),
101            location: Location::new(file!(), line!(), column!()),
102        })
103    }
104
105    /// Register a table.
106    async fn register_table(
107        &self,
108        _request: RegisterTableRequest,
109    ) -> Result<RegisterTableResponse> {
110        Err(Error::NotSupported {
111            source: "register_table not implemented".into(),
112            location: Location::new(file!(), line!(), column!()),
113        })
114    }
115
116    /// Check if a table exists.
117    async fn table_exists(&self, _request: TableExistsRequest) -> Result<()> {
118        Err(Error::NotSupported {
119            source: "table_exists not implemented".into(),
120            location: Location::new(file!(), line!(), column!()),
121        })
122    }
123
124    /// Drop a table.
125    async fn drop_table(&self, _request: DropTableRequest) -> Result<DropTableResponse> {
126        Err(Error::NotSupported {
127            source: "drop_table not implemented".into(),
128            location: Location::new(file!(), line!(), column!()),
129        })
130    }
131
132    /// Deregister a table.
133    async fn deregister_table(
134        &self,
135        _request: DeregisterTableRequest,
136    ) -> Result<DeregisterTableResponse> {
137        Err(Error::NotSupported {
138            source: "deregister_table not implemented".into(),
139            location: Location::new(file!(), line!(), column!()),
140        })
141    }
142
143    /// Count rows in a table.
144    async fn count_table_rows(&self, _request: CountTableRowsRequest) -> Result<i64> {
145        Err(Error::NotSupported {
146            source: "count_table_rows not implemented".into(),
147            location: Location::new(file!(), line!(), column!()),
148        })
149    }
150
151    /// Create a new table with data from Arrow IPC stream.
152    async fn create_table(
153        &self,
154        _request: CreateTableRequest,
155        _request_data: Bytes,
156    ) -> Result<CreateTableResponse> {
157        Err(Error::NotSupported {
158            source: "create_table not implemented".into(),
159            location: Location::new(file!(), line!(), column!()),
160        })
161    }
162
163    /// Create an empty table (metadata only operation).
164    async fn create_empty_table(
165        &self,
166        _request: CreateEmptyTableRequest,
167    ) -> Result<CreateEmptyTableResponse> {
168        Err(Error::NotSupported {
169            source: "create_empty_table not implemented".into(),
170            location: Location::new(file!(), line!(), column!()),
171        })
172    }
173
174    /// Insert data into a table.
175    async fn insert_into_table(
176        &self,
177        _request: InsertIntoTableRequest,
178        _request_data: Bytes,
179    ) -> Result<InsertIntoTableResponse> {
180        Err(Error::NotSupported {
181            source: "insert_into_table not implemented".into(),
182            location: Location::new(file!(), line!(), column!()),
183        })
184    }
185
186    /// Merge insert data into a table.
187    async fn merge_insert_into_table(
188        &self,
189        _request: MergeInsertIntoTableRequest,
190        _request_data: Bytes,
191    ) -> Result<MergeInsertIntoTableResponse> {
192        Err(Error::NotSupported {
193            source: "merge_insert_into_table not implemented".into(),
194            location: Location::new(file!(), line!(), column!()),
195        })
196    }
197
198    /// Update a table.
199    async fn update_table(&self, _request: UpdateTableRequest) -> Result<UpdateTableResponse> {
200        Err(Error::NotSupported {
201            source: "update_table not implemented".into(),
202            location: Location::new(file!(), line!(), column!()),
203        })
204    }
205
206    /// Delete from a table.
207    async fn delete_from_table(
208        &self,
209        _request: DeleteFromTableRequest,
210    ) -> Result<DeleteFromTableResponse> {
211        Err(Error::NotSupported {
212            source: "delete_from_table not implemented".into(),
213            location: Location::new(file!(), line!(), column!()),
214        })
215    }
216
217    /// Query a table.
218    async fn query_table(&self, _request: QueryTableRequest) -> Result<Bytes> {
219        Err(Error::NotSupported {
220            source: "query_table not implemented".into(),
221            location: Location::new(file!(), line!(), column!()),
222        })
223    }
224
225    /// Create a table index.
226    async fn create_table_index(
227        &self,
228        _request: CreateTableIndexRequest,
229    ) -> Result<CreateTableIndexResponse> {
230        Err(Error::NotSupported {
231            source: "create_table_index not implemented".into(),
232            location: Location::new(file!(), line!(), column!()),
233        })
234    }
235
236    /// List table indices.
237    async fn list_table_indices(
238        &self,
239        _request: ListTableIndicesRequest,
240    ) -> Result<ListTableIndicesResponse> {
241        Err(Error::NotSupported {
242            source: "list_table_indices not implemented".into(),
243            location: Location::new(file!(), line!(), column!()),
244        })
245    }
246
247    /// Describe table index statistics.
248    async fn describe_table_index_stats(
249        &self,
250        _request: DescribeTableIndexStatsRequest,
251    ) -> Result<DescribeTableIndexStatsResponse> {
252        Err(Error::NotSupported {
253            source: "describe_table_index_stats not implemented".into(),
254            location: Location::new(file!(), line!(), column!()),
255        })
256    }
257
258    /// Describe a transaction.
259    async fn describe_transaction(
260        &self,
261        _request: DescribeTransactionRequest,
262    ) -> Result<DescribeTransactionResponse> {
263        Err(Error::NotSupported {
264            source: "describe_transaction not implemented".into(),
265            location: Location::new(file!(), line!(), column!()),
266        })
267    }
268
269    /// Alter a transaction.
270    async fn alter_transaction(
271        &self,
272        _request: AlterTransactionRequest,
273    ) -> Result<AlterTransactionResponse> {
274        Err(Error::NotSupported {
275            source: "alter_transaction not implemented".into(),
276            location: Location::new(file!(), line!(), column!()),
277        })
278    }
279
280    /// Return a human-readable unique identifier for this namespace instance.
281    ///
282    /// This is used for equality comparison and hashing when the namespace is
283    /// used as part of a storage options provider. Two namespace instances with
284    /// the same ID are considered equal and will share cached resources.
285    ///
286    /// The ID should be human-readable for debugging and logging purposes.
287    /// For example:
288    /// - REST namespace: `"rest(endpoint=https://api.example.com)"`
289    /// - Directory namespace: `"dir(root=/path/to/data)"`
290    ///
291    /// Implementations should include all configuration that uniquely identifies
292    /// the namespace to provide semantic equality.
293    fn namespace_id(&self) -> String;
294}
lance_namespace/namespace.rs

lance_namespace/
namespace.rs
