Home

AmberDB Technical Wiki & Reference Encyclopedia

Turkce Dokumantasyon | English Documentation

Welcome to the technical reference encyclopedia for AmberDB (Version 5.22.x). AmberDB is a high-performance, schema-driven NoSQL database engine for Perl built on top of Berkeley DB (DB_File), featuring precomputed inverted indexing, ACID-compliant transactions with Strict Two-Phase Locking (Strict 2PL), automatic crash recovery, and intelligent locale-aware text search.

This wiki is organized as an encyclopedic reference dictionary. Each method, architectural concept, configuration flag, and physical file format is documented as an independent, deeply detailed entry with its parameters, return values, Big-O complexity, internal mechanics, and practical input/output examples.

---

Quick Navigation

• Getting Started & Guides: What is AmberDB? | How to Install AmberDB | How to Use AmberDB | Core CRUD Operations
• Core Concepts: Berkeley DB Engine | Table Schema | Global Flags | Table Schema Flags | Directory Structure | File Structure | Repeat Blocks | Auto-Increment ID | ASCII ID | Relational Records | Record Anatomy | JOIN-Free Architecture | Strict 2PL Locking
• Essential Methods: new | config | insert_id | read_id | read_all | modify_id | delete_id | field_fetch | search_table | facet_menu | transact_start | flock_open
• Top Flags: log_owner | use_counter | use_junk | keep_deleted | auto_id | buffer_write | simple | jnktype | keys_only
• File Types: .db | .table | .inx | .fld | .src | .fac | .srt | .slg | .txn | .amberdb | .csv

---

Alphabetical A-Z Index

Letter	Entries
A	array_compare · array_filter · array_pick · array_punch · array_shuffle · array_size · array_sort · array_sublist · array_substr · array_substrno · ASCII ID · auto_id (Flag) · Auto-Increment ID (Concept)
B	Berkeley DB Engine · buffer_delete · buffer_read · buffer_write · buffer_write (Flag)
C	cache_delete · cache_ensure · cache_preload · cache_read · cache_setup · cache_write · check_table · config · convert_tables · CRUD Operations Guide
D	Data Model · deep_copy · delete_id · delete_list · Directory Structure · Disaster Recovery · Disjunctive Faceting · dump
E	exist_id · exist_list · exist_table
F	facet_menu · facet_rules · field_allfltkeys · field_fetch · field_filter · field_fltkeys · File Structure (Extensions) · flock_close · flock_open
G	Global Flags
I	id_type (Flag) · In-Memory Schema Mutation · insert_id · insert_list · Installation Guide · inverse_matrix
J	JOIN-Free Architecture · jnktype (Flag) · Junk Tier Indexing
K	keep_deleted (Flag) · keys_only (Flag)
L	language (Flag) · locale_format_currency · locale_format_date · locale_lc · locale_num2text · locale_sort · locale_to_ascii · locale_uc · log_owner (Flag)
M	modify_id · modify_list
N	new · no_backup (Flag) · no_write (Flag)
P	Packed Binary Index · Phonetic Accent Search
R	RAM-Disk Acceleration · read_all · read_id · read_list · recs_del · recs_get · recs_put · recs_scan · Relational Records · Repeat Blocks · restore
S	search_table · set_datadir · set_fields · set_filters · set_index · set_readall · set_search · set_sort · simple (Flag) · Simple Mode · slug_fetch · slug_read · Strict 2PL Locking
T	Table Schema · Table Schema Flags · table_attr · table_close · table_count · table_create · table_keys · table_lastid · table_read · table_write · transact_commit · transact_end · transact_recover · transact_rollback · transact_start
U	Undo Journal Rollback · Usage Quickstart Guide · use_counter (Flag) · use_junk (Flag)
V	vacuum_table
W	What is AmberDB? Guide

---

Topical Encyclopedia Breakdown

AmberDB Architecture
 Storage Engine (Berkeley DB DB_File Hash)
    Master Data: .db, .del, .aut, .cnt
    Secondary Derived Indexes: .inx, .fld, .src, .fac, .srt, .slg
 Schema Layer (.table, .dbase, in-memory table_attr)
 Concurrency & ACID (Strict 2PL, OS flock, Undo-Journal .txn)
 Indexing Subsystem (8-byte packed Q*/a8*, columnar bitsets, accent normalizer)
 Tiered Storage Subsystem (.jnk cold tier, single-pass hybrid queries)
 Cache Subsystem (RAM-disk tmpfs/ImDisk mirroring, disk buffers)
 Multilingual Engine (AmberDB::Locale: 9 languages, UCA collation, num2text)

0. Getting Started & Guides

• What is AmberDB? — Overview, philosophy, and architecture
• How to Install AmberDB — CPAN, source build, upgrades, and RAM-disks
• How to Use AmberDB — End-to-end practical scenario
• Core CRUD Operations — insert, read, modify, and delete guide

1. Core Architectural Concepts

• Berkeley DB Engine & Advantages
• AmberDB Table Schema
• Global Flags & Configuration
• Table Schema Flags
• Directory Structure & Hierarchy
• File Structure & Extensions
• Repeating Extensible Blocks (Repeat Blocks)
• Auto-Increment ID Allocation
• ASCII ID Architecture & Usage
• Relational Records & Foreign Keys
• Record Anatomy & 0-Index ID Rule
• JOIN-Free Extensible Block Architecture
• 8-Byte Packed Binary Indexing Mechanism
• Strict Two-Phase Locking (Strict 2PL) Concurrency
• Undo-Journal ACID Rollback and Crash Recovery
• Tiered Hot/Cold Storage and Junk Indexing
• Columnar Disjunctive Facet Filtering
• Phonetic Accent Search and Normalization
• 2-Pillar Continuous Disaster Recovery & .amberdb Archiving
• RAM-Disk (tmpfs / ImDisk) Shared Memory Acceleration
• Zero-Migration In-Memory Schema Mutation
• Simple Mode (Schemaless Direct Access)

