Skip to content
This repository was archived by the owner on Jun 8, 2026. It is now read-only.

DOCS.md

Latest commit

 

History

History
125 lines (90 loc) · 4.35 KB

DOCS.md

File metadata and controls

125 lines (90 loc) · 4.35 KB
Raw

Latha DB System Documentation (v4.0)

Role: Lead Technical Writer & Systems Analyst.

SECTION 1: SYSTEM OVERVIEW

Architecture & Capabilities

Core Engine The heart of Latha DB is a custom Java-based immutable ledger system. It prioritizes data integrity and auditability.

  • .latha (JSON): The primary storage format, human-readable and easy to debug.
  • .latha-bin (Compressed): A compact, binary storage format for efficiency in production environments.

Polyglot Interface Latha DB supports multiple ways to interact with your data:

  • Lisp Mode: The native, powerful S-Expression based query language (e.g., (select :all :from "Table")).
  • SQL Mode: A built-in transpiler that converts standard SQL queries into Lisp commands on the fly, easing adoption.
  • Visual Mode: The "Blueprint" node editor and Graph Visualizer for a no-code/low-code experience.

Deployment

  • Native Image: Compiled via GraalVM for instant startup times, removing the need for a pre-installed JVM on the target machine.
  • Network: Built with a Master-Slave Replication model and a robust Client-Server architecture for scalability.

SECTION 2: THE QUERY REFERENCE (The "Bible")

This section lists every valid command in Latha DB.

1. Data Definition (DDL)

Create Table Define a new table schema.

  • Lisp: (create-table "Name" :columns {"Col" "Type"})
  • SQL: CREATE TABLE Name (Col Type)

Drop Table Remove an existing table and its data.

  • Lisp: (drop-table "Name")
  • SQL: N/A (Use Lisp command)

2. Data Manipulation (DML)

Insert Add new records to a table.

  • Lisp: (insert :into "Users" {"name" "Kisu" "age" 24})
  • SQL: INSERT INTO Users (name, age) VALUES ('Kisu', 24)

Select Retrieve all records from a table.

  • Lisp: (select :all :from "Users")
  • SQL: SELECT * FROM Users

Filter (Where) Retrieve records matching specific criteria.

  • Lisp: (select :all :from "Users" (where (> :age 18)))
  • SQL: SELECT * FROM Users WHERE age > 18

Update Modify existing records.

  • Lisp: (update "Users" (set :age 25) (where (eq :name "Kisu")))
  • SQL: UPDATE Users SET age = 25 WHERE name = 'Kisu'

Delete Remove records from a table.

  • Lisp: (delete :from "Users" (where (< :score 0)))
  • SQL: DELETE FROM Users WHERE score < 0

3. Advanced Analytics

Vector Search (AI) Perform similarity searches on vector embeddings.

  • Lisp: (find-similar :column :vec_data :limit 5)

Graph Path Find connections between nodes in a graph structure.

  • Lisp: (find-path :from "NodeA" :to "NodeB")

Charting Generate visual plots from query results.

  • Lisp: (plot :type :bar :x "Date" :y "Sales" :from "Orders")

SECTION 3: VISUAL TOOLS MANUAL

Studio Features

Query Explorer The main REPL (Read-Eval-Print Loop) interface. It features:

  • Syntax Highlighting: Color-coded text for better readability.
  • Auto-Translate: Type in SQL and see the Lisp equivalent instantly.

Data Visualizer Explore your data relationships visually.

  • Force-Directed Graph: Load a file to see nodes and edges. Interact with the physics engine by dragging nodes or pausing the simulation.
  • Color Coding: Nodes are automatically colored based on their Table type for quick identification.

Visual Builder (Blueprints) A construct-a-query interface.

  • Drag & Drop: Drag nodes like Filter, Select onto the canvas.
  • Wire Connectivity: Connect nodes to build complex logic flows without writing a single line of code.

Analytics Dashboard Visual representation of data trends.

  • Plot Integration: Uses the (plot) command to render charts via JFreeChart.

SECTION 4: DEVELOPER GUIDE (Contributing)

Building & Extending

Build System

  • Standard Fat JAR: mvn clean package
  • Native Windows Executable: mvn -Pnative native:compile (Requires GraalVM)

Project Structure

  • com.lathadb.engine: Core logic and storage engine.
  • com.lathadb.lang: Lisp Parser, AST, and SQL Transpiler.
  • com.lathadb.ui: User Interface code (Swing/FlatLaf).
  • com.lathadb.net: Networking, Server, and Replication logic.

Policy

  • "Human Scalable Code": Code must be understandable by humans. No blind AI pasting without understanding and validation.