Struct Database 

pub struct Database { /* private fields */ }

The main database object.

Implementations

impl Database

pub fn list_catalogs(&self) -> Result<Vec<CatalogInfo>>

Catalog 一覧を取得する。

pub fn get_catalog(&self, name: &str) -> Result<CatalogInfo>

Catalog を取得する。

pub fn list_namespaces(&self, catalog_name: &str) -> Result<Vec<NamespaceInfo>>

Namespace 一覧を取得する。

pub fn get_namespace( &self, catalog_name: &str, namespace_name: &str, ) -> Result<NamespaceInfo>

Namespace を取得する。

pub fn list_tables( &self, catalog_name: &str, namespace_name: &str, ) -> Result<Vec<TableInfo>>

テーブル一覧を取得する。

pub fn list_tables_simple(&self) -> Result<Vec<TableInfo>>

デフォルト catalog/namespace のテーブル一覧を取得する。

pub fn get_table_info( &self, catalog_name: &str, namespace_name: &str, table_name: &str, ) -> Result<TableInfo>

テーブル情報を取得する。

pub fn get_table_info_simple(&self, table_name: &str) -> Result<TableInfo>

デフォルト catalog/namespace のテーブル情報を取得する。

pub fn get_table_info_cached( &self, catalog_name: &str, namespace_name: &str, table_name: &str, ) -> Result<CachedTableInfo>

テーブル情報をキャッシュから取得する（キャッシュミス時は DB ルックアップ）。

パフォーマンス最適化のため、キャッシュを使用してテーブルメタデータを取得する。 DDL 操作（テーブル作成/削除など）が発生するとキャッシュは自動的に無効化される。

pub fn list_indexes( &self, catalog_name: &str, namespace_name: &str, table_name: &str, ) -> Result<Vec<IndexInfo>>

インデックス一覧を取得する。

pub fn list_indexes_simple(&self, table_name: &str) -> Result<Vec<IndexInfo>>

デフォルト catalog/namespace のインデックス一覧を取得する。

pub fn get_index_info( &self, catalog_name: &str, namespace_name: &str, table_name: &str, index_name: &str, ) -> Result<IndexInfo>

インデックス情報を取得する。

pub fn get_index_info_simple( &self, table_name: &str, index_name: &str, ) -> Result<IndexInfo>

デフォルト catalog/namespace のインデックス情報を取得する。

pub fn create_catalog( &self, request: CreateCatalogRequest, ) -> Result<CatalogInfo>

Catalog を作成する。

Examples

use alopex_embedded::{CreateCatalogRequest, Database};

let db = Database::new();
let catalog = db.create_catalog(CreateCatalogRequest::new("main")).unwrap();
assert_eq!(catalog.name, "main");

pub fn delete_catalog(&self, name: &str, force: bool) -> Result<()>

Catalog を削除する。

pub fn create_namespace( &self, request: CreateNamespaceRequest, ) -> Result<NamespaceInfo>

Namespace を作成する。

Examples

use alopex_embedded::{CreateCatalogRequest, CreateNamespaceRequest, Database};

let db = Database::new();
db.create_catalog(CreateCatalogRequest::new("main")).unwrap();
let namespace = db
    .create_namespace(CreateNamespaceRequest::new("main", "analytics"))
    .unwrap();
assert_eq!(namespace.catalog_name, "main");
assert_eq!(namespace.name, "analytics");

pub fn delete_namespace( &self, catalog_name: &str, namespace_name: &str, force: bool, ) -> Result<()>

Namespace を削除する。

pub fn create_table(&self, request: CreateTableRequest) -> Result<TableInfo>

テーブルを作成する。

Examples

use alopex_embedded::{
    ColumnDefinition, CreateCatalogRequest, CreateNamespaceRequest, CreateTableRequest,
    Database,
};
use alopex_sql::ast::ddl::DataType;

let db = Database::new();
db.create_catalog(CreateCatalogRequest::new("default")).unwrap();
db.create_namespace(CreateNamespaceRequest::new("default", "default"))
    .unwrap();

let schema = vec![ColumnDefinition::new("id", DataType::Integer)];
let table = db
    .create_table(CreateTableRequest::new("users").with_schema(schema))
    .unwrap();
assert_eq!(table.name, "users");

pub fn create_table_simple( &self, name: &str, schema: Vec<ColumnDefinition>, ) -> Result<TableInfo>

デフォルト catalog/namespace のテーブルを作成する。

pub fn delete_table( &self, catalog_name: &str, namespace_name: &str, table_name: &str, ) -> Result<()>

テーブルを削除する。

pub fn delete_table_simple(&self, name: &str) -> Result<()>

デフォルト catalog/namespace のテーブルを削除する。

impl Database

pub fn open_with_config(config: EmbeddedConfig) -> Result<Self>

構成付きでデータベースを開く（カラムナー機能を初期化）。

pub fn storage_mode(&self) -> StorageMode

現在のカラムナーストレージモードを返す。

