/ 
AmberDB-5.02
/ AmberDB::Index::Junk

NAME

AmberDB::Index::Junk - Schema-driven Tiered (Hot/Cold) Indexing and Lifecycle Management for AmberDB

SYNOPSIS

# In table schema definition (.table):
{
    name         => "Ürünler",
    record_index => 1,
    use_junk     => 1,
    junk_rules   => [
        [ 20, "ne", 1 ],                      # Direct block rule (e.g. sales_status != 1)
        [ "2->14", "ne", 1 ],                 # Relational RDBM rule (producer block 2 -> status block 14)
        [ "6->0", "eq", "out_of_stock" ],     # Nested array / composite rule
    ],
    jnktype      => "AB",                     # Default table query tier mode (A, AB, B, BA)
    search_block => [ 4, 5 ],
    match_block  => [ 1, 2, 3 ],
}

# Querying from AmberDB ($dbp inherits AmberDB::Index::Junk):

# 1. Search with explicit tier mode:
my ($cnt, @recs) = $dbp->search_table("catalog_product", "roman", start => 0, limit => 20, jnktype => 'A');

# 2. Field filter with tier mode:
my $filter_res   = $dbp->field_filter("catalog_product", { filter => { 1 => 45 }, jnktype => 'AB' });

# 3. Read all records with tier mode:
my @active_ids   = $dbp->read_all("catalog_product", jnktype => 'A', keys_only => 1);
my @junk_ids     = $dbp->read_all("catalog_product", jnktype => 'B', keys_only => 1);
my @combined_ids = $dbp->read_all("catalog_product", jnktype => 'AB', keys_only => 1);

DESCRIPTION

AmberDB::Index::Junk provides a schema-driven, fully automated two-tier indexing architecture:

  • Hot / Active Tier (A):

    Contains high-priority, currently active, in-sale records. Files: ${table_path}.inx, ${table_path}_${blk}.fld, ${table_path}_${blk}.src, ${table_path}_${blk}.fac.

  • Cold / Junk Tier (B):

    Contains passive, expired, or out-of-sale records. Files: ${table_path}.jinx, ${table_path}_${blk}.jfld, ${table_path}_${blk}.jsrc.

This partitioning ensures high performance on storefront search, filtering, and indexing operations while keeping legacy and inactive catalog data searchable and accessible on demand without degrading active traffic.

SCHEMA CONFIGURATION

use_junk => 1

Enables dual-tier indexing on the table. If absent or set to 0, standard single-tier indexing is used.

junk_rules => [ [ $spec, $operator, $value ], ... ]

Defines the conditions under which a record is classified as Junk (Tier B). If any rule matches (logical OR), the record is routed to Tier B. If no rules match, the record is routed to Tier A.

  • Direct Block Index: [ 20, "ne", 1 ]

    Evaluates block 20 of the current record.

  • Relational RDBM Reference: [ "2-14", "ne", 1 ]>

    Looks up block 2's target table (via rdbm schema configuration) and evaluates block 14 of the referenced record. For example, if a product is manufactured by a publisher whose status in catalog_producer is passive, the product is automatically classified as Junk.

  • Nested Array / Composite: [ "6-0", "eq", "archived" ]>

    Evaluates nested array elements or comma/tab separated fields within the record.

QUERY MODES (jnktype)

The query tier mode is resolved with the following priority hierarchy:

1. Query Parameter: $opts->{jnktype} (e.g. in search_table, field_filter, read_all)
2. Table Schema:    $table_info->{jnktype}
3. Instance Config: $self->{cfg}->{jnktype}
4. Global Default:  'AB'

Available Modes:

  • A (Active Only):

    Queries only active indexes (.inx, .fld, .src). Ideal for customer-facing category listings, checkout, stock verification, and order processing.

  • AB (Active First, Junk Appended):

    Queries active indexes first, then appends results from junk indexes. Ideal for general storefront search where active products appear at the top, followed by out-of-print items.

  • B (Junk Only):

    Queries only junk indexes (.jinx, .jfld, .jsrc). Ideal for administrative archives, inventory reconciliation, and discontinued item reports.

  • BA (Junk First, Active Appended):

    Queries junk indexes first, followed by active records.

LIFECYCLE & AUTOMATIC STATE TRANSITIONS

During modify_id and modify_list calls, junk_transition calculates state changes:

  • Active -> Junk:

    Record is removed from .inx, .fld, .src and added to .jinx, .jfld, .jsrc.

  • Junk -> Active:

    Record is removed from .jinx, .jfld, .jsrc and added to .inx, .fld, .src.

  • Unchanged:

    Record is modified in-place within its existing tier.

METHODS

junk_rules($table_info, @record)

Evaluates schema rules against a record. Returns 1 if Junk, 0 if Active.

get_jnktype($table_info, \%opts)

Resolves effective query mode ('A', 'AB', 'B', 'BA') according to the priority hierarchy.

junk_transition($table_path, $table_info, $tableid, \@pairs)

Manages automated index migration between active and junk tiers during record modifications.

junk_records_add / junk_records_del

CRUD operations for primary cold record index (.jinx).

junk_match_add / junk_match_del / junk_match_modify

CRUD operations for cold inverted field index files (_${blk}.jfld).

junk_search_add / junk_search_del / junk_search_modify

CRUD operations for cold full-text search index files (_${blk}.jsrc).

AUTHOR

Maruf Cetin <marufcetin@gmail.com>

LICENSE AND COPYRIGHT

Copyright (C) 2012-2026 Maruf Cetin.

This library is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.