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};
9
10use lance_namespace_reqwest_client::models::{
11    AlterTableAddColumnsRequest, AlterTableAddColumnsResponse, AlterTableAlterColumnsRequest,
12    AlterTableAlterColumnsResponse, AlterTableDropColumnsRequest, AlterTableDropColumnsResponse,
13    AlterTransactionRequest, AlterTransactionResponse, AnalyzeTableQueryPlanRequest,
14    BatchDeleteTableVersionsRequest, BatchDeleteTableVersionsResponse, CountTableRowsRequest,
15    CreateNamespaceRequest, CreateNamespaceResponse, CreateTableIndexRequest,
16    CreateTableIndexResponse, CreateTableRequest, CreateTableResponse,
17    CreateTableScalarIndexResponse, CreateTableTagRequest, CreateTableTagResponse,
18    CreateTableVersionRequest, CreateTableVersionResponse, DeclareTableRequest,
19    DeclareTableResponse, DeleteFromTableRequest, DeleteFromTableResponse, DeleteTableTagRequest,
20    DeleteTableTagResponse, DeregisterTableRequest, DeregisterTableResponse,
21    DescribeNamespaceRequest, DescribeNamespaceResponse, DescribeTableIndexStatsRequest,
22    DescribeTableIndexStatsResponse, DescribeTableRequest, DescribeTableResponse,
23    DescribeTableVersionRequest, DescribeTableVersionResponse, DescribeTransactionRequest,
24    DescribeTransactionResponse, DropNamespaceRequest, DropNamespaceResponse,
25    DropTableIndexRequest, DropTableIndexResponse, DropTableRequest, DropTableResponse,
26    ExplainTableQueryPlanRequest, GetTableStatsRequest, GetTableStatsResponse,
27    GetTableTagVersionRequest, GetTableTagVersionResponse, InsertIntoTableRequest,
28    InsertIntoTableResponse, ListNamespacesRequest, ListNamespacesResponse,
29    ListTableIndicesRequest, ListTableIndicesResponse, ListTableTagsRequest, ListTableTagsResponse,
30    ListTableVersionsRequest, ListTableVersionsResponse, ListTablesRequest, ListTablesResponse,
31    MergeInsertIntoTableRequest, MergeInsertIntoTableResponse, NamespaceExistsRequest,
32    QueryTableRequest, RegisterTableRequest, RegisterTableResponse, RenameTableRequest,
33    RenameTableResponse, RestoreTableRequest, RestoreTableResponse, TableExistsRequest,
34    UpdateTableRequest, UpdateTableResponse, UpdateTableSchemaMetadataRequest,
35    UpdateTableSchemaMetadataResponse, UpdateTableTagRequest, UpdateTableTagResponse,
36};
37
38/// Base trait for Lance Namespace implementations.
39///
40/// This trait defines the interface that all Lance namespace implementations
41/// must provide. Each method corresponds to a specific operation on namespaces
42/// or tables.
43///
44/// # Error Handling
45///
46/// All operations may return the following common errors (via [`crate::NamespaceError`]):
47///
48/// - [`crate::ErrorCode::Unsupported`] - Operation not supported by this backend
49/// - [`crate::ErrorCode::InvalidInput`] - Invalid request parameters
50/// - [`crate::ErrorCode::PermissionDenied`] - Insufficient permissions
51/// - [`crate::ErrorCode::Unauthenticated`] - Invalid credentials
52/// - [`crate::ErrorCode::ServiceUnavailable`] - Service temporarily unavailable
53/// - [`crate::ErrorCode::Internal`] - Unexpected internal error
54///
55/// See individual method documentation for operation-specific errors.
56#[async_trait]
57pub trait LanceNamespace: Send + Sync + std::fmt::Debug {
58    /// List namespaces.
59    ///
60    /// # Errors
61    ///
62    /// Returns [`crate::ErrorCode::NamespaceNotFound`] if the parent namespace does not exist.
63    async fn list_namespaces(
64        &self,
65        _request: ListNamespacesRequest,
66    ) -> Result<ListNamespacesResponse> {
67        Err(Error::not_supported("list_namespaces not implemented"))
68    }
69
70    /// Describe a namespace.
71    ///
72    /// # Errors
73    ///
74    /// Returns [`crate::ErrorCode::NamespaceNotFound`] if the namespace does not exist.
75    async fn describe_namespace(
76        &self,
77        _request: DescribeNamespaceRequest,
78    ) -> Result<DescribeNamespaceResponse> {
79        Err(Error::not_supported("describe_namespace not implemented"))
80    }
81
82    /// Create a new namespace.
83    ///
84    /// # Errors
85    ///
86    /// Returns [`crate::ErrorCode::NamespaceAlreadyExists`] if a namespace with the same name already exists.
87    async fn create_namespace(
88        &self,
89        _request: CreateNamespaceRequest,
90    ) -> Result<CreateNamespaceResponse> {
91        Err(Error::not_supported("create_namespace not implemented"))
92    }
93
94    /// Drop a namespace.
95    ///
96    /// # Errors
97    ///
98    /// - [`crate::ErrorCode::NamespaceNotFound`] if the namespace does not exist.
99    /// - [`crate::ErrorCode::NamespaceNotEmpty`] if the namespace contains tables or child namespaces.
100    async fn drop_namespace(
101        &self,
102        _request: DropNamespaceRequest,
103    ) -> Result<DropNamespaceResponse> {
104        Err(Error::not_supported("drop_namespace not implemented"))
105    }
106
107    /// Check if a namespace exists.
108    ///
109    /// # Errors
110    ///
111    /// Returns [`crate::ErrorCode::NamespaceNotFound`] if the namespace does not exist.
112    async fn namespace_exists(&self, _request: NamespaceExistsRequest) -> Result<()> {
113        Err(Error::not_supported("namespace_exists not implemented"))
114    }
115
116    /// List tables in a namespace.
117    async fn list_tables(&self, _request: ListTablesRequest) -> Result<ListTablesResponse> {
118        Err(Error::not_supported("list_tables not implemented"))
119    }
120
121    /// Describe a table.
122    async fn describe_table(
123        &self,
124        _request: DescribeTableRequest,
125    ) -> Result<DescribeTableResponse> {
126        Err(Error::not_supported("describe_table not implemented"))
127    }
128
129    /// Register a table.
130    async fn register_table(
131        &self,
132        _request: RegisterTableRequest,
133    ) -> Result<RegisterTableResponse> {
134        Err(Error::not_supported("register_table not implemented"))
135    }
136
137    /// Check if a table exists.
138    async fn table_exists(&self, _request: TableExistsRequest) -> Result<()> {
139        Err(Error::not_supported("table_exists not implemented"))
140    }
141
142    /// Drop a table.
143    async fn drop_table(&self, _request: DropTableRequest) -> Result<DropTableResponse> {
144        Err(Error::not_supported("drop_table not implemented"))
145    }
146
147    /// Deregister a table.
148    async fn deregister_table(
149        &self,
150        _request: DeregisterTableRequest,
151    ) -> Result<DeregisterTableResponse> {
152        Err(Error::not_supported("deregister_table not implemented"))
153    }
154
155    /// Count rows in a table.
156    async fn count_table_rows(&self, _request: CountTableRowsRequest) -> Result<i64> {
157        Err(Error::not_supported("count_table_rows not implemented"))
158    }
159
160    /// Create a new table with data from Arrow IPC stream.
161    async fn create_table(
162        &self,
163        _request: CreateTableRequest,
164        _request_data: Bytes,
165    ) -> Result<CreateTableResponse> {
166        Err(Error::not_supported("create_table not implemented"))
167    }
168
169    /// Declare a table (metadata only operation).
170    async fn declare_table(&self, _request: DeclareTableRequest) -> Result<DeclareTableResponse> {
171        Err(Error::not_supported("declare_table not implemented"))
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::not_supported("insert_into_table not implemented"))
181    }
182
183    /// Merge insert data into a table.
184    async fn merge_insert_into_table(
185        &self,
186        _request: MergeInsertIntoTableRequest,
187        _request_data: Bytes,
188    ) -> Result<MergeInsertIntoTableResponse> {
189        Err(Error::not_supported(
190            "merge_insert_into_table not implemented",
191        ))
192    }
193
194    /// Update a table.
195    async fn update_table(&self, _request: UpdateTableRequest) -> Result<UpdateTableResponse> {
196        Err(Error::not_supported("update_table not implemented"))
197    }
198
199    /// Delete from a table.
200    async fn delete_from_table(
201        &self,
202        _request: DeleteFromTableRequest,
203    ) -> Result<DeleteFromTableResponse> {
204        Err(Error::not_supported("delete_from_table not implemented"))
205    }
206
207    /// Query a table.
208    async fn query_table(&self, _request: QueryTableRequest) -> Result<Bytes> {
209        Err(Error::not_supported("query_table not implemented"))
210    }
211
212    /// Create a table index.
213    async fn create_table_index(
214        &self,
215        _request: CreateTableIndexRequest,
216    ) -> Result<CreateTableIndexResponse> {
217        Err(Error::not_supported("create_table_index not implemented"))
218    }
219
220    /// List table indices.
221    async fn list_table_indices(
222        &self,
223        _request: ListTableIndicesRequest,
224    ) -> Result<ListTableIndicesResponse> {
225        Err(Error::not_supported("list_table_indices not implemented"))
226    }
227
228    /// Describe table index statistics.
229    async fn describe_table_index_stats(
230        &self,
231        _request: DescribeTableIndexStatsRequest,
232    ) -> Result<DescribeTableIndexStatsResponse> {
233        Err(Error::not_supported(
234            "describe_table_index_stats not implemented",
235        ))
236    }
237
238    /// Describe a transaction.
239    async fn describe_transaction(
240        &self,
241        _request: DescribeTransactionRequest,
242    ) -> Result<DescribeTransactionResponse> {
243        Err(Error::not_supported("describe_transaction not implemented"))
244    }
245
246    /// Alter a transaction.
247    async fn alter_transaction(
248        &self,
249        _request: AlterTransactionRequest,
250    ) -> Result<AlterTransactionResponse> {
251        Err(Error::not_supported("alter_transaction not implemented"))
252    }
253
254    /// Create a scalar index on a table.
255    async fn create_table_scalar_index(
256        &self,
257        _request: CreateTableIndexRequest,
258    ) -> Result<CreateTableScalarIndexResponse> {
259        Err(Error::not_supported(
260            "create_table_scalar_index not implemented",
261        ))
262    }
263
264    /// Drop a table index.
265    async fn drop_table_index(
266        &self,
267        _request: DropTableIndexRequest,
268    ) -> Result<DropTableIndexResponse> {
269        Err(Error::not_supported("drop_table_index not implemented"))
270    }
271
272    /// List all tables across all namespaces.
273    async fn list_all_tables(&self, _request: ListTablesRequest) -> Result<ListTablesResponse> {
274        Err(Error::not_supported("list_all_tables not implemented"))
275    }
276
277    /// Restore a table to a specific version.
278    async fn restore_table(&self, _request: RestoreTableRequest) -> Result<RestoreTableResponse> {
279        Err(Error::not_supported("restore_table not implemented"))
280    }
281
282    /// Rename a table.
283    async fn rename_table(&self, _request: RenameTableRequest) -> Result<RenameTableResponse> {
284        Err(Error::not_supported("rename_table not implemented"))
285    }
286
287    /// List all versions of a table.
288    async fn list_table_versions(
289        &self,
290        _request: ListTableVersionsRequest,
291    ) -> Result<ListTableVersionsResponse> {
292        Err(Error::not_supported("list_table_versions not implemented"))
293    }
294
295    /// Create a new table version entry.
296    ///
297    /// This operation supports `put_if_not_exists` semantics, where the operation
298    /// fails if the version already exists. This is used to coordinate concurrent
299    /// writes to a table through an external manifest store.
300    ///
301    /// # Arguments
302    ///
303    /// * `request` - Contains the table identifier, version number, manifest path,
304    ///   and optional metadata like size and ETag.
305    ///
306    /// # Errors
307    ///
308    /// - Returns an error if the version already exists (conflict).
309    /// - Returns [`crate::ErrorCode::TableNotFound`] if the table does not exist.
310    async fn create_table_version(
311        &self,
312        _request: CreateTableVersionRequest,
313    ) -> Result<CreateTableVersionResponse> {
314        Err(Error::not_supported("create_table_version not implemented"))
315    }
316
317    /// Describe a specific table version.
318    ///
319    /// Returns metadata about a specific version of a table, including the
320    /// manifest path, size, ETag, and timestamp.
321    ///
322    /// # Arguments
323    ///
324    /// * `request` - Contains the table identifier and optionally the version
325    ///   number. If version is not specified, returns the latest version.
326    ///
327    /// # Errors
328    ///
329    /// - Returns [`crate::ErrorCode::TableNotFound`] if the table does not exist.
330    /// - Returns an error if the specified version does not exist.
331    async fn describe_table_version(
332        &self,
333        _request: DescribeTableVersionRequest,
334    ) -> Result<DescribeTableVersionResponse> {
335        Err(Error::not_supported(
336            "describe_table_version not implemented",
337        ))
338    }
339
340    /// Batch delete table versions.
341    ///
342    /// Deletes version records for a single table using `request.id` + `request.ranges`.
343    ///
344    /// # Arguments
345    ///
346    /// * `request` - Contains the table identifier and version ranges to delete.
347    ///
348    /// # Errors
349    ///
350    /// - Returns [`crate::ErrorCode::TableNotFound`] if the table does not exist.
351    async fn batch_delete_table_versions(
352        &self,
353        _request: BatchDeleteTableVersionsRequest,
354    ) -> Result<BatchDeleteTableVersionsResponse> {
355        Err(Error::not_supported(
356            "batch_delete_table_versions not implemented",
357        ))
358    }
359
360    /// Update table schema metadata.
361    async fn update_table_schema_metadata(
362        &self,
363        _request: UpdateTableSchemaMetadataRequest,
364    ) -> Result<UpdateTableSchemaMetadataResponse> {
365        Err(Error::not_supported(
366            "update_table_schema_metadata not implemented",
367        ))
368    }
369
370    /// Get table statistics.
371    async fn get_table_stats(
372        &self,
373        _request: GetTableStatsRequest,
374    ) -> Result<GetTableStatsResponse> {
375        Err(Error::not_supported("get_table_stats not implemented"))
376    }
377
378    /// Explain a table query plan.
379    async fn explain_table_query_plan(
380        &self,
381        _request: ExplainTableQueryPlanRequest,
382    ) -> Result<String> {
383        Err(Error::not_supported(
384            "explain_table_query_plan not implemented",
385        ))
386    }
387
388    /// Analyze a table query plan.
389    async fn analyze_table_query_plan(
390        &self,
391        _request: AnalyzeTableQueryPlanRequest,
392    ) -> Result<String> {
393        Err(Error::not_supported(
394            "analyze_table_query_plan not implemented",
395        ))
396    }
397
398    /// Add columns to a table.
399    async fn alter_table_add_columns(
400        &self,
401        _request: AlterTableAddColumnsRequest,
402    ) -> Result<AlterTableAddColumnsResponse> {
403        Err(Error::not_supported(
404            "alter_table_add_columns not implemented",
405        ))
406    }
407
408    /// Alter columns in a table.
409    async fn alter_table_alter_columns(
410        &self,
411        _request: AlterTableAlterColumnsRequest,
412    ) -> Result<AlterTableAlterColumnsResponse> {
413        Err(Error::not_supported(
414            "alter_table_alter_columns not implemented",
415        ))
416    }
417
418    /// Drop columns from a table.
419    async fn alter_table_drop_columns(
420        &self,
421        _request: AlterTableDropColumnsRequest,
422    ) -> Result<AlterTableDropColumnsResponse> {
423        Err(Error::not_supported(
424            "alter_table_drop_columns not implemented",
425        ))
426    }
427
428    /// List all tags for a table.
429    async fn list_table_tags(
430        &self,
431        _request: ListTableTagsRequest,
432    ) -> Result<ListTableTagsResponse> {
433        Err(Error::not_supported("list_table_tags not implemented"))
434    }
435
436    /// Get the version for a specific tag.
437    async fn get_table_tag_version(
438        &self,
439        _request: GetTableTagVersionRequest,
440    ) -> Result<GetTableTagVersionResponse> {
441        Err(Error::not_supported(
442            "get_table_tag_version not implemented",
443        ))
444    }
445
446    /// Create a tag for a table.
447    async fn create_table_tag(
448        &self,
449        _request: CreateTableTagRequest,
450    ) -> Result<CreateTableTagResponse> {
451        Err(Error::not_supported("create_table_tag not implemented"))
452    }
453
454    /// Delete a tag from a table.
455    async fn delete_table_tag(
456        &self,
457        _request: DeleteTableTagRequest,
458    ) -> Result<DeleteTableTagResponse> {
459        Err(Error::not_supported("delete_table_tag not implemented"))
460    }
461
462    /// Update a tag for a table.
463    async fn update_table_tag(
464        &self,
465        _request: UpdateTableTagRequest,
466    ) -> Result<UpdateTableTagResponse> {
467        Err(Error::not_supported("update_table_tag not implemented"))
468    }
469
470    /// Return a human-readable unique identifier for this namespace instance.
471    ///
472    /// This is used for equality comparison and hashing when the namespace is
473    /// used as part of a storage options provider. Two namespace instances with
474    /// the same ID are considered equal and will share cached resources.
475    ///
476    /// The ID should be human-readable for debugging and logging purposes.
477    /// For example:
478    /// - REST namespace: `"rest(endpoint=https://api.example.com)"`
479    /// - Directory namespace: `"dir(root=/path/to/data)"`
480    ///
481    /// Implementations should include all configuration that uniquely identifies
482    /// the namespace to provide semantic equality.
483    fn namespace_id(&self) -> String;
484}
lance_namespace/namespace.rs

lance_namespace/
namespace.rs
