Prollytree

https://docs.rs/prollytree
Admin
Prollytree is a hybrid data structure combining B-trees and Merkle trees for efficient data access...
Tokens:313,588
Snippets:1,942
Trust Score:9.1
Update:3 months ago
Show doc for...
Tokens:
Raw
### Initialize test git repository

Source: https://docs.rs/prollytree/latest/src/prollytree/git/operations.rs.html?search=std%3A%3Avec

Example test setup for initializing a temporary Git repository.

```rust
@test
    fn test_git_operations_creation() {
        let temp_dir = TempDir::new().unwrap();
        // Initialize git repository (regular, not bare)
        gix::init(temp_dir.path()).unwrap();
```

--------------------------------

### Initialize Versioned Stores

Source: https://docs.rs/prollytree/latest/prollytree/git/versioned_store/struct.StoreFactory.html?search=u32+-%3E+bool

Examples of creating different types of versioned stores using StoreFactory.

```rust
use prollytree::git::versioned_store::StoreFactory;

// In-memory (volatile, fastest) — great for testing or caching
let store = StoreFactory::memory::<32>("/tmp/my-repo/data")?;

// Git-backed (persistent, versioned) — production use
let store = StoreFactory::git::<32>("/tmp/my-repo/data")?;

// Thread-safe Git-backed — multi-threaded / async access
let store = StoreFactory::git_threadsafe::<32>("/tmp/my-repo/data")?;
```

--------------------------------

### Initialize ProllyNode with Builder

Source: https://docs.rs/prollytree/latest/src/prollytree/node.rs.html

Examples of initializing a ProllyNode using the builder pattern with specific keys, values, and chunking parameters.

```rust
let keys: Vec<Vec<u8>> = (1..=size).map(|i| vec![i]).collect();
let values = vec![value_for_all.clone(); keys.len()];

// Initialize the prolly tree with multiple key-value pairs using the builder
let node: ProllyNode<32> = ProllyNode::builder().keys(keys).values(values).build();

// Insert the node into storage
storage.insert_node(node.get_hash(), node.clone()).unwrap();

// Print chunk content
println!("{:?}", node.chunk_content());
```

```rust
let keys: Vec<Vec<u8>> = vec![vec![17], vec![30], vec![32]];
let values = vec![value_for_all.clone(); keys.len()];

// initialize the prolly tree with multiple key-value pairs using the builder
let node: ProllyNode<32> = ProllyNode::builder()
    .keys(keys)
    .values(values)
    .pattern(0b11)
    .min_chunk_size(2)
    .build();

// Insert the node into storage
storage.insert_node(node.get_hash(), node.clone()).unwrap();

// Print chunk content
println!("{:?}", node.chunk_content());
```

--------------------------------

### Initialize Git Repository for Testing

Source: https://docs.rs/prollytree/latest/src/prollytree/git/worktree.rs.html

Helper logic to create a base Git repository structure, including an initial commit and branch setup, required for worktree operations.

```rust
.args(["add", "."])
            .current_dir(repo_path)
            .output()
            .expect("Failed to add files");

        // Write tree from index
        let write_tree_output = std::process::Command::new("git")
            .args(["write-tree"])
            .current_dir(repo_path)
            .output()
            .expect("Failed to write tree");
        let tree_hash = String::from_utf8_lossy(&write_tree_output.stdout)
            .trim()
            .to_string();
        let tree_id =
            gix::ObjectId::from_hex(tree_hash.as_bytes()).expect("Failed to parse tree hash");

        // Create initial commit using gix (bypasses shell hooks like commit signing)
        let signature = gix::actor::Signature {
            name: "Test User".into(),
            email: "test@example.com".into(),
            time: gix::date::Time {
                seconds: 1700000000,
                offset: 0,
            },
        };

        let commit = gix::objs::Commit {
            tree: tree_id,
            parents: vec![].into(),
            author: signature.clone(),
            committer: signature,
            encoding: None,
            message: b"Initial commit"[..].into(),
            extra_headers: vec![],
        };

        let commit_id = repo.objects.write(&commit).expect("Failed to write commit");

        // Create refs/heads/main pointing to the commit
        let refs_dir = repo.path().join("refs").join("heads");
        std::fs::create_dir_all(&refs_dir).expect("Failed to create refs directory");
        std::fs::write(refs_dir.join("main"), commit_id.to_hex().to_string())
            .expect("Failed to write main branch ref");

        // Set HEAD to point to main
        let head_file = repo.path().join("HEAD");
        std::fs::write(head_file, "ref: refs/heads/main\n").expect("Failed to write HEAD");
    }
```

--------------------------------

### init

Source: https://docs.rs/prollytree/latest/prollytree/git/versioned_store/type.GitVersionedKvStore.html

Initializes a new versioned KV store with Git storage.

```APIDOC
## pub fn init<P: AsRef<Path>>(path: P) -> Result<Self, GitKvError>

### Description
Initializes a new versioned KV store with Git storage (default).

### Parameters
- **path** (P) - Required - The path to initialize the store.
```

--------------------------------

### Testing ProllyTree with InMemory Storage

Source: https://docs.rs/prollytree/latest/src/prollytree/tree.rs.html?search=std%3A%3Avec

Example setup for testing ProllyTree using an in-memory storage backend.

