/ 
AmberDB-5.21.0
/ 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 ($adb inherits AmberDB::Index::Junk):

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

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

# 3. Read all records with tier mode:
my @active_ids   = $adb->read_all("catalog_product", jnktype => 'A', keys_only => 1);
my @junk_ids     = $adb->read_all("catalog_product", jnktype => 'B', keys_only => 1);
my @combined_ids = $adb->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: $adb->config('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 (junk_rules) against a given record. Resolves direct fields, nested arrays, and relational foreign keys (RDBM) dynamically. Returns 1 if the record satisfies any junk condition (Tier B), 0 if active (Tier A).

my $is_junk = $adb->junk_rules($table_schema, @record_fields);

get_jnktype($table_info, \%opts)

Resolves the effective query mode ('A', 'AB', 'B', 'BA') using the 4-level priority hierarchy (query options -> table schema -> instance config -> default 'AB').

my $mode = $adb->get_jnktype($table_schema, { jnktype => 'A' }); # "A"

Low-Level Cold Index Maintenance Methods

These methods manage cold index files during CRUD mutations and are called automatically:

  • junk_transition($table_path, $table_info, $tableid, \@pairs) — Migrates modified records between active and junk tiers if their state changed.

  • junk_records_add / junk_records_del — Primary cold key index operations (.jinx).

  • junk_match_add / junk_match_del / junk_match_modify — Cold inverted field match index operations (_${blk}.jfld).

  • junk_search_add / junk_search_del / junk_search_modify — Cold full-text search index operations (_${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.