AmberDB
view release on metacpan or search on metacpan
lib/AmberDB.pm view on Meta::CPAN
}
my $is_txn = ( $self->{_txn} && $self->{_txn}->{active} ) ? 1 : 0;
my $is_async_write = ( $use_ramdisk == 4 && !$is_txn );
my $target_file = ( ( $is_async_write || $use_ramdisk == 3 ) && $ramdisk_path ) ? "$ramdisk_path.$self->{db_ext}" : $file_path;
# open table with exclusive lock
my $db_handle = $self->table_write($target_file);
unless ($db_handle) {
return;
}
# check record id.
my $has_manual_id = ( defined $rid && $rid ne '' && $rid ne '0' );
$rid = $self->table_autoid( $tableid, ( $has_manual_id ? $rid : undef ) );
unless ($rid) {
$self->table_close($target_file);
$self->transact_error( $target_file, "Invalid or missing record ID" );
return;
}
if ($has_manual_id) {
my $junk;
my $k = $self->utf_encode("$rid");
if ( $self->{_db}->{$target_file} && $self->{_db}->{$target_file}->get( $k, $junk ) == 0 ) {
$self->table_close($target_file);
$self->transact_error( $target_file, "Duplicate ID: $rid" );
return;
}
}
# Transaction journal & record locking (Lock before write - Strict 2PL)
$self->flock_open( $tableid, "write", $rid );
if ($is_txn) {
$self->{_txn}->{locks}->{"${tableid}_${rid}"} = 1;
}
# Validate and normalize field values according to schema blocks
@record = $self->enc_validate( $tableid, \@record );
# Validate unique constraints across blocks
my ( $unq_ok, $unq_err ) = $self->unique_check( $table_path, $table_info, $rid, \@record );
if ( !$unq_ok ) {
$self->table_close($target_file);
unless ($is_txn) { $self->flock_close( $tableid, $rid ); }
$self->transact_error( $target_file, $unq_err // "Unique constraint violation" );
return;
}
$self->recs_put( [ $target_file, $tableid ], [ $rid, @record ] );
if ($is_async_write) {
$self->ramdisk_mark_dirty( $file_path, $rid, 1 );
}
elsif ( $use_ramdisk == 4 && $is_txn ) {
$self->ramdisk_unmark_dirty( $file_path, $rid );
}
$self->table_close($target_file);
unless ($is_txn) { $self->flock_close( $tableid, $rid ); }
# for index actions and backup
@record = ( $rid, @record );
# Invalidate cached table keys and count in memory
$self->set_cache( $tableid, 'keys', undef );
$self->set_cache( $tableid, 'count', undef );
unless ( $is_async_write || $use_ramdisk == 3 ) {
$self->recs_back( "add", $tableid, \@record );
}
if ( $self->config('use_simple') || ( $table_info && $table_info->{use_simple} ) ) {
$self->_invalidate_child_ramdisk_tables($tableid);
return $rid;
}
# update .inx and secondary indexes
my @batch = ( \@record );
my $idx_path = ( $use_ramdisk && $ramdisk_path ) ? $ramdisk_path : $table_path;
# 1. Base stream: unconditionally write all records
$self->records_add( $idx_path, $table_info, $tableid, [$rid] );
$self->search_add( $idx_path, $table_info, $tableid, \@batch );
$self->match_add( $idx_path, $table_info, \@batch );
$self->sort_add( $idx_path, $table_info, \@batch );
$self->unique_add( $idx_path, $table_info, \@batch );
$self->slug_add( $idx_path, $table_info, $tableid, \@batch );
$self->suggest_add( $idx_path, $table_info, $tableid, \@batch );
# 2. Tiered stream (A: Aktif, B: Pasif/Junk)
if ( $table_info->{use_junk} ) {
my $is_junk = $self->junk_rules( $table_info, @record );
my $tier = $is_junk ? 'B' : 'A';
$self->records_add( $idx_path, $table_info, $tableid, [$rid], $tier );
$self->search_add( $idx_path, $table_info, $tableid, \@batch, $tier );
$self->match_add( $idx_path, $table_info, \@batch, $tier );
$self->sort_add( $idx_path, $table_info, \@batch, $tier ) if $table_info->{sort_block};
if ( !$is_junk ) {
$self->facet_add( $idx_path, $table_info, \@batch );
}
}
elsif ( $table_info->{use_facet} ) {
$self->facet_add( $idx_path, $table_info, \@batch );
}
$self->auth_write( $tableid, $table_path, "add", $rid ) unless ( $is_async_write || $use_ramdisk == 3 );
$self->_invalidate_child_ramdisk_tables($tableid);
return $rid;
}
# for bulk record inserting
# Note: Bulk operations (insert_list, modify_list, delete_list) do NOT use transactions (_txn_log).
# my $statu_hash = $adb->insert_list($tableid, @records);
# ------------------------------------------------
sub insert_list {
my ( $self, $tableid, @records ) = @_;
lib/AmberDB.pm view on Meta::CPAN
$self->_invalidate_child_ramdisk_tables($tableid) if @batch;
return \%statu unless @batch;
return \%statu if $is_simple;
my $idx_path = ( $use_ramdisk && $ramdisk_path ) ? $ramdisk_path : $table_path;
# 1. Base stream (All records)
$self->records_add( $idx_path, $table_info, $tableid, \@new_rids );
$self->search_add( $idx_path, $table_info, $tableid, \@batch );
$self->match_add( $idx_path, $table_info, \@batch );
$self->sort_add( $idx_path, $table_info, \@batch );
# 2. Tiered stream (A: Aktif, B: Pasif/Junk)
if ( $table_info->{use_junk} ) {
my ( @active_batch, @junk_batch, @active_rids, @junk_rids );
for my $rec (@batch) {
if ( $self->junk_rules( $table_info, @$rec ) ) {
push @junk_batch, $rec;
push @junk_rids, $rec->[0];
}
else {
push @active_batch, $rec;
push @active_rids, $rec->[0];
}
}
if (@active_batch) {
$self->records_add( $idx_path, $table_info, $tableid, \@active_rids, 'A' );
$self->search_add( $idx_path, $table_info, $tableid, \@active_batch, 'A' );
$self->match_add( $idx_path, $table_info, \@active_batch, 'A' );
$self->sort_add( $idx_path, $table_info, \@active_batch, 'A' ) if $table_info->{sort_block};
$self->facet_add( $idx_path, $table_info, \@active_batch ) if $table_info->{use_facet};
}
if (@junk_batch) {
$self->records_add( $idx_path, $table_info, $tableid, \@junk_rids, 'B' );
$self->search_add( $idx_path, $table_info, $tableid, \@junk_batch, 'B' );
$self->match_add( $idx_path, $table_info, \@junk_batch, 'B' );
$self->sort_add( $idx_path, $table_info, \@junk_batch, 'B' ) if $table_info->{sort_block};
}
}
elsif ( $table_info->{use_facet} ) {
$self->facet_add( $idx_path, $table_info, \@batch );
}
if ($has_unique) {
$self->unique_add( $idx_path, $table_info, \@batch );
}
$self->slug_add( $idx_path, $table_info, $tableid, \@batch );
$self->suggest_add( $idx_path, $table_info, $tableid, \@batch );
unless ($is_async_write) {
if ( $table_info->{log_owner} ) {
foreach my $rec (@batch) {
$self->auth_write( $tableid, $table_path, "add", $rec->[0] );
}
}
unless ( $self->config('no_backup') || $table_info->{no_backup} ) {
$self->recs_back( "add", $tableid, @batch );
}
}
return \%statu;
}
# Replace the DB record with new data.
# ------------------------------------------------
sub update_id {
my ( $self, $tableid, $rid, @record ) = @_;
# Perform the checks.
$tableid or return;
if ( ref($rid) eq 'HASH' && !@record ) {
if ( $self->schema_matches_hash( $tableid, $rid ) ) {
my $h = { %$rid };
$rid = $h->{id} // $h->{ID};
@record = ($h);
}
else {
my $h = { %$rid };
$rid = delete $h->{id} // delete $h->{ID};
@record = ($h);
}
}
$rid = $self->id_check( $tableid, $rid );
$rid or return;
# Deflate ONLY if table has a schema AND hash matches schema
if ( @record && ref($record[0]) eq 'HASH' ) {
if ( $self->schema_matches_hash( $tableid, $record[0] ) ) {
my $h = { %{ $record[0] } };
$h->{id} //= $rid;
my $def = $self->deflate( $tableid, $h );
if ( ref($def) eq 'ARRAY' ) {
@record = ( scalar(@$def) > 1 ) ? @{$def}[ 1 .. $#$def ] : ();
}
}
}
my $table_info = $self->table_info($tableid);
(undef, @record) = $self->repeat_fields( $table_info, $rid, @record );
my $table_path = $self->table_path($tableid);
my $file_path = "$table_path.$self->{db_ext}";
# Write authority cancelled.
$self->config('no_write')
and do { $self->transact_error( $file_path, "No authority to write to the file" ); return; };
# Transaction journal & record locking (Lock BEFORE reading/modifying - Strict 2PL)
my $is_txn = ( $self->{_txn} && $self->{_txn}->{active} ) ? 1 : 0;
$self->flock_open( $tableid, "write", $rid );
if ($is_txn) {
$self->{_txn}->{locks}->{"${tableid}_${rid}"} = 1;
}
lib/AmberDB.pm view on Meta::CPAN
if ( $use_ramdisk == 3 && $ram_file ) {
$self->table_write($ram_file)
or do {
unless ($is_txn) { $self->flock_close( $tableid, $rid ); }
$self->transact_error( $ram_file, "$ram_file can't open" );
return;
};
}
# Perform record check (exists or not)
if ( ( $is_async_write || $use_ramdisk == 3 ) && $ram_file && -e $ram_file ) {
my $rh = $self->recs_get( $ram_file, $rid );
$old_record = $rh ? $rh->{$rid} : undef;
}
unless ( defined $old_record || $use_ramdisk == 3 ) {
my $rh = $self->recs_get( $file_path, $rid );
$old_record = $rh ? $rh->{$rid} : undef;
}
if ( !$table_info->{force} ) {
if ( !defined $old_record ) {
$self->table_close($file_path) unless ( $is_async_write || $use_ramdisk == 3 );
$self->table_close($ram_file) if ( $use_ramdisk == 3 && $ram_file );
unless ($is_txn) { $self->flock_close( $tableid, $rid ); }
$self->transact_error( $file_path, "Record not exist: $rid" );
return;
}
}
# Validate and normalize field values according to schema blocks
@record = $self->enc_validate( $tableid, \@record );
# Validate unique constraints across blocks
my ( $unq_ok, $unq_err ) = $self->unique_check( $table_path, $table_info, $rid, \@record );
if ( !$unq_ok ) {
$self->table_close($file_path) unless ( $is_async_write || $use_ramdisk == 3 );
$self->table_close($ram_file) if ( $use_ramdisk == 3 && $ram_file );
unless ($is_txn) { $self->flock_close( $tableid, $rid ); }
$self->transact_error( $file_path, $unq_err // "Unique constraint violation" );
return;
}
# Perform the record operation
$self->recs_put( [ $target_file, $tableid ], [ $rid, @record ] );
if ($is_async_write) {
$self->ramdisk_mark_dirty( $file_path, $rid, 2 );
}
elsif ( $use_ramdisk == 4 && $is_txn ) {
$self->ramdisk_unmark_dirty( $file_path, $rid );
}
$self->table_close($file_path) unless ( $is_async_write || $use_ramdisk == 3 );
$self->table_close($ram_file) if $ram_file;
unless ($is_txn) { $self->flock_close( $tableid, $rid ); }
# Cache invalidate
$self->clear_cache($tableid, $rid);
my @new_rec = ( $rid, @record );
# text backup record.
unless ( $is_async_write || $use_ramdisk == 3 ) {
$self->recs_back( "edit", $tableid, \@new_rec )
or cluck "[DB_TIE] Backup error (edit). $tableid\n";
}
if ( $self->config('use_simple') || ( $table_info && $table_info->{use_simple} ) ) {
$self->_invalidate_child_ramdisk_tables($tableid);
return $rid;
}
my @old_rec = $old_record ? ( $rid, $self->db_decode($old_record) ) : ($rid);
# Index update (search, match, facet, sort)
my @pairs = ( [ $rid, \@old_rec, \@new_rec ] );
my $idx_path = ( $use_ramdisk && $ramdisk_path ) ? $ramdisk_path : $table_path;
# 1. Base stream unconditional index updates
$self->search_modify( $idx_path, $table_info, $tableid, \@pairs );
$self->match_modify( $idx_path, $table_info, \@pairs );
# 2. Tiered stream updates
if ( $table_info->{use_junk} ) {
$self->junk_transition( $idx_path, $table_info, $tableid, \@pairs );
}
elsif ( $table_info->{use_facet} ) {
$self->facet_modify( $idx_path, $table_info, \@pairs );
}
$self->sort_modify( $idx_path, $table_info, \@pairs );
$self->unique_modify( $idx_path, $table_info, \@pairs );
$self->slug_modify( $idx_path, $table_info, $tableid, \@pairs );
$self->suggest_add( $idx_path, $table_info, $tableid, [ \@new_rec ] );
# Authorization
$self->auth_write( $tableid, $table_path, "edit", $rid ) unless ( $is_async_write || $use_ramdisk == 3 );
$self->_invalidate_child_ramdisk_tables($tableid);
return 1;
}
# List record modify.
# Note: Bulk operations (insert_list, modify_list, delete_list) do NOT use transactions (_txn_log).
# ------------------------------------------------
sub update_list {
my ( $self, $tableid, @records ) = @_;
local $self->{_no_txn} = 1;
$tableid or return {};
scalar @records or return {};
# Deflate ONLY if table has a schema and records match schema
my $should_deflate = 0;
if ( $self->has_schema($tableid) ) {
my $first_rec = ( @records == 1 && ref($records[0]) eq 'ARRAY' && @{$records[0]} && ref($records[0]->[0]) eq 'HASH' )
? $records[0]->[0]
: ( ref($records[0]) eq 'HASH' ? $records[0] : ( ( @records > 1 && ref($records[1]) eq 'HASH' ) ? $records[1] : undef ) );
if ( $first_rec && $self->schema_matches_hash( $tableid, $first_rec ) ) {
$should_deflate = 1;
lib/AmberDB.pm view on Meta::CPAN
}
my $new_record = [ $rid, @data ];
if ($has_repeat) {
$new_record = [ $self->repeat_fields( $table_info, @$new_record ) ];
}
push @records_to_put, $new_record;
$self->clear_cache( $tableid, $rid );
$statu{$rid} = 1;
my @old_rec = $old_raw ? ( $rid, $self->db_decode($old_raw) ) : ($rid);
my @new_rec = @$new_record;
push @pairs, [ $rid, \@old_rec, \@new_rec ];
}
if (@records_to_put) {
$self->recs_put( [ $target_file, $tableid ], @records_to_put );
if ($is_async_write) {
foreach my $rec (@records_to_put) {
$self->ramdisk_mark_dirty( $file_path, $rec->[0], 2 );
}
}
elsif ( $use_ramdisk == 4 && $is_txn ) {
foreach my $rec (@records_to_put) {
$self->ramdisk_unmark_dirty( $file_path, $rec->[0] );
}
}
}
$self->table_close($file_path);
$self->table_close($ram_file) if $ram_file;
return \%statu unless @pairs;
return \%statu if $is_simple;
my $idx_path = ( $use_ramdisk && $ramdisk_path ) ? $ramdisk_path : $table_path;
# Phase 2: bulk index updates
# 1. Base stream unconditional index updates
$self->search_modify( $idx_path, $table_info, $tableid, \@pairs );
$self->match_modify( $idx_path, $table_info, \@pairs );
# 2. Tiered stream updates
if ( $table_info->{use_junk} ) {
$self->junk_transition( $idx_path, $table_info, $tableid, \@pairs );
}
elsif ( $table_info->{use_facet} ) {
$self->facet_modify( $idx_path, $table_info, \@pairs );
}
$self->sort_modify( $idx_path, $table_info, \@pairs );
$self->unique_modify( $idx_path, $table_info, \@pairs );
$self->slug_modify( $idx_path, $table_info, $tableid, \@pairs );
if ( $table_info->{log_owner} && !$is_async_write ) {
foreach my $pair (@pairs) {
$self->auth_write( $tableid, $table_path, "edit", $pair->[0] );
}
}
unless ( $is_async_write || $self->config('no_backup') || $table_info->{no_backup} ) {
$self->recs_back( "edit", $tableid, map { $_->[2] } @pairs );
}
return \%statu;
}
# Standard SQL/CRUD aliases
sub modify_id { shift->update_id(@_) }
sub modify_list { shift->update_list(@_) }
# Updates a field value in an existing record.
# Supports updating fixed schema blocks:
# $adb->update_field($table, $rid, "price", 1750)
# $adb->update_field($table, $rid, block => "price", 1750)
# Supports updating repeating child items by 'id' or 'pos':
# $adb->update_field($table, $rid, id => 202, $new_item)
# $adb->update_field($table, $rid, pos => 0, $new_item)
# ------------------------------------------------
sub update_field {
my $self = shift;
my $tableid = shift;
my $rid = shift;
$tableid or return;
$rid = $self->id_check( $tableid, $rid );
$rid or return;
my ( $target_spec, $new_val );
if ( @_ == 3 && !ref($_[0]) ) {
my ( $k, $v, $val ) = @_;
$target_spec = { $k => $v };
$new_val = $val;
}
elsif ( @_ == 2 ) {
( $target_spec, $new_val ) = @_;
if ( !ref($target_spec) ) {
$target_spec = { block => $target_spec };
}
}
else {
return;
}
my $table_info = $self->table_info($tableid);
my $rep_start = $table_info->{repeat_start};
if ( !defined $rep_start && $table_info->{blocks} ) {
for my $i ( 0 .. $#{ $table_info->{blocks} } ) {
my $b = $table_info->{blocks}->[$i];
if ( ref($b) eq 'HASH' && defined $b->{type} && lc( $b->{type} ) eq 'repeat' ) {
$rep_start = $i;
last;
}
}
}
my $table_path = $self->table_path($tableid);
my $file_path = "$table_path.$self->{db_ext}";
$self->config('no_write')
and do { $self->transact_error( $file_path, "No authority to write to the file" ); return; };
lib/AmberDB.pm view on Meta::CPAN
}
my $is_async_write = ( $use_ramdisk == 4 && !$is_txn );
my $is_dual_write = ( $use_ramdisk == 2 || ( $is_txn && $use_ramdisk ) );
my $ram_file = $ramdisk_path ? "$ramdisk_path.$self->{db_ext}" : undef;
my $target_file = ( ( $is_async_write || $use_ramdisk == 3 ) && $ram_file ) ? $ram_file : $file_path;
# Open table to write unless async write or volatile ramdisk
unless ( $is_async_write || $use_ramdisk == 3 ) {
$self->table_write($file_path)
or do {
unless ($is_txn) { $self->flock_close( $tableid, $rid ); }
$self->transact_error( $file_path, "Could not open $file_path to write" );
return;
};
}
if ( $use_ramdisk == 3 && $ram_file ) {
$self->table_write($ram_file)
or do {
unless ($is_txn) { $self->flock_close( $tableid, $rid ); }
$self->transact_error( $ram_file, "Could not open $ram_file to write" );
return;
};
}
# If no record, return
my $record;
if ( ( $is_async_write || $use_ramdisk == 3 ) && $ram_file && -e $ram_file ) {
my $rec_h = $self->recs_get( $ram_file, $rid );
$record = $rec_h ? $rec_h->{$rid} : undef;
}
unless ( defined $record || $use_ramdisk == 3 ) {
my $rec_h = $self->recs_get( $file_path, $rid );
$record = $rec_h ? $rec_h->{$rid} : undef;
}
if ( !defined $record ) {
$self->table_close($file_path) unless ( $is_async_write || $use_ramdisk == 3 );
$self->table_close($ram_file) if ( $use_ramdisk == 3 && $ram_file );
unless ($is_txn) { $self->flock_close( $tableid, $rid ); }
return;
}
# Delete the record
$self->recs_del( [ $target_file, $tableid ], $rid );
if ($is_async_write) {
$self->ramdisk_mark_dirty( $file_path, $rid, 3 );
}
elsif ( $use_ramdisk == 4 && $is_txn ) {
$self->ramdisk_unmark_dirty( $file_path, $rid );
}
$self->table_close($file_path) unless ( $is_async_write || $use_ramdisk == 3 );
$self->table_close($ram_file) if $ram_file;
unless ($is_txn) { $self->flock_close( $tableid, $rid ); }
# Cache invalidate
$self->clear_cache($tableid, $rid);
# Text backup record
unless ( $is_async_write || $use_ramdisk == 3 ) {
$self->recs_back( "del", $tableid, [ $rid, "" ] )
or cluck "[DB_TIE] Backup error (del). $tableid\n";
}
# Move to archive if keep_deleted enabled
if ( $table_info->{keep_deleted} && !$is_async_write ) {
( $self->table_write($del_path)
and $self->recs_put( [ $del_path, $tableid ], [ $rid, $record ] )
and $self->table_close($del_path) )
or cluck "[DB_TIE] $del_path can't open.\n";
}
# Invalidate cached table keys and count in memory
$self->set_cache( $tableid, 'keys', undef );
$self->set_cache( $tableid, 'count', undef );
( $self->config('use_simple') || ( $table_info && $table_info->{use_simple} ) ) and return $rid;
my @record = ( $rid, $self->db_decode($record) );
# Clear Index (search, match, facet, sort)
my @batch = ( \@record );
my $idx_path = ( $use_ramdisk && $ramdisk_path ) ? $ramdisk_path : $table_path;
# 1. Base stream: unconditionally delete from all records
$self->records_del( $idx_path, $table_info, [$rid], $tableid );
$self->search_del( $idx_path, $table_info, $tableid, \@batch );
$self->match_del( $idx_path, $table_info, \@batch );
$self->sort_del( $idx_path, $table_info, \@batch );
$self->unique_del( $idx_path, $table_info, \@batch );
# 2. Tiered stream (clean from both A and B tiers)
if ( $table_info->{use_junk} ) {
$self->records_del( $idx_path, $table_info, [$rid], $tableid, ['A', 'B'] );
$self->search_del( $idx_path, $table_info, $tableid, \@batch, ['A', 'B'] );
$self->match_del( $idx_path, $table_info, \@batch, ['A', 'B'] );
$self->sort_del( $idx_path, $table_info, \@batch, ['A', 'B'] ) if $table_info->{sort_block};
$self->facet_del( $idx_path, $table_info, \@batch ) if $table_info->{use_facet};
}
elsif ( $table_info->{use_facet} ) {
$self->facet_del( $idx_path, $table_info, \@batch );
}
$self->slug_del( $idx_path, $table_info, $tableid, [$rid] );
# Authorization
$self->auth_write( $tableid, $table_path, "del", $rid ) unless ( $is_async_write || $use_ramdisk == 3 );
$self->_invalidate_child_ramdisk_tables($tableid);
return 1;
}
# Deletes list of records from table...
# Note: Bulk operations (insert_list, modify_list, delete_list) do NOT use transactions (_txn_log).
# ------------------------------------------------
sub delete_list {
my ( $self, $tableid, @records ) = @_;
lib/AmberDB.pm view on Meta::CPAN
push @del_rids, $rid;
push @batch, [ $rid, $self->db_decode($raw) ];
$self->clear_cache( $tableid, $rid );
}
if (@del_rids) {
$self->recs_del( [ $target_file, $tableid ], @del_rids );
if ($is_async_write) {
foreach my $rid (@del_rids) {
$self->ramdisk_mark_dirty( $file_path, $rid, 3 );
}
}
}
$self->table_close($file_path) unless ( $is_async_write || $use_ramdisk == 3 );
$self->table_close($ram_file) if $ram_file;
return \%statu unless @batch;
$self->set_cache($tableid);
if ($is_simple) {
$self->_invalidate_child_ramdisk_tables($tableid);
return \%statu;
}
# Archive
if ( $table_info->{keep_deleted} && !$is_async_write && $use_ramdisk != 3 ) {
if ( $self->table_write($del_path) ) {
my @archive_records = map {
[ $_->[0], $self->db_encode( @{$_}[ 1 .. $#$_ ] ) ]
} @batch;
$self->recs_put( [ $del_path, $tableid ], @archive_records );
$self->table_close($del_path);
}
}
my $idx_path = ( $use_ramdisk && $ramdisk_path ) ? $ramdisk_path : $table_path;
# Phase 2: bulk index clearing
# 1. Base stream unconditional delete
$self->records_del( $idx_path, $table_info, \@del_rids, $tableid );
$self->search_del( $idx_path, $table_info, $tableid, \@batch );
$self->match_del( $idx_path, $table_info, \@batch );
$self->sort_del( $idx_path, $table_info, \@batch );
# 2. Tiered stream cleanups
if ( $table_info->{use_junk} ) {
$self->records_del( $idx_path, $table_info, \@del_rids, $tableid, ['A', 'B'] );
$self->search_del( $idx_path, $table_info, $tableid, \@batch, ['A', 'B'] );
$self->match_del( $idx_path, $table_info, \@batch, ['A', 'B'] );
$self->sort_del( $idx_path, $table_info, \@batch, ['A', 'B'] ) if $table_info->{sort_block};
$self->facet_del( $idx_path, $table_info, \@batch ) if $table_info->{use_facet};
}
elsif ( $table_info->{use_facet} ) {
$self->facet_del( $idx_path, $table_info, \@batch );
}
$self->unique_del( $idx_path, $table_info, \@batch );
$self->slug_del( $idx_path, $table_info, $tableid, \@batch );
unless ( $is_async_write || $use_ramdisk == 3 ) {
# Operations: auth, backup
if ( $table_info->{log_owner} ) {
foreach my $rec (@batch) {
$self->auth_write( $tableid, $table_path, "del", $rec->[0] );
}
}
unless ( $self->config('no_backup') || $table_info->{no_backup} ) {
$self->recs_back( "del", $tableid, map { [ $_->[0], "" ] } @batch );
}
}
$self->_invalidate_child_ramdisk_tables($tableid);
return \%statu;
}
# my $ok = $adb->insert_links($tableid, [rid1, lnk1], [rid2, lnk2]);
# Writes alias link bindings into .lnk file.
# ------------------------------------------------
sub insert_links {
my ( $self, $tableid, @records ) = @_;
$tableid or return;
@records or return;
my $table_info = $self->table_info($tableid);
$table_info->{use_alias} or return;
# Yazma yetkisi iptal edildi.
$self->config('no_write')
and do { cluck "[DB_TIE] No authority to write to the file.\n"; return; };
my $table_path = $self->table_path($tableid);
my $link_path = "$table_path.lnk";
$self->table_write($link_path)
or do { cluck "[DB_TIE] $link_path can't open. insert_links. $tableid\n"; return; };
foreach my $rec (@records) {
( $rec->[0] and $rec->[1] ) or next;
$self->recs_put( $link_path, [ $rec->[0], $rec->[1] ] );
}
$self->table_close($link_path);
return 1;
}
# my $ok = $adb->insert_strs($tableid, $blk, [str1a, str1b], [str2a, str2b]);
# Updates synonym mapping tables (.unq); appends new values to existing list.
# ------------------------------------------------
sub insert_strs {
my ( $self, $tableid, $blk, @records ) = @_;
$tableid or return;
@records or return;
my $table_info = $self->table_info($tableid);
# Write authority cancelled
$self->config('no_write')
and do { cluck "[DB_TIE] No authority to write to the file.\n"; return; };
my $table_path = $self->table_path($tableid);
my $unq_path = "${table_path}.unq";
$self->table_write($unq_path)
or do { cluck "[DB_TIE] $unq_path can't open. insert_links.\n"; return; };
lib/AmberDB.pm view on Meta::CPAN
}
return $ret == 0 ? 1 : 0;
}
# Plural path:
return 0 unless @keys_to_del;
if ( !$self->{_db}->{$table_path} || !$self->{_dbm}->{$table_path} ) {
$self->table_write($table_path)
or do { cluck "[DB_TIE] $table_path can't open for index_del.\n"; return 0; };
}
my $db = $self->{_db}->{$table_path};
return 0 unless $db;
my $is_txn = $self->is_transact($tableid);
my $del_count = 0;
for my $k_item (@keys_to_del) {
next unless defined $k_item && $k_item ne '';
my $k = $self->utf_encode("$k_item");
if ( $is_txn && !$self->{_txn}->{logged}->{"$table_path\x1e$k_item"}++ ) {
my $old_raw;
my $ret = $db->get( $k, $old_raw );
if ( $ret == 0 && defined $old_raw ) {
$self->_txn_log( 'index', $tableid, $table_path, $k_item, 'del', $old_raw );
}
}
my $ret = $db->del($k);
$del_count++ if $ret == 0;
}
# RAM-disk Tier 2 (mirror) or (Tier 4 in active transaction) dual-write
if ( !$no_mirror && $tableid && $self->ramdisk_is_mounted() ) {
my $table_info = eval { $self->table_info($tableid) };
my $use_ramdisk = $table_info ? $self->_normalize_ramdisk_tier( $table_info->{use_ramdisk} // $table_info->{use_cache} // 0 ) : 0;
if ( $use_ramdisk == 1 || $use_ramdisk == 2 || ( $use_ramdisk == 4 && $is_txn ) ) {
my $ram_dir = $self->ramdisk_dir();
my $is_in_ram = ( $ram_dir && index( $table_path, $ram_dir ) == 0 ) ? 1 : 0;
my ($ext) = $table_path =~ m{\.([^.]+)$};
my $mirror_path;
if ( $ext && $ext =~ /^(?:\Q$self->{db_ext}\E|inx|src|fld|fac|unq|slg|ajw|ajn)$/ ) {
if ($is_in_ram) {
my $tbl_path = $self->table_path($tableid);
$mirror_path = "$tbl_path.$ext" if $tbl_path;
}
else {
my $r_path = $self->ramdisk_path($tableid);
$mirror_path = "$r_path.$ext" if $r_path;
}
if ( $mirror_path && $mirror_path ne $table_path ) {
$self->index_del( [ $mirror_path, $tableid, 1 ], \@keys_to_del );
}
}
}
}
return $del_count;
}
# Writes add|edit|del operation to daily CSV backup audit stream (backup/YYYY/YYYY-MM-DD.csv).
# Exits silently if no_backup is set (globally or in table schema).
# my $ok = $adb->recs_back("add|edit|del", $tableid, @records);
# ------------------------------------------------
sub recs_back {
my ( $self, $action, $tableid, @records ) = @_;
( $action and $tableid and scalar @records ) or return;
# Global config check: disables backup for all tables
return 1 if $self->config('no_backup');
# Table schema check: no_backup => 1 in table schema or volatile Tier 3 RAM-disk
my $table_info = $self->table_info($tableid);
return 1 if $table_info->{no_backup} || ( $table_info->{use_ramdisk} // 0 ) == 3;
my $user = $self->config('user') || 'system';
$tableid =~ s/[:\/\\]/--/g;
my $backup_base = $self->path('backup_dir')
|| ( $self->path('dbase_dir') ? $self->path('dbase_dir') . "/backup" : "backup" );
my $year = $self->year;
my $month = $self->month;
my $day = $self->day;
my $date_iso = "$year-$month-$day";
my $time_str = $self->date_str;
my $backup_file;
if ( $self->config('use_simple') ) {
$backup_file = "$backup_base/$date_iso.csv";
}
else {
my $year_dir = "$backup_base/$year";
$self->make_path($year_dir);
$backup_file = "$year_dir/$date_iso.csv";
}
open my $YAZ, ">>:encoding(UTF-8)", $backup_file
or do {
cluck "[DB_BACKUP] Cannot open backup file $backup_file: $!\n";
return;
};
foreach my $record (@records) {
ref($record) eq "ARRAY" or $record = [$record];
my $rid = $record->[0];
my $bac_val = $self->db_encode( @{$record}[ 1 .. $#$record ] );
print $YAZ "$time_str\t$user\t$action\t$tableid\t$rid\t$bac_val\n";
}
close $YAZ;
return 1;
}
# my $view_pre = $adb->auth_view($tableid, $rid);
# Returns add/edit/del audit history on record as HTML <pre>.
# ------------------------------------------------
sub auth_view {
my ( $self, $tableid, $rid ) = @_;
return unless $rid;
return unless $tableid;
return unless ref $self->{_auth}->{$tableid}->{$rid} eq "ARRAY";
my $string;
foreach my $line ( @{ $self->{_auth}->{$tableid}->{$rid} } ) {
if ( ref $line eq "ARRAY" ) {
my $date = $self->dateid2str( $line->[2] );
if ( $line->[1] ne "edit" ) { $line->[1] .= " " }
$string .= " $line->[1]\t$date\t$line->[0]\n";
}
else {
$string .= "--> $line\n";
$string .= "----------------\n";
}
}
return $string;
}
# Loads record ownership audit trail into memory (_auth) from .aut file.
# AUTH called internally only from read_list and read_id.
# my $ok = $adb->auth_read($tableid, $table_path, @record_ids);
# ------------------------------------------------
sub auth_read {
my ( $self, $tableid, $table_path, @record_ids ) = @_;
return unless $tableid;
return unless -e "$table_path.$self->{db_ext}";
return unless -e "$table_path.aut";
return unless scalar @record_ids;
my $table_info = $self->table_info($tableid);
return unless $table_info->{log_owner};
my @lookup_keys;
my %esc_map;
lib/AmberDB.pm view on Meta::CPAN
$adb->insert_id("table_id", @record);
# Update record (update_id / modify_id)
$adb->update_id("table_id", @record_updated);
# Delete record
$adb->delete_id("table_id", $record_id);
# Read record by ID
my @record = $adb->read_id("table_id", $record_id);
# Read all records
my @records = $adb->read_all("table_id");
# Read list of records by IDs
my @records = $adb->read_list("table_id", \@id_list);
# Search for the string "New York" in field 2 using the match function.
my @records = $adb->field_fetch("table_id", 2, "New York");
# or if the New York ID is 142
my @records = $adb->field_fetch("table_id", 2, 142);
# Full-text string search
my @records = $adb->search_table("table_id", "search string");
# If `read_all`, `field_fetch`, and `search_table` take the `$limit` parameter, they will not read all records; they will read a specific range based on `offset` and `limit`, and return the number of records at the beginning.
my ($count, @records) = $adb->read_all("table_id", $offset, $limit);
my ($count, @records) = $adb->field_fetch("table_id", $field_no, $match_value, $offset, $limit);
my ($count, @records) = $adb->search_table("table_id", "search string", $offset, $limit);
# Direct low-level table access
$adb->table_write($file_path);
my $records = $adb->recs_get($file_path, @rec_ids);
my $ok = $adb->recs_put($file_path, @records);
$adb->table_close($file_path);
# Transaction example (Checkout / Stock operation)
my $res = $adb->transact_start();
my $order_id = $adb->insert_id("order", 0, $user_id, $item_id, $qty);
if ( !$order_id ) {
$adb->transact_error();
}
my $stock_id = $adb->modify_id("stock", $item_id, $user_id, $item_id, $new_qty);
$adb->transact_end();
=head1 DESCRIPTION
C<AmberDB> is a high-performance, flat-file NoSQL database engine for Perl built on top of Berkeley DB (C<DB_File>). It combines the speed of flat-file storage with enterprise features: schema-driven multi-dimensional indexing, ACID-compliant transac...
=head1 SUBMODULE ARCHITECTURE & INHERITANCE
C<AmberDB> is built as a unified coordinator that incorporates all functionality from specialized submodules via inheritance (C<use parent>). When you instantiate an C<AmberDB> object (C<$adb>), all methods from the following submodules are directly ...
=over 4
=item * B<L<AmberDB::Date>> - Compact chronological ID getters (C<day_id>, C<second_id>, C<month_id>), date string parsing (C<str2dateid>, C<dateid2str>), range generation (C<day_range>), ISO week numbers (C<dateid2week>), and relative offset calcula...
=item * B<L<AmberDB::Locale>> - Multilingual text processing, locale-aware casing (C<uc>, C<lc>, C<ucfirst>), Unicode Collation (UCA) sorting (C<sort>), ASCII transliteration (C<to_ascii>), number-to-words / cheque conversion (C<num2text>), number fo...
=item * B<L<AmberDB::Tools>> - Enterprise database utilities: backup (C<.amberdb> tar archive with SHA-256 integrity), atomic restore, CSV migration (C<tie2csv>, C<csv2tie>), vacuum compaction, and reindexing.
=back
All submodules (except C<AmberDB::Tools> which takes an C<$adb> handle) can also be instantiated and used independently in standalone scripts.
=head1 TABLE NAMING CONVENTIONS
AmberDB enforces a strict, deterministic lowercase snake_case table naming convention:
=over 4
=item * B<Format:> All table identifiers must consist of lowercase alphanumeric characters in snake_case, structured as C<E<lt>databaseE<gt>_E<lt>table_nameE<gt>> (e.g. C<catalog_product>, C<member_address>, C<orders_item>).
=item * B<Database Prefix Resolution:> The segment before the first underscore (C<_>) represents the logical database/schema group (mapped to C<E<lt>databaseE<gt>.dbase>).
=item * B<Schema Files:> A table C<catalog_product> automatically resolves its schema from C<catalog_product.table> and its database group settings from C<catalog.dbase>.
=item * B<Constraint:> Uppercase or mixed-case table names (e.g. C<Catalog_Product>) are not supported and will fail database group extraction.
=back
=head1 SCHEMA DEFINITION & CONFIGURATION (.table & IN-MEMORY)
AmberDB is schema-driven. Table schemas define primary key constraints, field blocks, multi-dimensional indexes, automatic URL slug generation, facet filters, lifecycle junk rules, and repeating nested items.
Schemas can be defined in two ways:
=over 4
=item 1.
B<Disk-Based Schema Files:> Placed in the C<dbstore/schema/E<lt>table_nameE<gt>.table> directory. AmberDB loads and parses them automatically upon first access.
=item 2.
B<Programmatic In-Memory Schemas:> Defined directly on the AmberDB instance via C<$adb-E<gt>table_attr('table_id', { ... })>.
=back
=head2 Example Table Schema (C<catalog_product.table>)
Defining blocks in the schema is not mandatory. However, `record_index`, `match_block`, `search_block`, and `sort_block` are crucial, especially for the automatic creation of indexes during record keeping. `record_index` only takes the value 0/1. `ma...
{
name => "Product Catalog",
record_index => 1, # Enable .inx primary record index
match_block => [1, 2, 3, 11], # .fld exact field match indexes (Category, Brand, etc.)
search_block => [4, 5, 7], # .src full-text search fields (Title, Subtitle, Description)
sort_block => [ 4, { blk => 10, type => 'num' } ], # .inx pre-sorted ID buffers
keep_deleted => 1, # Enable soft-delete audit log (.del)
log_owner => 1, # Enable change audit logging (.aut)
}
=head2 Dynamic Runtime Schema Manipulation (C<table_attr>)
Schemas can be dynamically reconfigured in-memory at runtime without modifying disk files or requiring table migrations:
# Dynamically change full-text search fields on the fly
$adb->table_attr("catalog_product", { search_block => [ 4, 9 ] });
lib/AmberDB.pm view on Meta::CPAN
# Repeating line items:
{ id => "item_id", name => "Item ID", type => "text" },
{ id => "item_title", name => "Product Title",type => "text" },
{ id => "item_qty", name => "Quantity", type => "num" },
{ id => "item_price", name => "Unit Price", type => "num" },
],
}
=head1 TRANSACTIONS
Transactions provide multi-table atomic updates backed by undo-log journals.
If a database error occurs (e.g. file lock failure, duplicate ID), or if custom business validation fails (e.g. insufficient stock),
all base records and indexes across all affected tables are restored to their exact pre-transaction state.
=head2 Checkout / Stock Deduction Example
$adb->transact_start();
# 1. Check & update stock
my @product = $adb->read_id("product", $product_id);
my $current_stock = $product[4];
if ($current_stock < $quantity) {
# Operational condition (out of stock): Directly roll back and release locks
$adb->transact_rollback();
return { success => 0, error => "Out of stock" };
}
$product[4] -= $quantity;
$adb->modify_id("product", $product_id, @product);
# 2. Insert order record
my $order_id = $adb->insert_id("orders", 0, $user_id, $product_id, $quantity, time());
# 3. Finalize transaction (auto-rollbacks if base error occurred)
my $txn = $adb->transact_end();
if ($txn->{status} eq 'commit') {
return { success => 1, order_id => $order_id };
} else {
return { success => 0, error => "The operation failed, the changes were reverted." };
}
B<Note / Limitations:> Bulk/list operations (C<insert_list>, C<modify_list>, C<delete_list>) do not support the transact operation. There is a fundamental reason for this. Junk operations are designed for loading, editing, or deleting a list containi...
Furthermore, if the user truly wants to perform an operation on the list using transact, they can put it in a loop and use the individual C<insert_id>, C<modify_id>, C<delete_id> operations.
=head1 SIMPLE MODE (SCHEMA-LESS FLAT STORE)
In addition to its schema-driven enterprise mode, AmberDB provides a lightweight B<Simple Mode> (C<use_simple =E<gt> 1>). In Simple Mode, the database operates as an ultra-fast, schemaless NoSQL key-value/document store directly on flat C<.db> (or cu...
=head2 Key Characteristics of Simple Mode
=over 4
=item * B<Arbitrary & Flexible Keys:> The 8-byte ASCII limit and numeric constraints are bypassed. Keys can be emails (C<user@example.com>), UUIDs, long tokens, or Unicode/multilingual strings.
=item * B<Flat Directory Structure:> All tables reside directly under C<dbase_dir> (e.g. C<$dbase_dir/table.db>). No C<table/> or C<schema/> subfolders are required.
=item * B<Rich Nested Structures:> Records can store nested array and hash references (ARRAY/HASH) directly.
=item * B<Continuous Daily Backup Logs:> Text-based continuous daily WAL/CSV logs (C<recs_back>) automatically record all C<add>, C<edit>, and C<del> operations directly into C<$dbase_dir/YYYY-MM-DD.csv> alongside database tables (can be silenced wit...
=item * B<ACID Transactions:> Full multi-table transaction support with atomic rollback (restoring raw records in the C<.db> file).
=item * B<Streaming Queries & Sorting:> Methods like C<read_all>, C<field_fetch>, and C<search_table> operate via direct sequential streaming scans with full support for pagination (C<offset>/C<limit>, with legacy C<start>), C<keys_only>, and in-memo...
=item * B<Zero-Latency RAM-Disk Caching:> Simple mode instances can be initialized directly on RAM-disk mount points (Linux C</dev/shm>, macOS C</Volumes/AmberDB_RAM>, or Windows ImDisk C<R:>) to provide nanosecond-speed transient session and cache s...
=back
=head2 Simple Mode Example
# 1. Initialize simple mode
my $adb = AmberDB->new(
path => { dbase_dir => "/var/data/sessions" },
cfg => { use_simple => 1, user => 'admin' },
);
# 2. Insert with arbitrary key
$adb->insert_id('sessions', 'user@example.com', 'Active', 'Chrome', time());
# 3. Read record (O(1))
my @sess = $adb->read_id('sessions', 'user@example.com');
# 4. Search and filter without indexes
my ($count, @active) = $adb->field_fetch('sessions', 1, 'Active', 0, 10);
# 5. Volatile in-memory simple store
my $ram_db = AmberDB->new(
path => { dbase_dir => "/dev/shm/amberdb_tokens" },
cfg => { use_simple => 1, no_backup => 1 },
);
$ram_db->insert_id('tokens', $token_id, $user_id, time());
=head1 RAM-DISK ACCELERATION
AmberDB features a built-in, transparent physical RAM-disk acceleration engine (Linux C<tmpfs>, macOS C<APFS RAM-Disk> via C<hdiutil>, or Windows C<ImDisk>). It enables high-traffic tables and hot indexes to operate at pure volatile memory speeds whi...
=head2 What is it?
RAM-disk acceleration routes file I/O for database tables directly to an operating system in-memory RAM-disk filesystem (Windows ImDisk C<R:/amberdb_$dbname>, Linux tmpfs C</dev/shm/amberdb_$dbname>, or macOS APFS C</Volumes/amberdb_$dbname>). Unlike...
=head2 How It Works
=over 4
=item * B<Native File Formats:> AmberDB stores all table data and index files on RAM-disk using their exact native file extensions (C<.db>, C<.inx>, C<.fld>, C<.src>, C<.fac>, C<.unq>, C<.slg>). No proprietary cache file format is used.
=item * B<Dual-Write Synchronization:> For accelerated tables, reads are served at microsecond RAM speeds directly from RAM-disk. Writes synchronously update both the persistent disk file and the RAM-disk file, ensuring complete data durability witho...
=item * B<ACID Transaction Safety:> Transactions (C<transact_start>, C<transact_end>, C<transact_rollback>) protect RAM-disk operations with disk-backed undo journals and strict two-phase locking (Strict 2PL).
=item * B<Automated Mount Detection & Strict Zero-Fallback:> The engine automatically verifies whether the OS RAM-disk filesystem is actively mounted. If unmounted, AmberDB enforces a strict Zero-Fallback policy: all RAM-disk paths (C<ramdisk_dir>, C...
=back
=head2 Acceleration Tiers (C<use_ramdisk>)
Tables can be assigned an acceleration tier via the C<use_ramdisk> schema flag or dynamically via C<table_attr()>:
=over 4
=item * B<Tier 1 (Hybrid Index-Only, C<use_ramdisk =E<gt> 1>):> Only secondary index files (C<.inx>, C<.fld>, C<.src>, C<.fac>, C<.unq>, C<.slg>) are placed in RAM-disk and synchronously dual-written to physical disk. Primary table data (C<.db>) rema...
=item * B<Tier 2 (Full Table Mirror, C<use_ramdisk =E<gt> 2>):> Both primary records (C<.db>) and all index files are mirrored on RAM-disk. Reads are served directly from RAM-disk with synchronous dual-writing to permanent storage.
=item * B<Tier 3 (Volatile In-Memory, C<use_ramdisk =E<gt> 3>):> Operates purely in RAM-disk as an unindexed simple store (C<use_simple =E<gt> 1>) with zero physical disk files. Ideal for ephemeral sessions, shopping carts, and temporary tokens. Supp...
=item * B<Tier 4 (Asynchronous Write-Behind, C<use_ramdisk =E<gt> 4>):> Primary records and indexes are updated immediately in RAM-disk for maximum throughput. Write operations append dirty sync events to C<journal/sync_ramdisk>, and a background dae...
=back
=head2 Transparent Management (C<use_ramdisk>)
AmberDB manages the RAM-disk layer entirely in the background. Developers do not need to call any low-level RAM-disk functions or manually orchestrate memory synchronization. Everything is controlled declaratively via the C<use_ramdisk> option:
=over 4
=item * B<Global Configuration:> Set globally at instantiation (C<AmberDB-E<gt>new(cfg =E<gt> { use_ramdisk =E<gt> 1 })>) or at runtime via C<$adb-E<gt>config(use_ramdisk =E<gt> 2)>.
=item * B<Per-Table Customization:> Set independently for each table in its C<.table> schema or via C<$adb-E<gt>table_attr($table, use_ramdisk =E<gt> $tier)>.
=item * B<Standard CRUD Workflow:> Continue using standard AmberDB methods (C<read_id>, C<search_table>, C<insert_id>, C<modify_id>). The engine automatically reads from memory at microsecond speeds and dual-writes to permanent storage.
=item * B<Windows & Linux Administration:> On Windows, use C<bin\setup_windows.bat> to mount or unmount the ImDisk RAM-disk. On Linux, C</dev/shm> is utilized automatically:
- Mount RAM-disk (Windows): bin\setup_windows.bat start 512M R:
- Status check (Windows): bin\setup_windows.bat status
- Background Sync Daemon: perl bin/amberdb_daemon.pl start
=back
lib/AmberDB.pm view on Meta::CPAN
"products", 1, "5",
{ offset => 0, limit => 20, sort => -10 }
);
# Multi-value matching (comma string, semicolon, or ARRAY ref)
my @records = $adb->field_fetch("products", 1, ["5", "8"]);
my @records = $adb->field_fetch("products", 1, "5, 8");
# Return only record IDs: keys_only flag
my @all_ids = $adb->field_fetch("products", 1, "5", { keys_only => 1 });
my ($total_count, @ids) = $adb->field_fetch("products", 1, "5", { offset => 0, limit => 20, keys_only => 1 });
# Tiered Junk query mode
my @active = $adb->field_fetch("products", 1, "5", { jnktype => 'A' }); # Only Active records
# Numerical / chronological range filtering on an auxiliary block:
my @range_prods = $adb->field_fetch("products", 2, "Smartphones", { range => { block => "price", min => 1000, max => 1500 } });
C<field_fetch> uses the C<match_block> definition in the schema and accesses inverted match index files (C<.fld>), providing $O(1)$ average-time lookup per indexed key (total retrieval cost scales with the number of requested values and matching reco...
=head2 field_count($table_id, $block, [$value], [\%options])
Quickly counts the number of matching records (keys) for one or more field values in a given block using the inverted exact match index file (C<.fld>) in $O(1)$ time per value (calculated directly as C<bytes::length($raw) / 8> without allocating memo...
B<Arguments:>
=over 4
=item * C<$table_id> (String) - Target table name.
=item * C<$block> (Integer|String) - 1-based block index or schema field name (e.g., C<2> or C<'firm'>).
=item * C<$value> (Scalar|ArrayRef, Optional) - Single value, comma-separated string, or ARRAY reference of values to count. If omitted, counts all values present in that block.
=item * C<\%options> (HashRef, Optional) - Optional flags. By default, C<< jnktype => 'ALL' >> is used, querying all records directly without A/B tier splitting. Pass C<< jnktype => 'A' >> for active records only, or C<< jnktype => 'B' >> for junk re...
=back
B<Return values:>
When passed an ARRAY reference or comma-separated values, returns a HASH reference (or HASH in list context) mapping each value to its record count:
my $counts = $adb->field_count("catalog_product", 2, [45, 68, 712, 1254]);
# { 45 => 1452, 68 => 21, 712 => 85, 1254 => 421 }
my $counts = $adb->field_count("catalog_product", "firm", [45, 68]);
# { 45 => 1452, 68 => 21 }
When passed a single scalar value, returns the record count as an integer:
my $count = $adb->field_count("catalog_product", 2, 45);
# 1452
When C<$value> is omitted, counts all values indexed for that block:
my $all_counts = $adb->field_count("catalog_product", 2);
# { 45 => 1452, 68 => 21, 712 => 85, ... }
=head2 search_table($table_id, $query, [\%options])
It performs searches matching query terms using the full-text C<.src> index (or a sorted table scan backup method if unindexed). C<search_table> uses the C<AmberDB::Locale> module. It features advanced language normalization according to the selected...
B<IMPORTANT (Return Signature Convention):>
When C<$limit> is passed and C<E<gt> 0> (paginated), C<search_table> returns C<($total_count, @records)> where the first scalar is the total matching count integer. When C<$limit> is omitted or C<0> (unpaginated), it returns C<@records> directly. Unp...
# 1. Unpaginated (returns array of record arrayrefs directly)
my @records = $adb->search_table("catalog_product", "wireless headphones");
my @sorted_records = $adb->search_table("catalog_product", "headphones", { sort => -5 });
# 2. Paginated (first element is total matching count integer)
my ($total_count, @search) = $adb->search_table("catalog_product", "headphones", { offset => 0, limit => 20 });
my ($total_count, @search) = $adb->search_table(
"catalog_product", "headphones",
{
offset => 0,
limit => 20,
sort => -5,
type => "and",
filter => { field => 6, value => 12 },
range => { block => "price", min => 100, max => 500 },
jnktype => 'AB',
}
);
# Return only scalar record IDs
my @all_ids = $adb->search_table("catalog_product", "headphones", { keys_only => 1 });
my ($total_count, @ids) = $adb->search_table("catalog_product", "headphones", { offset => 0, limit => 50, keys_only => 1 });
=head2 field_filter($table_id, \%filter_options)
Performs multi-block filtered queries (AND / OR) with support for multi-value filters, tier mode selection (C<jnktype>), numerical/chronological range filtering (C<range>), sorting, and pagination:
my $res = $adb->field_filter("catalog_product", {
type => "and",
filter => { 1 => "5", 6 => ["12", "14"] },
range => { block => "price", min => 1000, max => 2500 },
sort => { blk => 5, reverse => 1 },
jnktype => "AB",
offset => 0,
limit => 20,
});
# Returns: { count => $total, ids => \@matching_ids }
=head2 exist_id($table_id, $record_id)
Checks if a single record exists in the specified table. Returns 1 if present, 0 otherwise:
my $exists = $adb->exist_id("catalog_product", 101);
=head2 exist_list($table_id, @record_ids)
Queries the presence of multiple record IDs in a single pass. Returns a hash reference C<{ id =E<gt> 1/0 }>:
my $map = $adb->exist_list("catalog_product", 101, 102, 103);
=head2 exist_table($table_id, [$ext])
Checks whether the physical database table or index file exists on disk. C<$ext> defaults to C<$self-E<gt>{db_ext}> (C<'db'>):
my $has_table = $adb->exist_table("catalog_product");
my $has_index = $adb->exist_table("catalog_product", "inx");
( run in 1.681 second using v1.01-cache-2.11-cpan-99fa8243a42 )