pub fn write_columnar_segment( &self, table: &str, batch: RecordBatch, ) -> Result<u64>

カラムナーセグメントを書き込む。

pub fn write_columnar_segment_with_config( &self, table: &str, batch: RecordBatch, config: SegmentConfigV2, ) -> Result<u64>

カラムナーセグメントを書き込む（構成上書き）。

pub fn read_columnar_segment( &self, table: &str, segment_id: u64, columns: Option<&[&str]>, ) -> Result<Vec<RecordBatch>>

カラムナーセグメントを読み取る（カラム名指定オプション付き）。

pub fn in_memory_usage(&self) -> Option<u64>

InMemory モード時のメモリ使用量を返す。Disk モードでは None。

pub fn open_in_memory_with_limit(limit: usize) -> Result<Self>

メモリ上限付きでインメモリ DB を開く。

pub fn resolve_table_id(&self, table: &str) -> Result<u32>

テーブル名から内部 ID を解決する。

pub fn scan_columnar_segment( &self, segment_id: &str, ) -> Result<Vec<Vec<SqlValue>>>

Scan a columnar segment by string ID.

The segment ID format is {table_id}:{segment_id} (e.g., “12345:1”). Returns rows as a vector of SqlValue vectors.

pub fn scan_columnar_segment_batches( &self, segment_id: &str, ) -> Result<Vec<RecordBatch>>

Scan a columnar segment by string ID, returning RecordBatches for streaming (FR-7).

This method returns raw RecordBatch objects, allowing the caller to iterate over rows without materializing all data upfront. Use this for large datasets where streaming is required.

The segment ID format is {table_id}:{segment_id} (e.g., “12345:1”).

pub fn scan_columnar_segment_streaming( &self, segment_id: &str, ) -> Result<ColumnarRowIterator>

Create a streaming row iterator over a columnar segment (FR-7).

This returns a ColumnarRowIterator that yields rows one at a time from the underlying RecordBatches, without materializing all rows upfront.

The segment ID format is {table_id}:{segment_id} (e.g., “12345:1”).

pub fn get_columnar_segment_stats( &self, segment_id: &str, ) -> Result<ColumnarSegmentStats>

Get statistics for a columnar segment by string ID.

The segment ID format is {table_id}:{segment_id} (e.g., “12345:1”).

pub fn list_columnar_segments(&self) -> Result<Vec<String>>

List all columnar segments.

Returns segment IDs in the format {table_id}:{segment_id}.

pub fn create_columnar_index( &self, segment_id: &str, column: &str, index_type: ColumnarIndexType, ) -> Result<()>

Create a columnar index for a segment/column.

pub fn list_columnar_indexes( &self, segment_id: &str, ) -> Result<Vec<ColumnarIndexInfo>>

List columnar indexes for a segment.

pub fn drop_columnar_index(&self, segment_id: &str, column: &str) -> Result<()>

Drop a columnar index for a segment/column.

pub fn flush_in_memory_segment_to_file( &self, table: &str, segment_id: u64, path: &Path, ) -> Result<()>

InMemory モードのセグメントをファイルへフラッシュする。

pub fn flush_in_memory_segment_to_kvs( &self, table: &str, segment_id: u64, ) -> Result<u64>

InMemory モードのセグメントを KVS へフラッシュする。

pub fn flush_in_memory_segment_to_alopex( &self, table: &str, segment_id: u64, writer: &mut AlopexFileWriter, ) -> Result<u32>

InMemory モードのセグメントを .alopex ファイルへフラッシュする。

impl Database

pub fn execute_sql(&self, sql: &str) -> Result<SqlResult>

SQL を実行する（auto-commit）。

• DDL/DML は ReadWrite トランザクションで実行し、成功時に自動コミットする。
• SELECT は ReadOnly トランザクションで実行する。

Examples

use alopex_embedded::Database;
use alopex_sql::ExecutionResult;

let db = Database::new();
let result = db.execute_sql(
    "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT);",
).unwrap();
assert!(matches!(result, ExecutionResult::Success));

pub fn execute_sql_with_rows<F, R>( &self, sql: &str, f: F, ) -> Result<StreamingQueryResult<R>>

