TriviumDB

https://docs.rs/triviumdb/0.7.0
Admin
TriviumDB is a database core module with FFI bindings for Python and Node.js, and a retrieval...
Tokens:234,920
Snippets:1,829
Trust Score:9.1
Update:4 months ago
Show doc for...
Tokens:
Raw
### Vec<T> From<&[T]> Example

Source: https://docs.rs/triviumdb/0.7.0/triviumdb/graph/pathfinding/type.Path.html

Demonstrates creating a Vec<T> by cloning elements from a slice.

```rust
assert_eq!(Vec::from(&[1, 2, 3][..]), vec![1, 2, 3]);
```

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

### Vec<T> From<[T; N]> Example

Source: https://docs.rs/triviumdb/0.7.0/triviumdb/graph/pathfinding/type.Path.html

Demonstrates creating a Vec<T> by moving elements from a fixed-size array.

```rust
assert_eq!(Vec::from([1, 2, 3]), vec![1, 2, 3]);
```

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

### Vec<T> From<&[T; N]> Example

Source: https://docs.rs/triviumdb/0.7.0/triviumdb/graph/pathfinding/type.Path.html

Demonstrates creating a Vec<T> by cloning elements from a fixed-size array reference.

```rust
assert_eq!(Vec::from(&[1, 2, 3]), vec![1, 2, 3]);
```

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

### Vec<T> From<&mut [T]> Example

Source: https://docs.rs/triviumdb/0.7.0/triviumdb/graph/pathfinding/type.Path.html

Demonstrates creating a Vec<T> by cloning elements from a mutable slice.

```rust
assert_eq!(Vec::from(&mut [1, 2, 3][..]), vec![1, 2, 3]);
```

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

### Vec<T> From<&mut [T; N]> Example

Source: https://docs.rs/triviumdb/0.7.0/triviumdb/graph/pathfinding/type.Path.html

Demonstrates creating a Vec<T> by cloning elements from a mutable fixed-size array reference.

```rust
assert_eq!(Vec::from(&mut [1, 2, 3]), vec![1, 2, 3]);
```

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

### DollarOp Variant Example

Source: https://docs.rs/triviumdb/0.7.0/triviumdb/query/tql_lexer/enum.TqlToken.html

Illustrates the use of the DollarOp variant for MongoDB operators, which are prefixed with a '$'.

```rust
    DollarOp(String),
$eq, $gt 等Mongo 操作符（含 $ 前缀）
```

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

### Open WAL File

Source: https://docs.rs/triviumdb/0.7.0/triviumdb/storage/wal/struct.Wal.html

Creates or opens a WAL file in append mode. This is the initial step to start using the write-ahead log.

```rust
pub fn open(db_path: &str) -> Result<Self>
```

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

### Open or Create Database (Default)

Source: https://docs.rs/triviumdb/0.7.0/src/triviumdb/database/mod.rs.html

Opens or creates a new database with default configurations. Requires the path and vector dimension. Uses default settings for storage mode and sync mode.

```Rust
pub fn open(path: &str, dim: usize) -> Result<Self> {
    let config = Config {
        dim,
        ..Default::default()
    };
    Self::open_with_config(path, config)
}
```

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

### Get Dimension

Source: https://docs.rs/triviumdb/0.7.0/src/triviumdb/storage/memtable.rs.html

Returns the dimensionality of the vectors stored in the Memtable.

```APIDOC
## dim

### Description
Returns the dimensionality of the vectors stored in the Memtable.

### Method
`#[inline] pub fn dim(&self) -> usize`

### Parameters
None

### Endpoint
N/A (Method call)

### Response
#### Success Response (200)
- `usize`: The dimension of the vectors.