```rust
#[test]
    fn inmem_node_storage_test() {
        // 1. Create a custom tree config
        let config = TreeConfig {
            base: 131,
            modulus: 1_000_000_009,
            min_chunk_size: 4,
            max_chunk_size: 8 * 1024,
            pattern: 0b101,
            root_hash: None,
            key_schema: None,
            value_schema: None,
            encode_types: vec![],
        };

        // 2. Create and Wrap the Storage Backend
        let storage = InMemoryNodeStorage::<32>::default();

        // 3. Create the Prolly Tree
```

--------------------------------

### init

Source: https://docs.rs/prollytree/latest/prollytree/git/versioned_store/type.GitVersionedKvStore.html?search=

Initializes a new versioned KV store with Git storage.

```APIDOC
## pub fn init<P: AsRef<Path>>(path: P) -> Result<Self, GitKvError>

### Description
Initializes a new versioned KV store with Git storage (default).
```

--------------------------------

### Initialize and Open Versioned KV Store

Source: https://docs.rs/prollytree/latest/src/prollytree/git/versioned_store/backends.rs.html?search=std%3A%3Avec

Methods for setting up a new store with default configuration and opening an existing store from a file path.

```rust
// Create ProllyTree with default config
        let config: TreeConfig<N> = TreeConfig::default();
        let tree = ProllyTree::new(storage, config);

        let mut store = VersionedKvStore {
            tree,
            metadata: GitMetadataBackend::new(git_repo),
            staging_area: HashMap::new(),
            current_branch: "main".to_string(),
            storage_backend: StorageBackend::File,
            dataset_dir: Some(dataset_dir),
            config_filename: DEFAULT_TREE_CONFIG_FILENAME.to_string(),
        };

        // Create initial commit (which will save config to dataset_dir)
        store.commit("Initial commit")?;

        Ok(store)
    }
```

```rust
pub fn open<P: AsRef<Path>>(path: P) -> Result<Self, GitKvError> {
        let path = path.as_ref();
        let dataset_dir = path.to_path_buf();

        // Safety check: prevent opening at git root to avoid `git add -A .` staging all files
        if Self::is_in_git_root(path)? {
            return Err(GitKvError::GitObjectError(
                "Cannot open file store in git root directory. \
                Please use a subdirectory for your dataset, or the commit operation \
                may accidentally stage all files in the repository."
                    .to_string(),
            ));
        }

        // Check if the dataset directory exists
        if !dataset_dir.exists() {
            return Err(GitKvError::GitObjectError(
                "Dataset directory not found. Call init() first to create the store.".to_string(),
            ));
        }

        // Find the git repository
        let git_root = Self::find_git_root(path).ok_or_else(|| {
            GitKvError::GitObjectError(
                "Not inside a git repository. Please run from within a git repository.".to_string(),
            )
        })?;

        // Get prolly directory inside .git
        let prolly_dir = Self::get_prolly_dir(&git_root);

        // Open existing Git repository
        let git_repo = gix::open(&git_root).map_err(|e| GitKvError::GitOpenError(Box::new(e)))?;

        // Open FileNodeStorage inside .git/prolly/nodes/files/
        let file_storage_path = prolly_dir.join("nodes").join("files");

        // Check if the file storage directory exists - if not, the store hasn't been initialized
        if !file_storage_path.exists() {
            return Err(GitKvError::GitObjectError(
                "File store not initialized. Call init() first to create the store.".to_string(),
            ));
        }

        let storage = FileNodeStorage::<N>::new(file_storage_path.clone()).map_err(|e| {
            GitKvError::GitObjectError(format!("Failed to create file storage: {e}"))
        })?;

        // Load tree configuration from dataset directory (not from storage)
        // Config file must exist for open() - use init() to create new stores
        let config_path = dataset_dir.join("prolly_config_tree_config");
        if !config_path.exists() {
            return Err(GitKvError::GitObjectError(
                "Config file not found. The store may not be initialized. \
                Call init() to create a new store."
                    .to_string(),
            ));
        }
        let config_data = std::fs::read_to_string(&config_path)
            .map_err(|e| GitKvError::GitObjectError(format!("Failed to read config file: {e}")))?;
        let config: TreeConfig<N> = serde_json::from_str(&config_data)
            .map_err(|e| GitKvError::GitObjectError(format!("Failed to parse config file: {e}")))?;

        // Try to load existing tree from storage using the config's root hash
        let tree =
            if let Some(existing_tree) = ProllyTree::load_from_storage(storage, config.clone()) {
                existing_tree
            } else {
                // Create new storage instance since the original was consumed
                let new_storage = FileNodeStorage::<N>::new(file_storage_path).map_err(|e| {
                    GitKvError::GitObjectError(format!("Failed to create file storage: {e}"))
                })?;
                ProllyTree::new(new_storage, config)
            };

        // Get current branch
        let current_branch = git_repo
            .head_ref()
            .map_err(|e| GitKvError::GitObjectError(format!("Failed to get head ref: {e}")))?
    }
```

--------------------------------

### Test Arrow Encoding Setup

Source: https://docs.rs/prollytree/latest/src/prollytree/encoding.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Partial unit test setup for Arrow encoding with complex data structures.

```rust
#[test]
    fn test_encode_arrow() {
        let mut node: ProllyNode<1024> = ProllyNode::default();

        let keys = [
            ComplexKey {
                id: 1,
                uuid: "guid-key1".to_string(),
            },
            ComplexKey {
                id: 2,
                uuid: "guid-key2".to_string(),
            },
        ];
        let values = [
            ComplexValue {
                name: "name1".to_string(),
                age: 30,
                description: "value1".to_string(),
                active: true,
                balance: 100.0,
            },
            ComplexValue {
                name: "name2".to_string(),
                age: 55,
                description: "value2".to_string(),
                active: false,
                balance: -50.0,
            },
        ];

        node.keys = keys
            .iter()
            .map(|k| serde_json::to_vec(k).unwrap())
```