where F: FnOnce(StreamingRows<'_>) -> Result<R>,

Execute SQL with callback-based streaming for SELECT queries (FR-7).

This method provides true streaming by keeping the transaction alive during row iteration. The callback receives a StreamingRows that yields rows on-demand from storage.

Type Parameters

• F - Callback function that processes the streaming rows
• R - Return type from the callback

Examples

use alopex_embedded::Database;

let db = Database::new();
db.execute_sql("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT);").unwrap();
db.execute_sql("INSERT INTO users (id, name) VALUES (1, 'Alice'), (2, 'Bob');").unwrap();

// Process rows with streaming - transaction stays alive during callback
let result = db.execute_sql_with_rows("SELECT * FROM users;", |mut rows| {
    let mut names = Vec::new();
    while let Ok(Some(row)) = rows.next_row() {
        if let Some(alopex_sql::storage::SqlValue::Text(name)) = row.get(1) {
            names.push(name.clone());
        }
    }
    Ok(names)
}).unwrap();

pub fn execute_sql_streaming(&self, sql: &str) -> Result<SqlStreamingResult>

Execute SQL and return a streaming result for SELECT queries (FR-7).

This method returns a SqlStreamingResult that contains an iterator for query results, enabling true streaming output without materializing all rows upfront.

Note

Only single SELECT statements are supported for streaming. Multi-statement SQL or non-SELECT statements fall back to the standard execution path.

Examples

use alopex_embedded::{Database, SqlStreamingResult};

let db = Database::new();
db.execute_sql("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT);").unwrap();
db.execute_sql("INSERT INTO users (id, name) VALUES (1, 'Alice');").unwrap();

let result = db.execute_sql_streaming("SELECT * FROM users;").unwrap();
if let SqlStreamingResult::Query(mut iter) = result {
    while let Ok(Some(row)) = iter.next_row() {
        println!("{:?}", row);
    }
}

impl Database

pub fn open(path: &Path) -> Result<Self>

Opens a database at the specified path.

pub fn new() -> Self

Creates a new, purely in-memory (transient) database.

pub fn open_in_memory() -> Result<Self>

Opens a database in in-memory mode with default options.

pub fn open_in_memory_with_options(opts: DatabaseOptions) -> Result<Self>

Opens a database in in-memory mode with the given options.

pub fn open_with_uri(uri: &str) -> Result<Self>

Opens a database from a URI string.

Supported URI schemes:

• file://path or bare path: Local filesystem
• s3://bucket/prefix: S3-compatible storage (requires s3 feature)

Example

// Local path
let db = Database::open_with_uri("/path/to/db")?;

// S3 URI (requires s3 feature and credentials)
let db = Database::open_with_uri("s3://my-bucket/data")?;

pub fn table_info_cache_epoch(&self) -> u64

Returns the current table info cache epoch.

pub fn get_cached_table_info( &self, catalog_name: &str, namespace_name: &str, table_name: &str, ) -> Option<CachedTableInfo>

Retrieves cached table info if available and epoch matches.

pub fn cache_table_info( &self, catalog_name: &str, namespace_name: &str, table_name: &str, info: CachedTableInfo, )

Stores table info in the cache.

pub fn invalidate_table_info_cache(&self)

Invalidates the table info cache (called on DDL operations).

pub fn flush(&self) -> Result<()>

Flushes the current in-memory data to an SSTable on disk (beta).

pub fn file_format_version(&self) -> FileVersion

Returns the file format version supported by the embedded engine.

pub fn memory_usage(&self) -> Option<MemoryStats>

Returns current memory usage statistics (in-memory KV only).

pub fn persist_to_disk(&self, wal_path: &Path) -> Result<()>

Persists the current in-memory database to disk atomically.

wal_path は「データディレクトリ」として扱う（file-mode）。

pub fn clone_to_memory(&self) -> Result<Self>

Creates a fully in-memory clone of the current database.

pub fn clear(&self) -> Result<()>

Clears all data while keeping the database usable.

pub fn set_memory_limit(&self, bytes: Option<usize>)

Updates the memory limit in bytes for the underlying in-memory store.

pub fn snapshot(&self) -> Vec<(Key, Vec<u8>)>

Returns a read-only snapshot of all key-value pairs.

pub fn create_hnsw_index(&self, name: &str, config: HnswConfig) -> Result<()>

HNSW インデックスを作成し、永続化する。

pub fn drop_hnsw_index(&self, name: &str) -> Result<()>

HNSW インデックスを削除する。

pub fn get_hnsw_stats(&self, name: &str) -> Result<HnswStats>

HNSW 統計情報を取得する。

pub fn compact_hnsw_index(&self, name: &str) -> Result<CompactionResult>

HNSW インデックスをコンパクションし、結果を返す。

pub fn search_hnsw( &self, name: &str, query: &[f32], k: usize, ef_search: Option<usize>, ) -> Result<(Vec<HnswSearchResult>, HnswSearchStats)>

HNSW インデックスに検索を行う。

pub fn create_blob_writer( &self, path: &Path, total_len: u64, chunk_size: Option<u32>, ) -> Result<LargeValueWriter>

Creates a chunked large value writer for opaque blobs (beta).

pub fn create_typed_writer( &self, path: &Path, type_id: u16, total_len: u64, chunk_size: Option<u32>, ) -> Result<LargeValueWriter>

Creates a chunked large value writer for typed payloads (beta).

pub fn open_large_value(&self, path: &Path) -> Result<LargeValueReader>

Opens a chunked large value reader (beta). Kind/type is read from the file header.

pub fn begin(&self, mode: TxnMode) -> Result<Transaction<'_>>

Begins a new transaction.

Trait Implementations

impl Default for Database

fn default() -> Self

Returns the “default value” for a type.