lance_nd/
format.rs

1//! The format version of a lance-nd table.
2//!
3//! A table has the schema metadata key [`FORMAT_METADATA_KEY`] with the
4//! value [`FORMAT_VERSION`]. lance-nd reads and changes only tables with this
5//! key and value. A change of the table layout gets a new version.
6
7use std::collections::HashMap;
8
9use lance::Dataset;
10
11use crate::error::{Error, Result};
12use crate::store::{StorageOptions, open_dataset};
13
14/// The table schema metadata key of the format version.
15pub const FORMAT_METADATA_KEY: &str = "lance_nd:format";
16
17/// The format version that this release reads and writes.
18pub const FORMAT_VERSION: &str = "1";
19
20/// Open the lance-nd table at `uri`. Fails when no table is there, or when
21/// the table has another format version.
22pub async fn open(uri: &str) -> Result<Dataset> {
23    open_with(uri, &StorageOptions::new()).await
24}
25
26/// Open the lance-nd table at `uri` with Lance storage options, for example
27/// the credentials of an object store. See [`crate::StorageOptions`].
28#[tracing::instrument(skip_all, fields(uri = %uri), err)]
29pub async fn open_with(uri: &str, options: &StorageOptions) -> Result<Dataset> {
30    let dataset = open_dataset(uri, options).await?;
31    check_format(&dataset)?;
32    Ok(dataset)
33}
34
35/// Fails when `dataset` is not a lance-nd table of [`FORMAT_VERSION`].
36pub fn check_format(dataset: &Dataset) -> Result<()> {
37    match dataset.schema().metadata.get(FORMAT_METADATA_KEY) {
38        Some(version) if version == FORMAT_VERSION => Ok(()),
39        Some(version) => Err(Error::InvalidTable(format!(
40            "the table has lance-nd format {version}, this release reads format {FORMAT_VERSION}"
41        ))),
42        None => Err(Error::InvalidTable(format!(
43            "the table has no {FORMAT_METADATA_KEY} key: it is not a lance-nd table of format {FORMAT_VERSION}"
44        ))),
45    }
46}
47
48/// Add the format key to the metadata of a new table.
49pub(crate) fn add_format(metadata: &mut HashMap<String, String>) {
50    metadata.insert(FORMAT_METADATA_KEY.to_string(), FORMAT_VERSION.to_string());
51}
lance_nd/format.rs

lance_nd/
format.rs