2. Core CRUD and Table Methods

• new — Instantiates AmberDB instance
• config — Deterministic configuration getter/setter
• set_datadir — Dynamically updates root database path
• insert_id — Inserts single record with auto ID generation
• insert_list — Bulk record insertion pipeline
• modify_id — Updates single record and resyncs indexes
• modify_list — Bulk record update pipeline
• delete_id — Deletes single record (soft or hard delete)
• delete_list — Bulk record deletion pipeline
• read_id — Direct primary key lookup
• read_all — Table scanning with sorting, pagination, and keys_only
• read_list — Order-preserving bulk ID reading
• exist_id — Single record existence check
• exist_list — Bulk record existence query
• exist_table — Physical table/index existence verification
• table_count — Returns total active record count
• table_keys — Returns array of all active record IDs
• table_lastid — Returns highest assigned ID
• table_attr — In-memory dynamic schema attribute manipulation
• table_create — Explicit empty database file initialization

3. Query, Search and Faceted Navigation Methods

• field_fetch — Exact match lookup via inverted .fld index
• field_filter — Compound multi-block AND/OR filtering
• search_table — Full-text keyword search via .src index
• facet_menu — Dynamic multi-dimensional faceted menu generator
• field_fltkeys — Single-block facet key counts
• field_allfltkeys — Multi-block facet aggregation
• facet_rules — Record facet qualification evaluator
• slug_read — Resolves URL slug to record ID
• slug_fetch — Resolves record ID to URL slug

4. Transaction Safety and Concurrency Methods

• transact_start — Begins multi-table ACID transaction
• transact_end — Concludes transaction with auto-rollback on error
• transact_commit — Flushes journal and commits changes
• transact_rollback — Reverts transaction in LIFO order
• transact_recover — Recovers orphaned .txn journals on startup
• flock_open — Acquires table or record-level lock
• flock_close — Releases table or record-level lock

5. Shared Cache, RAM-Disk and Low-Level Access Methods

• cache_setup — Inspects RAM-disk mounting status and diagnostics
• cache_read — Reads record from memory cache with TTL check
• cache_write — Serializes record to RAM-disk cache
• cache_delete — Invalidates single cache entry or whole table
• cache_preload — Preloads table data atomically to RAM-disk
• cache_ensure — Validates cache presence and auto-populates
• buffer_write — Writes structured records to staging buffer
• buffer_read — Reads staged records from buffer
• buffer_delete — Removes disk buffer file
• recs_scan — Sequential C-level seq table scanning
• recs_get — Direct raw record fetch from open handle
• recs_put — Direct raw record write to open handle
• recs_del — Direct raw record deletion from open handle

6. Multilingual Locale and Helper Methods

• locale_uc — Language-aware uppercase conversion
• locale_lc — Language-aware lowercase conversion
• locale_sort — Unicode Collation Algorithm (UCA) sorting
• locale_to_ascii — Transliterates accented text to plain ASCII
• locale_num2text — Spell out numbers as words (invoices/checks)
• locale_format_currency — ISO currency symbol and decimal formatting
• locale_format_date — Localized date and time formatting
• array_sort — Versatile scalar and AoA matrix sorting engine
• array_punch — Subtracts array elements with deduplication
• array_filter — Fast in-memory array filtering via predicate
• array_sublist — Splits arrays into fixed-size chunks
• deep_copy — Recursively clones nested Perl data structures

7. Maintenance, Backup and Diagnostic Tools

• dump — Creates compressed portable .amberdb native archive
• restore — Restores .amberdb archive with SHA-256 validation
• set_index — Rebuilds all secondary and primary indexes
• convert_tables — Scans and updates entire database indexes
• vacuum_table — Compacts table and optimizes Berkeley DB hash pages
• check_table — Diagnostic integrity check for tables and indexes

8. Configuration and Schema Flags

• log_owner — User audit trail logging (.aut)
• use_counter — High-concurrency hit/view counter store (.cnt)
• use_junk — Hot/cold two-tier indexing enablement
• keep_deleted — Soft deletion recycle bin archive (.del)
• auto_id — Auto-incrementing 64-bit ID generation
• buffer_write — Disk staging buffer write mode
• simple — Schemaless flat-store direct access mode
• no_write — Read-only protection mode
• no_backup — Disables continuous CSV WAL logging
• jnktype — Tier query selection ('A', 'B', 'AB', 'BA')
• keys_only — Memory-efficient scalar ID pipeline
• id_type — ID format specification ('numeric' or 'ascii')
• language — Active locale engine language code

9. Physical File Formats and Directory Layout

• .db — Primary Berkeley DB document hash table
• .table — Table schema definition file
• .dbase — Database group configuration file
• .inx — 8-byte packed binary primary index
• .fld — Inverted exact match secondary index
• .src — Inverted full-text search index
• .fac — Columnar facet bitset index
• .srt — Monotonic binary pre-sorted index
• .slg — Bidirectional URL slug mapping file
• .unq — Bidirectional dictionary & uniqueness index
• .del — Soft-deleted records archive file
• .aut — User chronological audit trail log
• .cnt — View and hit counter store
• .txn — Active transaction undo-journal file
• .amberdb — Compressed native database archive
• .csv — Daily continuous WAL audit stream
• .cache — RAM-disk shared cache file
• .tmp — Disk buffer staging file