--------------------------------

### get

Source: https://docs.rs/prollytree/latest/prollytree/git/versioned_store/struct.VersionedKvStore.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Retrieves a value by key.

```APIDOC
## pub fn get(&self, key: &[u8]) -> Option<Vec<u8>>

### Description
Get a value by key (checks staging area first, then committed data).
```

--------------------------------

### log

Source: https://docs.rs/prollytree/latest/prollytree/git/versioned_store/namespaced/type.GitNamespacedKvStore.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Get commit history.

```APIDOC
## pub fn log(&self) -> Result<Vec<CommitInfo>, GitKvError>

### Description
Get commit history.
```

--------------------------------

### current_branch

Source: https://docs.rs/prollytree/latest/prollytree/git/versioned_store/namespaced/type.GitNamespacedKvStore.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Get current branch name.

```APIDOC
## pub fn current_branch(&self) -> &str

### Description
Get current branch name.
```

--------------------------------

### init<P: AsRef<Path>>(path: P) -> Result<Self, GitKvError>

Source: https://docs.rs/prollytree/latest/prollytree/git/versioned_store/type.FileVersionedKvStore.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Initializes a new versioned KV store with File storage at the specified path.

```APIDOC
## init

### Description
Initializes a new versioned KV store with File storage. Nodes are stored in .git/prolly/nodes/files/ and configuration is stored in the dataset directory.

### Parameters
- **path** (P: AsRef<Path>) - Required - The filesystem path where the store will be initialized.
```

--------------------------------

### open

Source: https://docs.rs/prollytree/latest/prollytree/git/versioned_store/type.GitVersionedKvStore.html

Opens an existing versioned KV store with Git storage.

```APIDOC
## pub fn open<P: AsRef<Path>>(path: P) -> Result<Self, GitKvError>

### Description
Opens an existing versioned KV store with Git storage (default).

### Parameters
- **path** (P) - Required - The path to the existing store.
```

--------------------------------

### get

Source: https://docs.rs/prollytree/latest/prollytree/git/versioned_store/namespaced/type.InMemoryNamespacedKvStore.html?search=

Retrieve a value by key from the default namespace.

```APIDOC
## pub fn get(&mut self, key: &[u8]) -> Option<Vec<u8>>

### Description
Get a value by key from the default namespace.
```

--------------------------------

### open

Source: https://docs.rs/prollytree/latest/prollytree/git/versioned_store/type.GitVersionedKvStore.html?search=

Opens an existing versioned KV store with Git storage.

```APIDOC
## pub fn open<P: AsRef<Path>>(path: P) -> Result<Self, GitKvError>

### Description
Open an existing versioned KV store with Git storage (default).
```

--------------------------------

### get_namespace_root_hash

Source: https://docs.rs/prollytree/latest/prollytree/git/versioned_store/namespaced/type.GitNamespacedKvStore.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Get the root hash for a namespace (O(1) lookup).

```APIDOC
## pub fn get_namespace_root_hash(&self, prefix: &str) -> Option<ValueDigest<N>>

### Description
Get the root hash for a namespace (O(1) lookup).
```

--------------------------------

### Initialize Git Repository for Testing

Source: https://docs.rs/prollytree/latest/src/prollytree/git/worktree.rs.html?search=std%3A%3Avec

This snippet demonstrates how to programmatically initialize a Git repository, write a tree, create an initial commit, and set up the main branch reference.

```rust
        .args(["add", "."])
            .current_dir(repo_path)
            .output()
            .expect("Failed to add files");

        // Write tree from index
        let write_tree_output = std::process::Command::new("git")
            .args(["write-tree"])
            .current_dir(repo_path)
            .output()
            .expect("Failed to write tree");
        let tree_hash = String::from_utf8_lossy(&write_tree_output.stdout)
            .trim()
            .to_string();
        let tree_id =
            gix::ObjectId::from_hex(tree_hash.as_bytes()).expect("Failed to parse tree hash");

        // Create initial commit using gix (bypasses shell hooks like commit signing)
        let signature = gix::actor::Signature {
            name: "Test User".into(),
            email: "test@example.com".into(),
            time: gix::date::Time {
                seconds: 1700000000,
                offset: 0,
            },
        };

        let commit = gix::objs::Commit {
            tree: tree_id,
            parents: vec![].into(),
            author: signature.clone(),
            committer: signature,
            encoding: None,
            message: b"Initial commit"[..].into(),
            extra_headers: vec![],
        };

        let commit_id = repo.objects.write(&commit).expect("Failed to write commit");

        // Create refs/heads/main pointing to the commit
        let refs_dir = repo.path().join("refs").join("heads");
        std::fs::create_dir_all(&refs_dir).expect("Failed to create refs directory");
        std::fs::write(refs_dir.join("main"), commit_id.to_hex().to_string())
            .expect("Failed to write main branch ref");

        // Set HEAD to point to main
        let head_file = repo.path().join("HEAD");
        std::fs::write(head_file, "ref: refs/heads/main\n").expect("Failed to write HEAD");
    }
```

--------------------------------

### Get commit history

Source: https://docs.rs/prollytree/latest/src/prollytree/git/versioned_store/core.rs.html?search=std%3A%3Avec

Retrieves the commit history for the current branch.

