# sql-rs Specification
## Overview
sql-rs is a lightweight, embedded database written in Rust that combines traditional relational database features with vector database capabilities, inspired by SQLite and Chroma.
## Core Features
### 1. Traditional Database
- **Storage Engine**: B-tree based key-value store with ACID properties
- **Data Types**: Integer, Float, Text, Blob, Boolean
- **Indexing**: Primary key and secondary indexes
- **Transactions**: Basic transaction support with rollback
- **Query Language**: Simple SQL-like query interface
### 2. Vector Database
- **Vector Storage**: Store high-dimensional embeddings (float arrays)
- **Similarity Search**: Cosine similarity, Euclidean distance, dot product
- **Indexing**: HNSW (Hierarchical Navigable Small World) for fast approximate nearest neighbor search
- **Metadata**: Associate metadata with vectors for filtering
### 3. CLI Interface
- `sql-rs create <db_path>` - Create new database
- `sql-rs query <db_path> <sql>` - Execute SQL query
- `sql-rs insert <db_path> --table <name> --data <json>` - Insert data
- `sql-rs vector add <db_path> --collection <name> --vector <json> --metadata <json>` - Add vector
- `sql-rs vector search <db_path> --collection <name> --vector <json> --top-k <n>` - Search similar vectors
- `sql-rs info <db_path>` - Show database information
## Architecture
### Storage Layer
- **Page-based storage**: Fixed-size pages (4KB default)
- **B-tree indexes**: For efficient key lookups
- **WAL (Write-Ahead Logging)**: For durability and crash recovery
### Vector Layer
- **Vector collections**: Separate namespaces for different vector types
- **HNSW index**: For approximate nearest neighbor search
- **Metadata store**: B-tree based metadata storage linked to vectors
### Query Engine
- **Parser**: Simple SQL parser for basic operations
- **Executor**: Query execution engine
- **Optimizer**: Basic query optimization
## File Format
- Single file database (like SQLite)
- Header: Magic bytes, version, page size, metadata
- Pages: Data pages, index pages, vector pages
- WAL file: Separate write-ahead log
## Performance Goals
- Insert: >10k rows/sec
- Query: <10ms for indexed lookups
- Vector search: <100ms for 1M vectors (approximate)
- Memory footprint: <50MB for typical workloads
## License
Copyright 2025 SQL-RS Contributors
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.