### Response Example
```rust
// Assuming `memtable` is a reference to your Memtable instance
let dimension = memtable.dim();
println!("Vector dimension: {}", dimension);
```
```

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

### Open or Create Database with Advanced Configuration

Source: https://docs.rs/triviumdb/0.7.0/src/triviumdb/database/mod.rs.html

The primary entry point for opening or creating a database with detailed configuration options. Includes dimension validation and directory creation.

```Rust
pub fn open_with_config(path: &str, config: Config) -> Result<Self> {
    let dim = config.dim;

    // ═══ 维度安全校验 ═══
    if dim == 0 {
        return Err(TriviumError::InvalidInput(
            "Vector dimension must be at least 1".into(),
        ));
    }
    // 上限 65536：单向量 65536×f32 = 256KB，已远超实际使用范围。
    // 超过此值会导致内存分配溢出或 32 位平台上的指针寻址越界。
    const MAX_DIM: usize = 65536;
    if dim > MAX_DIM {
        return Err(TriviumError::InvalidInput(format!(
            "Vector dimension {} exceeds maximum allowed {} (would require {}MB per vector pool page)",
            dim,
            MAX_DIM,
            dim * 4 / 1024 / 1024
        )));
    }

    // ═══ 自动递归创建上层目录 ═══
    if let Some(parent_dir) = std::path::Path::new(path).parent()
        && !parent_dir.as_os_str().is_empty()
    {
        std::fs::create_dir_all(parent_dir)?;
    }

    // ═══ 文件锁：防止多进程并发写同一个数据库 ═══
    let lock_path = format!("{}.lock", path);
    let lock_file = std::fs::OpenOptions::new()
        .create(true)
        .write(true)
        .open(&lock_path)?;
    lock_file.try_lock_exclusive().map_err(|_| {
        TriviumError::DatabaseLocked(format!(
            "Database '{}' is already opened by another process. \n                 If this is unexpected, delete '{}'",
            path,
            lock_path
        ))
    })?;

    let mut memtable = if std::path::Path::new(path).exists() {
        file_format::load(path, config.storage_mode)?
    } else {
        MemTable::new(dim)
    };

    if Wal::needs_recovery(path) {
        let (entries, valid_offset) = Wal::read_entries::<T>(path)?;

        // 执行极其关键的物理防串局截断（Truncation）！
        let wal_path = format!("{}.wal", path);
        let wal_file = std::fs::OpenOptions::new().write(true).open(&wal_path)?;
        wal_file.set_len(valid_offset)?;
        wal_file.sync_all()?;

        if !entries.is_empty() {
            tracing::info!(
                "Recovering {} entries from WAL, safely truncated at offset {}...",

```

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

### Get Dimension of Vectors

Source: https://docs.rs/triviumdb/0.7.0/triviumdb/storage/memtable/struct.MemTable.html

Returns the dimension of the vectors stored in the MemTable.

```rust
pub fn dim(&self) -> usize
```

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

### Get Edges

Source: https://docs.rs/triviumdb/0.7.0/src/triviumdb/storage/memtable.rs.html

Retrieves the outgoing edges for a given Node ID.

```APIDOC
## get_edges

### Description
Retrieves the outgoing edges for a given Node ID.

### Method
`pub fn get_edges(&self, id: NodeId) -> Option<&[Edge]>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
`id` (NodeId): The ID of the node for which to retrieve edges.

### Response
#### Success Response (200)
- `Option<&[Edge]>`: An optional slice of `Edge` structs representing the outgoing edges. Returns `None` if the Node ID is not found.

### Response Example
```rust
// Assuming `memtable` is a reference to your Memtable instance and `node_id` is a valid NodeId
if let Some(edges) = memtable.get_edges(node_id) {
    for edge in edges {
        println!("Edge to: {}", edge.dst_id);
    }
}
```
```

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

### TQL RETURN * Syntax

Source: https://docs.rs/triviumdb/0.7.0/triviumdb/query/tql_ast/enum.ReturnClause.html

Illustrates the TQL syntax for returning all columns from a query.

```sql
RETURN *
```

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

### Get Dimension

Source: https://docs.rs/triviumdb/0.7.0/src/triviumdb/storage/memtable.rs.html

Returns the dimension (dimensionality) of the vectors stored in the memtable.

```rust
    #[inline]
    pub fn dim(&self) -> usize {
        self.dim
    }
```

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

### Open or Create Database with Sync Mode

Source: https://docs.rs/triviumdb/0.7.0/src/triviumdb/database/mod.rs.html

Opens or creates a database, allowing specification of the WAL synchronization mode. This is a backward-compatible method.

```Rust
pub fn open_with_sync(path: &str, dim: usize, sync_mode: SyncMode) -> Result<Self> {
    let config = Config {
        dim,
        sync_mode,
        ..Default::default()
    };
    Self::open_with_config(path, config)
}
```

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

### Transaction Usage Example

Source: https://docs.rs/triviumdb/0.7.0/triviumdb/database/transaction/struct.Transaction.html

Demonstrates how to begin a transaction, perform insert and link operations, and then atomically commit the changes. Ensure to handle potential errors during commit.

```rust
let mut tx = db.begin_tx();
tx.insert(&vec, payload);
tx.link(1, 2, "knows", 1.0);
tx.commit()?;  // 原子提交
```

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

### Get Node Edges

Source: https://docs.rs/triviumdb/0.7.0/src/triviumdb/database/mod.rs.html

Retrieves all outgoing edges for a specific node.

```APIDOC
## Get Node Edges

### Description
Retrieves a list of all edges originating from the specified node ID.

### Method
```rust
pub fn get_edges(&self, id: NodeId) -> Vec<crate::node::Edge>
```

### Parameters
* **id** (`NodeId`) - The ID of the node whose edges are to be retrieved.

### Returns
* `Vec<crate::node::Edge>` - A vector containing all edges connected to the node. Returns an empty vector if the node has no outgoing edges or does not exist.

### Example
```rust
// Assuming db is an immutable reference to your TriviumDB instance
let edges = db.get_edges(node_id);
for edge in edges {
    println!("Edge to: {}, Weight: {}", edge.target_id, edge.weight);
}
```
```

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

### Get Node Payload

Source: https://docs.rs/triviumdb/0.7.0/src/triviumdb/database/mod.rs.html

Retrieves the payload of a specific node by its ID.

```APIDOC
## Get Node Payload

### Description
Retrieves the JSON payload associated with a given node ID from the in-memory table.

### Method
```rust
pub fn get_payload(&self, id: NodeId) -> Option<serde_json::Value>
```

### Parameters
* **id** (`NodeId`) - The ID of the node whose payload is to be retrieved.

### Returns
* `Option<serde_json::Value>` - Returns `Some(payload)` if the node exists and has a payload, otherwise `None`.

### Example
```rust
// Assuming db is an immutable reference to your TriviumDB instance
if let Some(payload) = db.get_payload(node_id) {
    println!("Node payload: {:?}", payload);
}
```
```

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

### TqlToken Initialization

Source: https://docs.rs/triviumdb/0.7.0/triviumdb/query/tql_lexer/enum.TqlToken.html

Initializes a TqlToken with the given initializer.

```APIDOC
## init

### Description
Initializes a TqlToken with the given initializer.

### Signature
`unsafe fn init(init: <T as Pointable>::Init) -> usize`
```

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

### TQL RETURN Variables Syntax

Source: https://docs.rs/triviumdb/0.7.0/triviumdb/query/tql_ast/enum.ReturnClause.html

Illustrates the TQL syntax for returning specific variables (columns) from a query.

```sql
RETURN a, b
```

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

### Vec<T> From<Cow<[T]>> Example

Source: https://docs.rs/triviumdb/0.7.0/triviumdb/graph/pathfinding/type.Path.html

Converts a Cow<[T]> into a Vec<T>. If the Cow is Owned, it's returned directly. If Borrowed, a new Vec is allocated and filled by cloning.

```rust
let o: Cow<'_, [i32]> = Cow::Owned(vec![1, 2, 3]);
let b: Cow<'_, [i32]> = Cow::Borrowed(&[1, 2, 3]);
assert_eq!(Vec::from(o), Vec::from(b));
```

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

### Get Vector Length

Source: https://docs.rs/triviumdb/0.7.0/triviumdb/graph/pathfinding/type.Path.html

Returns the number of elements currently stored in the vector.

```rust
let a = vec![1, 2, 3];
assert_eq!(a.len(), 3);

```

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

### TQL Query Executor Overview

Source: https://docs.rs/triviumdb/0.7.0/src/triviumdb/query/tql_executor.rs.html

This code block provides an overview of the TQL unified query executor. It explains the three main entry points: MATCH for graph pattern matching, FIND for document filtering, and SEARCH for vector retrieval. It also mentions that DML write operations generate MutationOp instructions.

```rust
1//! TQL 统一查询执行器
2//! 
3//! 将 TqlQuery AST 在 MemTable 上执行，支持三种入口：
4//! - MATCH: 图模式匹配（含可变长路径、多标签边）
5//! - FIND: 文档过滤扫描
6//! - SEARCH: 向量检索 + 图扩散（桥接到现有管线）
7//! 
8//! DML 写操作通过 execute_tql_mutation() 生成 MutationOp 指令，
9//! 由 Database 层统一执行并写入 WAL。
10
```

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

### Get Edges for a Node

Source: https://docs.rs/triviumdb/0.7.0/triviumdb/storage/memtable/struct.MemTable.html

Retrieves the outgoing edges for a specified node, if any exist.

```rust
pub fn get_edges(&self, id: NodeId) -> Option<&[Edge]>
```

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

### Convenience Entry Point: Parse TQL to TqlQuery AST

Source: https://docs.rs/triviumdb/0.7.0/src/triviumdb/query/tql_parser.rs.html

Provides a convenient way to parse a TQL string into a TqlQuery AST for read-only queries. Initializes the lexer and parser.

```rust
pub fn parse_tql(input: &str) -> Result<TqlQuery, String> {
    let mut lexer = super::tql_lexer::TqlLexer::new(input);
    let tokens = lexer.tokenize()?;
    let mut parser = TqlParser::new(tokens);
    parser.parse_query()
}
```

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

### Get Payload

Source: https://docs.rs/triviumdb/0.7.0/src/triviumdb/storage/memtable.rs.html

Retrieves the JSON payload associated with a given Node ID.

```APIDOC
## get_payload

### Description
Retrieves the JSON payload associated with a given Node ID.

### Method
`pub fn get_payload(&self, id: NodeId) -> Option<&serde_json::Value>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
`id` (NodeId): The ID of the node for which to retrieve the payload.

### Response
#### Success Response (200)
- `Option<&serde_json::Value>`: An optional reference to the JSON payload. Returns `None` if the Node ID is not found.

### Response Example
```rust
// Assuming `memtable` is a reference to your Memtable instance and `node_id` is a valid NodeId
if let Some(payload) = memtable.get_payload(node_id) {
    println!("Payload: {}", payload);
}
```
```

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

### Convenience Entry Point: Parse TQL to TqlStatement

Source: https://docs.rs/triviumdb/0.7.0/src/triviumdb/query/tql_parser.rs.html

Provides a convenient way to parse a TQL string into a TqlStatement, which can represent either a read query or a write operation. Initializes the lexer and parser.

```rust
pub fn parse_tql_statement(input: &str) -> Result<TqlStatement, String> {
    let mut lexer = super::tql_lexer::TqlLexer::new(input);
    let tokens = lexer.tokenize()?;
    let mut parser = TqlParser::new(tokens);
    parser.parse_statement()
}
```

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

### Get Database Dimension

Source: https://docs.rs/triviumdb/0.7.0/src/triviumdb/database/mod.rs.html

Retrieves the current dimensionality of the vectors stored in the database.

```rust
pub fn dim(&self) -> usize {
        lock_or_recover(&self.memtable).dim()
    }
```

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

### begin_tx

Source: https://docs.rs/triviumdb/0.7.0/triviumdb/database/struct.Database.html

Initiates a lightweight transaction. All write operations within the transaction are buffered in memory and atomically applied upon calling `commit()`.

```APIDOC
## pub fn begin_tx(&mut self) -> Transaction<'_, T>

### Description
Initiates a lightweight transaction. Write operations are buffered in memory and applied atomically on commit.

### Method
`begin_tx`

### Example
```rust
let mut tx = db.begin_tx();
// Perform write operations using tx
tx.commit()?;
```
```

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

### Vec with Initial Capacity

Source: https://docs.rs/triviumdb/0.7.0/triviumdb/graph/pathfinding/type.Path.html

Shows how to create a Vec with a specified initial capacity and verify it.

```rust
let mut vec: Vec<i32> = Vec::with_capacity(10);
vec.push(42);
assert!(vec.capacity() >= 10);

```

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

### Get BQ Signature

Source: https://docs.rs/triviumdb/0.7.0/triviumdb/storage/memtable/struct.MemTable.html

Retrieves the BQ quantization pre-screening signature for a given index.

```rust
pub fn get_bq_signature(&self, index: usize) -> Option<BqSignature>
```

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

### Get Text Index Engine

Source: https://docs.rs/triviumdb/0.7.0/src/triviumdb/storage/memtable.rs.html

Provides read-only access to the internal TextIndex engine.

```rust
pub fn text_engine(&self) -> &TextIndex {
        &self.text_index
    }
```

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

### Execute a Write Operation with TQL

Source: https://docs.rs/triviumdb/0.7.0/triviumdb/database/struct.Database.html

Serves as the entry point for TQL write operations, including creating, updating, and deleting nodes and edges. It also supports read queries, falling back to `tql()`.

```rust
let result = db.tql_mut(r#"CREATE ({name: "Alice", age: 30})"#)?;
assert_eq!(result.created_ids.len(), 1);
```

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

### Get Edges by Node ID

Source: https://docs.rs/triviumdb/0.7.0/src/triviumdb/storage/memtable.rs.html

Retrieves the outgoing edges for a given Node ID, if any.

```rust
    pub fn get_edges(&self, id: NodeId) -> Option<&[Edge]> {
        self.edges.get(&id).map(|e| e.as_slice())
    }
```

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

### Database::open_with_config

Source: https://docs.rs/triviumdb/0.7.0/src/triviumdb/database/mod.rs.html

The advanced entry point for opening or creating a database, allowing full customization through the `Config` struct. This enables fine-grained control over dimensions, storage modes, WAL sync modes, and other database parameters.

```APIDOC
## Database::open_with_config

### Description
The advanced entry point for opening or creating a database, allowing full customization through the `Config` struct. This enables fine-grained control over dimensions, storage modes, WAL sync modes, and other database parameters.

### Method
`Database::open_with_config(path: &str, config: Config) -> Result<Self>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response
- `Database<T>`: An instance of the Database.

#### Response Example
```rust
// Example usage
// use triviumdb::database::config::Config;
// let config = Config { dim: 128, storage_mode: StorageMode::Mmap, ..Default::default() };
// let db = Database::<Vec<f32>>::open_with_config("./my_db", config)?; 
```

### Error Handling
- `TriviumError` if the database cannot be opened or created, if the dimension is invalid, or if the database is locked by another process.
```

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

### Execute TQL Query Function

Source: https://docs.rs/triviumdb/0.7.0/src/triviumdb/query/tql_executor.rs.html

The main entry point for executing a parsed TqlQuery. It handles EXPLAIN mode, applies row limits, and dispatches to specific execution functions based on the query entry type (Find, Match, Search). It also handles sorting, offset, limit, aggregation, and projection pruning.

```rust
65pub fn execute_tql<T: VectorType>(
66    query: &TqlQuery,
67    memtable: &MemTable<T>,
68) -> Result<TqlResult<T>, TriviumError> {
69    // EXPLAIN 模式：输出查询计划而不执行
70    if query.explain {
71        return Ok(generate_explain_plan(query, memtable));
72    }
73
74    let row_limit = query.limit.unwrap_or(DEFAULT_ROW_LIMIT);
75
76    let mut results = match &query.entry {
77        QueryEntry::Find { filter } => execute_find(filter, query, memtable, row_limit)?,
78        QueryEntry::Match { pattern } => execute_match(pattern, query, memtable, row_limit, false)?,
79        QueryEntry::OptionalMatch { pattern } => {
80            execute_match(pattern, query, memtable, row_limit, true)?
81        }
82        QueryEntry::Search {
83            vector,
84            top_k,
85            expand,
86        } => execute_search(vector, *top_k, expand.as_ref(), query, memtable, row_limit)?,
87    };
88
89    // ORDER BY 排序
90    if !query.order_by.is_empty() {
91        sort_results(&mut results, &query.order_by, memtable);
92    }
93
94    // OFFSET 偏移
95    if let Some(off) = query.offset {
96        if off < results.len() {
97            results = results.into_iter().skip(off).collect();
98        } else {
99            results.clear();
100        }
101    }
102
103    // LIMIT 截断（排序后再截断）
104    if let Some(lim) = query.limit {
105        results.truncate(lim);
106    }
107
108    // 聚合函数 + DISTINCT 后处理
109    results = apply_aggregation_and_distinct(
110        &query.returns,
111        results,
112        matches!(&query.entry, QueryEntry::Find { .. }),
113    )?;
114
115    // 投影裁剪：对仅属性引用的变量，剥离 vector + edges 节省内存
116    apply_projection_pruning(&query.returns, &mut results);
117
118    Ok(results)
119}
```

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

### Get All Node IDs

Source: https://docs.rs/triviumdb/0.7.0/src/triviumdb/database/mod.rs.html

Retrieves a list of all node IDs currently present in the database.

```APIDOC
## Get All Node IDs

### Description
Returns a list containing the IDs of all nodes currently stored in the database's in-memory table.

### Method
```rust
pub fn get_all_ids(&self) -> Vec<NodeId>
```

### Returns
* `Vec<NodeId>` - A vector of all node identifiers.

### Example
```rust
// Assuming db is an immutable reference to your TriviumDB instance
let all_ids = db.get_all_ids();
println!("Total nodes: {}", all_ids.len());
```
```

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

### QuIVer::batch_build_experimental

Source: https://docs.rs/triviumdb/0.7.0/triviumdb/index/quiver/struct.QuIVer.html

An experimental method for batch building the QuIVer.

```APIDOC
## QuIVer::batch_build_experimental

### Description
An experimental method for batch building the QuIVer.

### Method
`batch_build_experimental(&mut self, vectors: &[f32], ids: &[u64], slot_idxs: &[usize])`

### Parameters
* **vectors** (&[f32]) - Required - The vectors to build.
* **ids** (&[u64]) - Required - The IDs corresponding to the vectors.
* **slot_idxs** (&[usize]) - Required - The slot indices for the vectors.
```

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

### MemTable Initialization

Source: https://docs.rs/triviumdb/0.7.0/triviumdb/storage/memtable/struct.MemTable.html

Provides methods for creating new MemTable instances, with options for specifying initial state and external resources.

```APIDOC
## `new(dim: usize) -> Self`

### Description
Creates a new, empty MemTable with the specified dimension for node vectors.

### Method
`new`

### Parameters
#### Path Parameters
- `dim` (usize) - Required - The dimension of the vectors to be stored.
```

```APIDOC
## `new_with_next_id(dim: usize, next_id: NodeId) -> Self`

### Description
Creates a new MemTable, useful when restoring from a persistent file, allowing specification of the starting ID.

### Method
`new_with_next_id`

### Parameters
#### Path Parameters
- `dim` (usize) - Required - The dimension of the vectors.
- `next_id` (NodeId) - Required - The initial value for the next node ID.
```

```APIDOC
## `new_with_vec_pool(dim: usize, next_id: NodeId, vec_pool: VecPool<T>) -> Self`

### Description
Creates a new MemTable with a specified starting ID and an pre-loaded VecPool, suitable for restoring from persistent storage.

### Method
`new_with_vec_pool`

### Parameters
#### Path Parameters
- `dim` (usize) - Required - The dimension of the vectors.
- `next_id` (NodeId) - Required - The initial value for the next node ID.
- `vec_pool` (VecPool<T>) - Required - An already loaded VecPool instance.
```

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

### Database::open_with_sync

Source: https://docs.rs/triviumdb/0.7.0/src/triviumdb/database/mod.rs.html

Opens or creates a database instance, allowing specification of the WAL (Write-Ahead Logging) synchronization mode. This provides backward compatibility for controlling WAL behavior.

```APIDOC
## Database::open_with_sync

### Description
Opens or creates a database instance, allowing specification of the WAL (Write-Ahead Logging) synchronization mode. This provides backward compatibility for controlling WAL behavior.

### Method
`Database::open_with_sync(path: &str, dim: usize, sync_mode: SyncMode) -> Result<Self>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response
- `Database<T>`: An instance of the Database.

#### Response Example
```rust
// Example usage
// use triviumdb::database::transaction::SyncMode;
// let db = Database::<Vec<f32>>::open_with_sync("./my_db", 128, SyncMode::Normal)?; 
```

### Error Handling
- `TriviumError` if the database cannot be opened or created, or if the dimension is invalid.
```

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

### Build Query Execution Plan

Source: https://docs.rs/triviumdb/0.7.0/src/triviumdb/query/tql_executor.rs.html

Constructs a detailed execution plan for a TQL query, including entry type, candidate strategy, predicates, return information, optimizations, and statistics. This is used internally to represent the query execution flow.

```Rust
fn build_plan<T: VectorType>(
    query: &TqlQuery,
    mt: &MemTable<T>,
) -> Vec<HashMap<String, Node>> {
    let mut plan = serde_json::Map::new();

    // Entry 类型
    let entry_type = match &query.entry {
        QueryEntry::Find { .. } => "Find".to_string(),
        QueryEntry::Match { .. } => "Match".to_string(),
        QueryEntry::OptionalMatch { .. } => "OptionalMatch".to_string(),
        QueryEntry::Search { .. } => "Search".to_string(),
    };

    // Entry 详细信息
    let entry_detail = match &query.entry {
        QueryEntry::Find { top_k, expand } => {
            let detail = if expand.is_some() {
                format!("TOP {} + EXPAND", top_k)
            } else {
                format!("TOP {}", top_k)
            };
            ("SEARCH".to_string(), detail)
        }
        QueryEntry::Match { pattern } | QueryEntry::OptionalMatch { pattern } => {
            let detail = format_pattern_detail(pattern);
            ("MATCH".to_string(), detail)
        }
        QueryEntry::Search { pattern, .. } => {
            let detail = format_pattern_detail(pattern);
            ("SEARCH".to_string(), detail)
        }
    };
    plan.insert("entry".into(), serde_json::json!(entry_type));
    plan.insert("detail".into(), serde_json::json!(entry_detail));

    // 候选集策略
    let strategy = match &query.entry {
        QueryEntry::Find { .. } => "full_scan".to_string(),
        QueryEntry::Match { pattern } | QueryEntry::OptionalMatch { pattern } => {
            analyze_candidate_strategy(&pattern.nodes[0], pattern.edges.first(), mt)
        }
        QueryEntry::Search { .. } => "vector_index".to_string(),
    };
    plan.insert("candidate_strategy".into(), serde_json::json!(strategy));

    // WHERE 谓词
    if let Some(pred) = &query.predicate {
        plan.insert("predicate".into(), serde_json::json!(format!("{:?}", pred)));
    } else {
        plan.insert("predicate".into(), serde_json::json!("none"));
    }

    // RETURN 信息
    let return_info = match &query.returns {
        ReturnClause::All => "ALL (*)".to_string(),
        ReturnClause::Variables(vars) => format!("variables: [{}]", vars.join(", ")),
        ReturnClause::Expressions(exprs) => {
            let descs: Vec<String> = exprs.iter().map(format_return_expr).collect();
            format!("expressions: [{}]", descs.join(", "))
        }
    };
    plan.insert("return".into(), serde_json::json!(return_info));

    // 优化提示
    let mut optimizations = Vec::new();
    if strategy.contains("id_shortcut") {
        optimizations.push("ID O(1) shortcut");
    }
    if strategy.contains("label_index") {
        optimizations.push("label index pushdown");
    }
    if let ReturnClause::Expressions(exprs) = &query.returns {
        let prunable = get_prunable_vars(exprs);
        if !prunable.is_empty() {
            optimizations.push("projection pruning");
        }
        if exprs.iter().any(|e| e.distinct) {
            optimizations.push("DISTINCT dedup");
        }
        if exprs.iter().any(|e| is_aggregate(&e.kind)) {
            optimizations.push("aggregation");
        }
    }
    if query.limit.is_some() {
        optimizations.push("LIMIT early termination");
    }
    plan.insert("optimizations".into(), serde_json::json!(optimizations));

    // 统计信息
    plan.insert(
        "total_nodes".into(),
        serde_json::json!(mt.all_node_ids().len()),
    );
    if let Some(lim) = query.limit {
        plan.insert("limit".into(), serde_json::json!(lim));
    }
    if let Some(off) = query.offset {
        plan.insert("offset".into(), serde_json::json!(off));
    }
    if !query.order_by.is_empty() {
        plan.insert(
            "order_by_count".into(),
            serde_json::json!(query.order_by.len()),
        );
    }

    // 封装为单行结果
    let plan_node = Node {
        id: 0,
        vector: Vec::new(),
        payload: serde_json::Value::Object(plan),
        edges: Vec::new(),
    };
    let mut row = HashMap::new();
    row.insert("plan".to_string(), plan_node);
    vec![row]
}

```

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

### Tokenize Query with Comment

Source: https://docs.rs/triviumdb/0.7.0/src/triviumdb/query/tql_lexer.rs.html

Shows that comments starting with '--' are correctly skipped during tokenization.

```rust
let mut lexer = TqlLexer::new("FIND {type: \"event\"} -- this is a comment\nRETURN *");
let tokens = lexer.tokenize().unwrap();
assert!(tokens.contains(&TqlToken::Return));
```

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

### Get Quiver Index Reference

Source: https://docs.rs/triviumdb/0.7.0/triviumdb/storage/memtable/struct.MemTable.html

Returns an optional reference to the QuIVer graph index if it has been built.

```rust
pub fn quiver(&self) -> Option<&QuIVer>
```

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

### Database::open

Source: https://docs.rs/triviumdb/0.7.0/src/triviumdb/database/mod.rs.html

Opens or creates a new database instance with default configurations. It requires the path to the database directory and the dimension of the vectors to be stored. Defaults to Mmap mode and SyncMode::Normal.

```APIDOC
## Database::open

### Description
Opens or creates a new database instance with default configurations. It requires the path to the database directory and the dimension of the vectors to be stored. Defaults to Mmap mode and SyncMode::Normal.

### Method
`Database::open(path: &str, dim: usize) -> Result<Self>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response
- `Database<T>`: An instance of the Database.

#### Response Example
```rust
// Example usage (assuming Database<Vec<f32>> is intended)
// let db = Database::<Vec<f32>>::open("./my_db", 128)?; 
```

### Error Handling
- `TriviumError` if the database cannot be opened or created, or if the dimension is invalid.
```

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

### Get Payload by Node ID

Source: https://docs.rs/triviumdb/0.7.0/src/triviumdb/storage/memtable.rs.html

Retrieves the payload associated with a given Node ID, if it exists.

```rust
    pub fn get_payload(&self, id: NodeId) -> Option<&serde_json::Value> {
        self.payloads.get(&id)
    }
```

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

### Get QuIVer Statistics

Source: https://docs.rs/triviumdb/0.7.0/triviumdb/index/quiver/struct.QuIVer.html

Retrieves statistics about the QuIVer index, such as node counts and connectivity information.

```rust
pub fn stats(&self) -> QuIVerStats
```

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

### Vec<T> From<Box<[T]>> Example

Source: https://docs.rs/triviumdb/0.7.0/triviumdb/graph/pathfinding/type.Path.html

Converts a boxed slice into a vector by transferring ownership of the heap allocation.

```rust
let b: Box<[i32]> = vec![1, 2, 3].into_boxed_slice();
assert_eq!(Vec::from(b), vec![1, 2, 3]);
```

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

### Initialize Vector Pool with Memory Mapping

Source: https://docs.rs/triviumdb/0.7.0/src/triviumdb/storage/vec_pool.rs.html

Sets up a vector pool, potentially using memory mapping for the base layer. It includes a recommendation for sequential prefetching on Unix-like systems to optimize read performance for large datasets.

```rust
                pool.mmap = Some(mmap);
                pool.mmap_count = expected_count;

                // 建立映射后立刻提交顺序预读建议：
                // BruteForce 全量扫描是 TriviumDB 的主要访问模式，
                // MADV_SEQUENTIAL 提示 OS 在读到第 N 页时就预读第 N+k 页，
                // 有效隐藏 page fault 延迟（在数据集大于 L3 Cache 时收益显著）。
                #[cfg(unix)]
                if let Some(ref m) = pool.mmap {
                    madvise(m, memmap2::Advice::Sequential);
                }

```

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

### Get Immutable Slice of Vec

Source: https://docs.rs/triviumdb/0.7.0/triviumdb/graph/pathfinding/type.Path.html

Extracts an immutable slice representing the entire vector. Equivalent to `&s[..]`.

```rust
use std::io::{self, Write};
let buffer = vec![1, 2, 3, 5, 8];
io::sink().write(buffer.as_slice()).unwrap();
```

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

### Batch Build Experimental Functionality

Source: https://docs.rs/triviumdb/0.7.0/src/triviumdb/index/quiver.rs.html

Handles the batch building of the experimental index. It processes vectors, generates signatures, assigns levels, and inserts nodes into the index structure.

```rust
pub fn batch_build_experimental(&mut self, vectors: &[f32], ids: &[u64], slot_idxs: &[usize]) {
    let n = ids.len();
    let dim = self.dim;
    assert_eq!(vectors.len(), n * dim);
    assert_eq!(slot_idxs.len(), n);

    let sigs: Vec<Bq2Signature> = vectors
        .par_chunks(dim)
        .map(Bq2Signature::from_vector)
        .collect();

    self.bq_sigs.reserve(n);
    self.ids.reserve(n);
    self.slot_indices.reserve(n);
    self.tombstones.reserve(n);
    self.node_max_layer.reserve(n);

    let mut lcg: u64 = 12345;
    let mut levels = Vec::with_capacity(n);
    for _ in 0..n {
        levels.push(self.random_level(&mut lcg));
    }

    self.layer0.data.reserve(n * self.layer0.stride);

    let mut visited = Bitset::new(0);
    for i in 0..n {
        let _v = &vectors[i * dim..(i + 1) * dim];
        let idx = self.n as u32;

        self.bq_sigs.push(sigs[i]);
        self.ids.push(ids[i]);
        self.slot_indices.push(slot_idxs[i]);
        self.id_to_internal.insert(ids[i], idx);
        self.tombstones.push(false);

        let level = levels[i];
        self.node_max_layer.push(level as u8);

        self.layer0.push_empty();
        while self.upper_layers.len() < level {
            self.upper_layers.push(vec![Vec::new(); self.n]);
        }
        for ul in self.upper_layers.iter_mut() {
            ul.push(Vec::new());
        }

        self.n += 1;
        visited.grow(self.n);

        if self.n == 1 {
            self.entry_point = 0;
            self.max_level = level;
            continue;
        }

        let my_sig = self.bq_sigs[idx as usize];
        let mut cur_node = self.entry_point;

        for l in ((level + 1)..=self.max_level).rev() {
            let ul_idx = l - 1;
            if ul_idx < self.upper_layers.len() {
                loop {
                    let mut changed = false;
                    let cur_d = my_sig.distance(&self.bq_sigs[cur_node as usize], dim);
                    let mut best_d = cur_d;
                    for &nb in &self.upper_layers[ul_idx][cur_node as usize] {
                        let nd = my_sig.distance(&self.bq_sigs[nb as usize], dim);
                        if nd < best_d {
                            cur_node = nb;
                            best_d = nd;
                            changed = true;
                        }
                    }
                    if !changed {
                        break;
                    }
                }
            }
        }
    }
}
```

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

### Get Indexed Field Names

Source: https://docs.rs/triviumdb/0.7.0/triviumdb/storage/memtable/struct.MemTable.html

Returns a set of names for all fields that currently have registered property indexes.

```rust
pub fn indexed_field_names(&self) -> &HashSet<String>
```

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

### Get Edges by Label

Source: https://docs.rs/triviumdb/0.7.0/triviumdb/storage/memtable/struct.MemTable.html

Finds all edges (src, dst) that match a specific label. This is an O(1) lookup.

```rust
pub fn get_edges_by_label(&self, label: &str) -> &[(NodeId, NodeId)]
```

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

### Tokenize ORDER BY, LIMIT, and OFFSET Clauses

Source: https://docs.rs/triviumdb/0.7.0/src/triviumdb/query/tql_lexer.rs.html

Demonstrates tokenizing a query that includes ORDER BY, DESC, LIMIT, and OFFSET clauses.

```rust
let mut lexer = TqlLexer::new("ORDER BY a.score DESC LIMIT 10 OFFSET 20");
let tokens = lexer.tokenize().unwrap();
assert_eq!(tokens[0], TqlToken::Order);
assert_eq!(tokens[1], TqlToken::By);
assert!(tokens.contains(&TqlToken::Desc));
assert!(tokens.contains(&TqlToken::Offset));
```

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

### Initialize TextIndex

Source: https://docs.rs/triviumdb/0.7.0/src/triviumdb/index/text.rs.html

Creates a new instance of TextIndex using its default configuration.

```rust
pub fn new() -> Self {
    Self::default()
}
```

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

### Unwrap Ok Value

Source: https://docs.rs/triviumdb/0.7.0/triviumdb/error/type.Result.html

Use `unwrap` to get the value from an `Ok` variant. It panics if the `Result` is an `Err`.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.unwrap(), 2);
```

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

### Get Node In-Degree

Source: https://docs.rs/triviumdb/0.7.0/src/triviumdb/storage/memtable.rs.html

Retrieves the in-degree count for a given NodeId. Returns 0 if the node does not exist.

```rust
/// 获取节点的入度数（若不存在则返回0）
    pub fn get_in_degree(&self, id: NodeId) -> usize {
        self.in_degrees.get(&id).copied().unwrap_or(0)
    }
```

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

### tql_mut

Source: https://docs.rs/triviumdb/0.7.0/triviumdb/database/struct.Database.html

Serves as the entry point for TQL write operations, including creating, updating, and deleting nodes and edges. It also supports read queries, automatically degrading to `tql()`.

```APIDOC
## pub fn tql_mut(&mut self, input: &str) -> Result<TqlMutResult>

### Description
TQL write operation entry point. Supports node/edge creation, updates, and deletions. Also compatible with read queries, automatically degrading to `tql()`.

### Method
`tql_mut`

### Parameters
#### Path Parameters
- **input** (str) - Required - The TQL mutation string.

### Example
```rust
let result = db.tql_mut(r#"CREATE ({name: "Alice", age: 30})"#)?;
assert_eq!(result.created_ids.len(), 1);
```
```

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

### Get Node ID by Index

Source: https://docs.rs/triviumdb/0.7.0/src/triviumdb/storage/memtable.rs.html

Retrieves the Node ID corresponding to a given index in the vector array.

```APIDOC
## get_id_by_index

### Description
Retrieves the Node ID corresponding to a given index in the vector array.

### Method
`#[inline] pub fn get_id_by_index(&self, idx: usize) -> NodeId`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
`idx` (usize): The index of the vector for which to retrieve the Node ID.

### Response
#### Success Response (200)
- `NodeId`: The Node ID associated with the given index.

### Response Example
```rust
// Assuming `memtable` is a reference to your Memtable instance
let node_id = memtable.get_id_by_index(0);
println!("Node ID at index 0: {}", node_id);
```
```

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

### from_raw_parts_in

Source: https://docs.rs/triviumdb/0.7.0/triviumdb/graph/pathfinding/type.Path.html

Creates a `Vec<T, A>` directly from a pointer, a length, a capacity, and an allocator. This is a nightly-only experimental API.

```APIDOC
## pub const unsafe fn from_raw_parts_in( ptr: *mut T, length: usize, capacity: usize, alloc: A, ) -> Vec<T, A>

### Description
Creates a `Vec<T, A>` directly from a pointer, a length, a capacity, and an allocator.

### Parameters
- `ptr` (*mut T): A raw mutable pointer to the data.
- `length` (usize): The length of the vector.
- `capacity` (usize): The capacity of the vector.
- `alloc` (A): The allocator to use for the vector.

### Returns
- `Vec<T, A>`: A new `Vec` constructed from the provided components.

### Safety
This function is unsafe because the caller must ensure that `ptr` is a valid pointer to `length` elements, that the elements are initialized, that `capacity` is the correct capacity, and that `alloc` is the correct allocator for this memory. The caller must also ensure that the memory is not deallocated while the `Vec` is still in use.

### Experimental
This is a nightly-only experimental API.
```

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

### TQL RETURN Expressions Syntax

Source: https://docs.rs/triviumdb/0.7.0/triviumdb/query/tql_ast/enum.ReturnClause.html

Illustrates the TQL syntax for returning computed expressions, including aggregate functions and aliased results, from a query.

```sql
RETURN count(b), avg(b.age) AS avg_age, DISTINCT a.name
```

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

### Get Node ID by Index

Source: https://docs.rs/triviumdb/0.7.0/src/triviumdb/storage/memtable.rs.html

Retrieves the Node ID corresponding to a given index in the internal storage.

```rust
    #[inline]
    pub fn get_id_by_index(&self, idx: usize) -> NodeId {
        self.indices_to_ids[idx]
    }
```

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

### Get All Node IDs

Source: https://docs.rs/triviumdb/0.7.0/src/triviumdb/database/mod.rs.html

Retrieves a list of all node IDs currently present in the database. This is a read operation.

```rust
pub fn get_all_ids(&self) -> Vec<NodeId> {
    let mt = lock_or_recover(&self.memtable);
    mt.get_all_ids()
}
```

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

### Get Underlying Allocator Reference

Source: https://docs.rs/triviumdb/0.7.0/triviumdb/graph/pathfinding/type.Path.html

Retrieves a reference to the vector's underlying allocator. This is a nightly-only experimental API.

```rust
let allocator_ref = my_vec.allocator();

```

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

### Graph Construction and Neighbor Selection in Quiver Index

Source: https://docs.rs/triviumdb/0.7.0/src/triviumdb/index/quiver.rs.html

This Rust code demonstrates the core logic for building the Quiver index. It involves iterating through levels, performing beam searches to find candidate neighbors, and selecting the best neighbors using the Vamana algorithm for both layer 0 and upper layers. It also handles updating the entry point and max level of the index.

```rust
for l in (level..=self.max_level).rev() {
                let res = self.beam_search_upper(&my_sig, l, cur_node, 1, &mut visited);
                if !res.is_empty() {
                    cur_node = res[0].1;
                }
            }

            for l in (0..=level).rev() {
                let ef = self.ef_construction;
                let candidates_sym = if l == 0 {
                    self.beam_search_l0(&my_sig, cur_node, ef, &mut visited)
                } else {
                    self.beam_search_upper(&my_sig, l, cur_node, ef, &mut visited)
                };
                let candidates: Vec<(u32, u32)> = candidates_sym
                    .into_iter()
                    .map(|(_, id)| (my_sig.distance(&self.bq_sigs[id as usize], dim), id))
                    .collect();

                let max_nb = if l == 0 { self.m0 } else { self.m };
                let selected = self.select_neighbors(idx, &candidates, max_nb);

                if l == 0 {
                    for &nb in &selected {
                        if !self.layer0.contains(idx, nb) {
                            self.layer0.push_neighbor(idx, nb);
                        }
                    }

                    let this_addr = self as *mut Self as usize;
                    selected.par_iter().for_each(|&nb| unsafe {
                        let this = &mut *(this_addr as *mut Self);
                        let mut nb_candidates: Vec<(u32, u32)> = this
                            .layer0
                            .neighbors(nb)
                            .iter()
                            .map(|&n| {
                                (
                                    this.bq_sigs[nb as usize]
                                        .distance(&this.bq_sigs[n as usize], dim),
                                    n,
                                )
                            })
                            .collect();
                        if !this.layer0.contains(nb, idx) {
                            let d = this.bq_sigs[nb as usize]
                                .distance(&this.bq_sigs[idx as usize], dim);
                            nb_candidates.push((d, idx));
                        }
                        nb_candidates.sort_unstable_by_key(|&(d, _)| d);
                        let pruned = Self::vamana_select(
                            &this.bq_sigs,
                            nb,
                            &nb_candidates,
                            max_nb,
                            dim,
                            this.alpha,
                        );
                        this.layer0.set_neighbors(nb, &pruned);
                    });
                } else {
                    let ul = l - 1;
                    for &nb in &selected {
                        if !self.upper_layers[ul][idx as usize].contains(&nb) {
                            self.upper_layers[ul][idx as usize].push(nb);
                        }
                        if !self.upper_layers[ul][nb as usize].contains(&idx) {
                            self.upper_layers[ul][nb as usize].push(idx);
                        }
                    }
                }

                if !candidates.is_empty() {
                    cur_node = candidates[0].1;
                }
            }

            if level > self.max_level {
                self.entry_point = idx;
                self.max_level = level;
            }
```

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

### Vec with Custom Allocator

Source: https://docs.rs/triviumdb/0.7.0/triviumdb/graph/pathfinding/type.Path.html

Demonstrates creating a Vec with a specific allocator and converting it back into its components.

```rust
#![feature(allocator_api)]

use std::alloc::System;

let mut v: Vec<i32, System> = Vec::new_in(System);
v.push(-1);
v.push(0);
v.push(1);

let (ptr, len, cap, alloc) = v.into_parts_with_alloc();

let rebuilt = unsafe {
    // We can now make changes to the components, such as
    // transmuting the raw pointer to a compatible type.
    let ptr = ptr.cast::<u32>();

    Vec::from_parts_in(ptr, len, cap, alloc)
};
assert_eq!(rebuilt, [4294967295, 0, 1]);

```

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

### Get Mutable Slice of Vec

Source: https://docs.rs/triviumdb/0.7.0/triviumdb/graph/pathfinding/type.Path.html

Extracts a mutable slice representing the entire vector. Equivalent to `&mut s[..]`.

```rust
use std::io::{self, Read};
let mut buffer = vec![0; 3];
io::repeat(0b101).read_exact(buffer.as_mut_slice()).unwrap();
```

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

### Get Incoming Sources for a Node

Source: https://docs.rs/triviumdb/0.7.0/triviumdb/storage/memtable/struct.MemTable.html

Retrieves all source nodes that have edges pointing to the specified node (reverse edges).

```rust
pub fn get_incoming_sources(&self, id: NodeId) -> &[NodeId]
```

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

### TextIndex::new

Source: https://docs.rs/triviumdb/0.7.0/triviumdb/index/text/struct.TextIndex.html

Constructs a new instance of TextIndex. This is the entry point for creating a text index.

```APIDOC
## TextIndex::new

### Description
Constructs a new instance of TextIndex.

### Method
`new()`

### Returns
- `Self`: A new instance of TextIndex.
```

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

### TextIndex::build() Method

Source: https://docs.rs/triviumdb/0.7.0/triviumdb/index/text/struct.TextIndex.html

Builds the full index, compiling the AC automaton and calculating average document length and frequency base.

```rust
pub fn build(&mut self)
```
Tokens:
Raw