```rust
    /// Get commit history
    pub fn log(&self) -> Result<Vec<CommitInfo>, GitKvError> {
        self.metadata.walk_history(100)
    }
```

--------------------------------

### Initialize GitVersionedKvStore and GitOperations

Source: https://docs.rs/prollytree/latest/src/prollytree/git/operations.rs.html?search=std%3A%3Avec

Initializes a Git-backed key-value store within a temporary directory and wraps it in GitOperations.

```rust
// Create subdirectory for dataset
let dataset_dir = temp_dir.path().join("dataset");
std::fs::create_dir_all(&dataset_dir).unwrap();
let store = GitVersionedKvStore::<32>::init(&dataset_dir).unwrap();
let _ops = GitOperations::new(store);
```

--------------------------------

### namespace

Source: https://docs.rs/prollytree/latest/prollytree/git/versioned_store/namespaced/type.InMemoryNamespacedKvStore.html?search=

Get a mutable handle to a namespace, creating it lazily if it does not exist.

```APIDOC
## pub fn namespace(&mut self, prefix: &str) -> NamespaceHandle<'_, N, S, M>

### Description
Get a mutable handle to a namespace. Creates the namespace lazily if it does not yet exist.
```

--------------------------------

### Initialize VersionedKvStore

Source: https://docs.rs/prollytree/latest/src/prollytree/git/versioned_store/backends.rs.html?search=

Initializes the store with Git metadata and loads the staging area.

```rust
        let mut store = VersionedKvStore {
            tree,
            metadata: GitMetadataBackend::new(git_repo),
            staging_area: HashMap::new(),
            current_branch,
            storage_backend: StorageBackend::Git,
            dataset_dir: Some(dataset_dir),
            config_filename: config_filename.to_string(),
        };

        store.load_staging_area()?;
```

--------------------------------

### get

Source: https://docs.rs/prollytree/latest/prollytree/git/versioned_store/type.GitVersionedKvStore.html?search=std%3A%3Avec

Retrieves a value by key, checking the staging area before committed data.

```APIDOC
## pub fn get(&self, key: &[u8]) -> Option<Vec<u8>>

### Description
Retrieves the value associated with the provided key. The method checks the staging area first, then falls back to committed data.
```

--------------------------------

### Initialize a new Versioned KV Store

Source: https://docs.rs/prollytree/latest/src/prollytree/git/versioned_store/backends.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Initializes a new store by setting up the Git repository, storage backend, and initial configuration.

```rust
let default_config_path = dataset_dir.join(DEFAULT_TREE_CONFIG_FILENAME);
        let mappings_path = dataset_dir.join("prolly_hash_mappings");

        if config_path.exists() || default_config_path.exists() || mappings_path.exists() {
            return Self::open_with_config_filename(path, config_filename);
        }

        let git_repo = gix::open(&git_root).map_err(|e| GitKvError::GitOpenError(Box::new(e)))?;
        let storage = GitNodeStorage::new(git_repo.clone(), dataset_dir.clone())?;
        let config: TreeConfig<N> = TreeConfig::default();
        let tree = ProllyTree::new(storage, config);

        let mut store = VersionedKvStore {
            tree,
            metadata: GitMetadataBackend::new(git_repo),
            staging_area: HashMap::new(),
            current_branch: "main".to_string(),
            storage_backend: StorageBackend::Git,
            dataset_dir: Some(dataset_dir),
            config_filename: config_filename.to_string(),
        };

        let _ = store.tree.save_config();
        store.commit("Initial commit")?;

        Ok(store)
```

--------------------------------

### Initialize Merge Trees Test

Source: https://docs.rs/prollytree/latest/src/prollytree/tree.rs.html

Initializes the setup for testing tree merges with conflicts.

```rust
#[test]
    fn test_merge_trees_with_conflicts() {
        let config = TreeConfig::default();
        let mut storage = InMemoryNodeStorage::<32>::default();

        // Create base tree
        let mut base_tree = ProllyTree::new(storage.clone(), config.clone());
```

--------------------------------

### get(&self, key: &[u8]) -> Option<Vec<u8>>

Source: https://docs.rs/prollytree/latest/prollytree/git/versioned_store/type.FileVersionedKvStore.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Retrieves a value by key from the store.

```APIDOC
## get

### Description
Retrieves a value by key, checking the staging area first, then the committed data.

### Parameters
- **key** (&[u8]) - Required - The key to look up.
```

--------------------------------

### Initialize and Open NamespacedKvStore

Source: https://docs.rs/prollytree/latest/src/prollytree/git/versioned_store/namespaced.rs.html?search=std%3A%3Avec

Methods for initializing a new store or opening an existing one from a file path, handling different format versions.

```rust
        let default_tree = ProllyTree::new(store.inner.tree.storage.clone(), TreeConfig::default());
        store
            .namespaces
            .insert(DEFAULT_NAMESPACE.to_string(), default_tree);

        store.commit("Initial namespaced store")?;
        Ok(store)
    }

    /// Open an existing namespaced store with file-based storage.
    pub fn open<P: AsRef<Path>>(path: P) -> Result<Self, GitKvError> {
        let inner = VersionedKvStore::<N, FileNodeStorage<N>>::open(&path)?;

        let dataset_dir = inner
            .dataset_dir
            .as_ref()
            .ok_or_else(|| GitKvError::GitObjectError("Dataset directory not set".into()))?;
        let format_version = Self::detect_format_version(dataset_dir);

        let mut store = NamespacedKvStore {
            inner,
            registry: HashMap::new(),
            namespaces: HashMap::new(),
            namespace_staging: HashMap::new(),
            default_namespace: DEFAULT_NAMESPACE.to_string(),
            dirty_namespaces: HashSet::new(),
            format_version: format_version.clone(),
            #[cfg(feature = "proximity")]
            proximity_indexes: HashMap::new(),
            #[cfg(feature = "proximity")]
            dirty_proximity_indexes: HashSet::new(),
            #[cfg(feature = "proximity")]
            text_embedders: HashMap::new(),
            #[cfg(feature = "proximity")]
            cascade_lists: HashMap::new(),
            #[cfg(feature = "proximity")]
            text_transformers: HashMap::new(),
            #[cfg(feature = "proximity")]
            text_chunkers: HashMap::new(),
            externalize_threshold: None,
        };

        match format_version {
            StoreFormatVersion::V2 => {
                store.load_namespace_registry()?;
            }
            StoreFormatVersion::V1 => {
                let default_tree =
                    ProllyTree::new(store.inner.tree.storage.clone(), TreeConfig::default());
                store
                    .namespaces
                    .insert(DEFAULT_NAMESPACE.to_string(), default_tree);
            }
        }

        Ok(store)
    }
```

--------------------------------

### Test Basic ProllyStorage Operations

Source: https://docs.rs/prollytree/latest/src/prollytree/sql.rs.html

Demonstrates initializing a git-backed storage, defining a schema, and performing CRUD operations using GlueSQL types.

```rust
#[tokio::test]
async fn test_basic_operations() {
    let temp_dir = TempDir::new().unwrap();

    // Initialize git repository in temp directory
    std::process::Command::new("git")
        .arg("init")
        .current_dir(temp_dir.path())
        .output()
        .expect("Failed to initialize git repository");

    // Create a subdirectory for the dataset
    let dataset_path = temp_dir.path().join("dataset");
    std::fs::create_dir(&dataset_path).unwrap();

    let mut storage = ProllyStorage::<32>::init(&dataset_path).unwrap();

    // Create a simple schema
    let schema = Schema {
        table_name: "users".to_string(),
        column_defs: Some(vec![
            ColumnDef {
                name: "id".to_string(),
                data_type: DataType::Int,
                nullable: false,
                default: None,
                unique: None,
                comment: None,
            },
            ColumnDef {
                name: "name".to_string(),
                data_type: DataType::Text,
                nullable: false,
                default: None,
                unique: None,
                comment: None,
            },
        ]),
        indexes: vec![],
        engine: None,
        foreign_keys: vec![],
        comment: None,
    };

    // Insert schema
    storage.insert_schema(&schema).await.unwrap();

    // Verify schema
    let fetched = storage.fetch_schema("users").await.unwrap();
    assert!(fetched.is_some());

    // Insert some data
    let row = DataRow::Vec(vec![Value::I64(1), Value::Str("Alice".to_string())]);
    let key = Key::I64(1);
    storage
        .insert_data("users", vec![(key.clone(), row.clone())])
        .await
        .unwrap();

    // Fetch data
    let fetched_row = storage.fetch_data("users", &key).await.unwrap();
    assert!(fetched_row.is_some());

    // Scan data
    use futures::StreamExt;
    let mut iter = storage.scan_data("users").await.unwrap();
    let first = iter.next().await.unwrap().unwrap();
    assert_eq!(first.0, key);
}
```

--------------------------------

### get

Source: https://docs.rs/prollytree/latest/prollytree/git/versioned_store/namespaced/struct.NamespaceHandle.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Retrieves a value by key within the namespace, checking both the staging area and the committed tree.

```APIDOC
## pub fn get(&self, key: &[u8]) -> Option<Vec<u8>>

### Description
Retrieves a value associated with the provided key within the current namespace. It checks the staging area first, followed by the committed tree.

### Parameters
- **key** (&[u8]) - Required - The key to look up.
```

--------------------------------

### Batch Insertion and Deletion

Source: https://docs.rs/prollytree/latest/src/prollytree/tree.rs.html

Examples of performing bulk operations on the ProllyTree using insert_batch and delete_batch.

```rust
#[test]
fn test_insert_batch_and_find() {
    let storage = InMemoryNodeStorage::<32>::default();

    let mut tree = ProllyTree::new(storage, TreeConfig::default());

    let keys = vec![b"key1".to_vec(), b"key2".to_vec(), b"key3".to_vec()];
    let values = vec![b"value1".to_vec(), b"value2".to_vec(), b"value3".to_vec()];

    tree.insert_batch(&keys, &values);

    assert!(tree.find(b"key1").is_some());
    assert!(tree.find(b"key2").is_some());
    assert!(tree.find(b"key3").is_some());
    assert!(tree.find(b"key4").is_none());
}
```

```rust
#[test]
fn test_delete_batch() {
    let storage = InMemoryNodeStorage::<32>::default();
    let mut tree = ProllyTree::new(storage, TreeConfig::default());

    let keys = vec![b"key1".to_vec(), b"key2".to_vec(), b"key3".to_vec()];
    let values = vec![b"value1".to_vec(), b"value2".to_vec(), b"value3".to_vec()];

    // Insert keys and values
    tree.insert_batch(&keys, &values);

    // Verify insertion
    assert!(tree.find(b"key1").is_some());
    assert!(tree.find(b"key2").is_some());
    assert!(tree.find(b"key3").is_some());

    // Delete keys in batch
    tree.delete_batch(&keys);

    // Verify deletion
    assert!(tree.find(b"key1").is_none());
    assert!(tree.find(b"key2").is_none());
    assert!(tree.find(b"key3").is_none());
}
```

--------------------------------

### init

Source: https://docs.rs/prollytree/latest/prollytree/git/versioned_store/type.InMemoryVersionedKvStore.html

Initializes a new versioned KV store with InMemory storage.

```APIDOC
## pub fn init<P: AsRef<Path>>(path: P) -> Result<Self, GitKvError>

### Description
Initialize a new versioned KV store with InMemory storage.
```

--------------------------------

### Single and Batch Deletion

Source: https://docs.rs/prollytree/latest/src/prollytree/tree.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Examples of removing individual keys or entire batches of keys from the tree.

```rust
#[test]
fn test_delete() {
    let storage = InMemoryNodeStorage::<32>::default();
    let mut tree = ProllyTree::new(storage, TreeConfig::default());

    tree.insert(b"key1".to_vec(), b"value1".to_vec());
    tree.insert(b"key2".to_vec(), b"value2".to_vec());

    assert!(tree.delete(b"key1"));
    assert!(tree.find(b"key1").is_none());
    assert!(tree.find(b"key2").is_some());
}
```

```rust
#[test]
fn test_delete_batch() {
    let storage = InMemoryNodeStorage::<32>::default();
    let mut tree = ProllyTree::new(storage, TreeConfig::default());

    let keys = vec![b"key1".to_vec(), b"key2".to_vec(), b"key3".to_vec()];
    let values = vec![b"value1".to_vec(), b"value2".to_vec(), b"value3".to_vec()];

    // Insert keys and values
    tree.insert_batch(&keys, &values);

    // Verify insertion
    assert!(tree.find(b"key1").is_some());
    assert!(tree.find(b"key2").is_some());
    assert!(tree.find(b"key3").is_some());

    // Delete keys in batch
    tree.delete_batch(&keys);

    // Verify deletion
    assert!(tree.find(b"key1").is_none());
    assert!(tree.find(b"key2").is_none());
    assert!(tree.find(b"key3").is_none());
}
```

--------------------------------

### init

Source: https://docs.rs/prollytree/latest/prollytree/git/versioned_store/type.ThreadSafeGitVersionedKvStore.html

Initializes a new thread-safe git-backed versioned key-value store at the specified path.

```APIDOC
## pub fn init<P: AsRef<Path>>(path: P) -> Result<Self, GitKvError>

### Description
Initializes a new thread-safe git-backed versioned key-value store at the provided file system path.

### Parameters
- **path** (P: AsRef<Path>) - Required - The file system path where the store will be initialized.
```

--------------------------------

### Initialization and Lifecycle

Source: https://docs.rs/prollytree/latest/prollytree/git/versioned_store/namespaced/type.ThreadSafeGitNamespacedKvStore.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Methods for initializing, opening, and managing the lifecycle of the Git-backed store.

```APIDOC
## init<P: AsRef<Path>>(path: P) -> Result<Self, GitKvError>
Initialize a new thread-safe namespaced store with Git storage.

## open<P: AsRef<Path>>(path: P) -> Result<Self, GitKvError>
Open an existing thread-safe namespaced store with Git storage.
```

--------------------------------

### init

Source: https://docs.rs/prollytree/latest/prollytree/git/versioned_store/namespaced/type.InMemoryNamespacedKvStore.html?search=

Initialize a new namespaced store with in-memory storage.

```APIDOC
## pub fn init<P: AsRef<Path>>(path: P) -> Result<Self, GitKvError>

### Description
Initialize a new namespaced store with in-memory storage.
```

--------------------------------

### Initialize TakeSourceResolver test

Source: https://docs.rs/prollytree/latest/src/prollytree/tree.rs.html?search=std%3A%3Avec

Setup for testing the TakeSourceResolver, which prioritizes source tree values during a merge conflict.

```rust
use crate::diff::TakeSourceResolver;

let config = TreeConfig::default();
let mut storage = InMemoryNodeStorage::<32>::default();

// Create base tree
let mut base_tree = ProllyTree::new(storage.clone(), config.clone());
```

--------------------------------

### Initialization

Source: https://docs.rs/prollytree/latest/prollytree/git/versioned_store/type.ThreadSafeInMemoryVersionedKvStore.html?search=std%3A%3Avec

Methods to initialize or open a versioned key-value store.

```APIDOC
## init<P: AsRef<Path>>(path: P) -> Result<Self, GitKvError>
Initialize a new thread-safe in-memory versioned key-value store.

## open<P: AsRef<Path>>(path: P) -> Result<Self, GitKvError>
Open an existing thread-safe in-memory versioned key-value store.
```

--------------------------------

### Merge ProllyTree States

Source: https://docs.rs/prollytree/latest/src/prollytree/tree.rs.html?search=std%3A%3Avec

Demonstrates the setup for merging tree states by persisting a base tree to storage.

```rust
#[test]
    fn test_merge_simple() {
        let config = TreeConfig::default();
        let mut storage = InMemoryNodeStorage::<32>::default();

        // Create base tree and persist it
        let mut base_tree = ProllyTree::new(storage.clone(), config.clone());
        base_tree.insert(b"key1".to_vec(), b"value1".to_vec());
        let base_root = base_tree.get_root_hash().unwrap();
        storage
            .insert_node(base_root.clone(), base_tree.root.clone())
            .unwrap();

        // Create source tree - same as base
        let mut source_tree = ProllyTree::new(storage.clone(), config.clone());
        source_tree.insert(b"key1".to_vec(), b"value1".to_vec());
```

--------------------------------

### Arrow Encoding Test Setup

Source: https://docs.rs/prollytree/latest/src/prollytree/encoding.rs.html

Initializes a ProllyNode with complex keys and values for Arrow encoding testing.

```rust
#[test]
    fn test_encode_arrow() {
        let mut node: ProllyNode<1024> = ProllyNode::default();

        let keys = [
            ComplexKey {
                id: 1,
                uuid: "guid-key1".to_string(),
            },
            ComplexKey {
                id: 2,
                uuid: "guid-key2".to_string(),
            },
        ];
        let values = [
            ComplexValue {
                name: "name1".to_string(),
                age: 30,
                description: "value1".to_string(),
                active: true,
                balance: 100.0,
            },
            ComplexValue {
                name: "name2".to_string(),
                age: 55,
                description: "value2".to_string(),
                active: false,
                balance: -50.0,
            },
        ];

        node.keys = keys
            .iter()
            .map(|k| serde_json::to_vec(k).unwrap())
            .collect();
```

--------------------------------

### Test ProllyTree Proof Visualization

Source: https://docs.rs/prollytree/latest/src/prollytree/node.rs.html

Demonstrates initializing a ProllyTree with custom configuration and verifying the proof output for a specific key.

```rust
#[test]
    fn test_print_tree_with_proof() {
        use crate::config::TreeConfig;
        use crate::tree::{ProllyTree, Tree};

        // Test the new print_tree_with_proof functionality using ProllyTree
        let storage = InMemoryNodeStorage::<32>::default();
        let config = TreeConfig {
            base: 131,
            modulus: 1_000_000_009,
            min_chunk_size: 2,
            max_chunk_size: 8,
            pattern: 0b11,
            root_hash: None,
            key_schema: None,
            value_schema: None,
            encode_types: vec![],
        };

        let mut tree = ProllyTree::new(storage, config);

        // Insert some test data
        for i in 0..10 {
            tree.insert(vec![i], vec![i * 10]);
        }

        // Test proof visualization for an existing key
        let test_key = vec![5];

        println!("Testing print_proof for key {:?}:", test_key);
        let is_valid = tree.print_proof(&test_key);

        // The proof should be valid for an existing key
        assert!(is_valid, "Proof should be valid for existing key");
    }
```

--------------------------------

### Initialize GitVersionedKvStore

Source: https://docs.rs/prollytree/latest/src/prollytree/git/operations.rs.html?search=

Sets up a versioned key-value store within a temporary directory for Git operations.

```rust
        // Create subdirectory for dataset
        let dataset_dir = temp_dir.path().join("dataset");
        std::fs::create_dir_all(&dataset_dir).unwrap();
        let store = GitVersionedKvStore::<32>::init(&dataset_dir).unwrap();
        let _ops = GitOperations::new(store);
    }
```

--------------------------------

### Get current branch of a worktree

Source: https://docs.rs/prollytree/latest/src/prollytree/git/worktree.rs.html

Retrieves the current branch name or commit hash for a given worktree path.

```rust
fn get_current_branch(&self, worktree_path: &Path) -> Result<String, GitKvError> {
    let head_file = if worktree_path == self.main_repo_path {
        self.git_dir.join("HEAD")
    } else {
        // For linked worktrees, find the HEAD in .git/worktrees/<name>/HEAD
        let worktree_name = self.find_worktree_name(worktree_path)?;
        self.git_dir
            .join("worktrees")
            .join(&worktree_name)
            .join("HEAD")
    };

    let head_content = fs::read_to_string(&head_file).map_err(GitKvError::IoError)?;

    // Parse the HEAD content (e.g., "ref: refs/heads/main")
    if head_content.starts_with("ref: refs/heads/") {
        Ok(head_content
            .trim()
            .strip_prefix("ref: refs/heads/")
            .unwrap_or("main")
            .to_string())
    } else {
        // Detached HEAD state - return the commit hash
        Ok(head_content.trim().to_string())
    }
}
```

--------------------------------

### get(key: &[u8])

Source: https://docs.rs/prollytree/latest/prollytree/git/versioned_store/type.InMemoryVersionedKvStore.html?search=std%3A%3Avec

Retrieves a value associated with the given key, checking the staging area before committed data.

```APIDOC
### pub fn get(&self, key: &[u8]) -> Option<Vec<u8>>

Retrieves the value for a specific key. It checks the staging area first, then the committed data.
```

--------------------------------

### init

Source: https://docs.rs/prollytree/latest/prollytree/git/versioned_store/struct.ThreadSafeVersionedKvStore.html

Initializes a new thread-safe versioned key-value store at the specified path.

```APIDOC
pub fn init<P: AsRef<Path>>(path: P) -> Result<Self, GitKvError>
```

--------------------------------

### Initialization Methods

Source: https://docs.rs/prollytree/latest/prollytree/git/versioned_store/type.ThreadSafeFileVersionedKvStore.html?search=std%3A%3Avec

Methods to initialize or open a new thread-safe file-based versioned key-value store.

```APIDOC
## pub fn init<P: AsRef<Path>>(path: P) -> Result<Self, GitKvError>

### Description
Initialize a new thread-safe file-based versioned key-value store at the specified path.

## pub fn open<P: AsRef<Path>>(path: P) -> Result<Self, GitKvError>

### Description
Open an existing thread-safe file-based versioned key-value store from the specified path.
```

--------------------------------

### Walk Commit History

Source: https://docs.rs/prollytree/latest/src/prollytree/git/metadata.rs.html

Traverses the commit history starting from HEAD and collects commit metadata up to a specified limit.

```rust
fn walk_history(&self, limit: usize) -> Result<Vec<CommitInfo>, GitKvError> {
        let mut history = Vec::new();

        let head_commit = match self.repo.head_commit() {
            Ok(commit) => commit,
            Err(_) => return Ok(history),
        };

        let rev_walk = self.repo.rev_walk([head_commit.id()]);

        match rev_walk.all() {
            Ok(walk) => {
                for info in walk.take(limit).flatten() {
                    if let Ok(commit_obj) = info.object() {
                        if let Ok(commit_ref) = commit_obj.decode() {
                            let author = match commit_ref.author() {
                                Ok(sig) => sig,
                                Err(_) => continue,
                            };
                            let committer = match commit_ref.committer() {
                                Ok(sig) => sig,
                                Err(_) => continue,
                            };
                            let timestamp = author.time().map(|t| t.seconds).unwrap_or(0);
                            history.push(CommitInfo {
                                id: commit_obj.id().into(),
                                author: format!(
                                    "{} <{}>",
                                    String::from_utf8_lossy(author.name),
                                    String::from_utf8_lossy(author.email)
                                ),
                                committer: format!(
                                    "{} <{}>",
                                    String::from_utf8_lossy(committer.name),
                                    String::from_utf8_lossy(committer.email)
                                ),
                                message: String::from_utf8_lossy(commit_ref.message).to_string(),
                                timestamp,
                            });
                        }
                    }
                }
            }
            Err(_) => {
                history.push(CommitInfo {
                    id: head_commit.id().into(),
                    author: "Unknown".to_string(),
                    committer: "Unknown".to_string(),
                    message: "Commit".to_string(),
                    timestamp: 0,
                });
            }
        }

        Ok(history)
    }
```

--------------------------------

### Get branch commit hash

Source: https://docs.rs/prollytree/latest/src/prollytree/git/worktree.rs.html

Retrieves the current commit hash for a specified branch by reading the corresponding reference file.

```rust
pub fn get_branch_commit(&self, branch: &str) -> Result<String, GitKvError> {
        let branch_ref = self.git_dir.join("refs").join("heads").join(branch);
        if !branch_ref.exists() {
            return Err(GitKvError::BranchNotFound(format!(
                "Branch {branch} not found"
            )));
        }

        fs::read_to_string(&branch_ref)
            .map_err(GitKvError::IoError)
            .map(|s| s.trim().to_string())
    }
```

--------------------------------

### Test Basic SQL Operations

Source: https://docs.rs/prollytree/latest/src/prollytree/sql.rs.html?search=std%3A%3Avec

Demonstrates initializing a git-backed ProllyStorage, defining a schema, and performing basic CRUD operations.

```rust
#[tokio::test]
    async fn test_basic_operations() {
        let temp_dir = TempDir::new().unwrap();

        // Initialize git repository in temp directory
        std::process::Command::new("git")
            .arg("init")
            .current_dir(temp_dir.path())
            .output()
            .expect("Failed to initialize git repository");

        // Create a subdirectory for the dataset
        let dataset_path = temp_dir.path().join("dataset");
        std::fs::create_dir(&dataset_path).unwrap();

        let mut storage = ProllyStorage::<32>::init(&dataset_path).unwrap();

        // Create a simple schema
        let schema = Schema {
            table_name: "users".to_string(),
            column_defs: Some(vec![
                ColumnDef {
                    name: "id".to_string(),
                    data_type: DataType::Int,
                    nullable: false,
                    default: None,
                    unique: None,
                    comment: None,
                },
                ColumnDef {
                    name: "name".to_string(),
                    data_type: DataType::Text,
                    nullable: false,
                    default: None,
                    unique: None,
                    comment: None,
                },
            ]),
            indexes: vec![],
            engine: None,
            foreign_keys: vec![],
            comment: None,
        };

        // Insert schema
        storage.insert_schema(&schema).await.unwrap();

        // Verify schema
        let fetched = storage.fetch_schema("users").await.unwrap();
        assert!(fetched.is_some());

        // Insert some data
        let row = DataRow::Vec(vec![Value::I64(1), Value::Str("Alice".to_string())]);
        let key = Key::I64(1);
        storage
            .insert_data("users", vec![(key.clone(), row.clone())])
            .await
            .unwrap();

        // Fetch data
        let fetched_row = storage.fetch_data("users", &key).await.unwrap();
        assert!(fetched_row.is_some());

        // Scan data
        use futures::StreamExt;
        let mut iter = storage.scan_data("users").await.unwrap();
        let first = iter.next().await.unwrap().unwrap();
        assert_eq!(first.0, key);
    }
```

--------------------------------

### Initialize VersionedKvStore

Source: https://docs.rs/prollytree/latest/src/prollytree/git/versioned_store/backends.rs.html

Initializes the store with metadata and staging area, loading the staging area from the local dataset directory.

```rust
        let mut store = VersionedKvStore {
            tree,
            metadata: GitMetadataBackend::new(git_repo),
            staging_area: HashMap::new(),
            current_branch,
            storage_backend: StorageBackend::Git,
            dataset_dir: Some(dataset_dir),
            config_filename: config_filename.to_string(),
        };

        store.load_staging_area()?;

        // Don't reload_tree_from_head — git-prolly reads from the dataset
        // directory's config/mapping files, not git HEAD. The tree was
        // already loaded from local storage above.
        Ok(store)
```
Tokens:
Raw