blib/lib/AmberDB/Base/Facet.pm untested

filter: Statementstmt 0.0% 0 / 657 Branchbran 0.0% 0 / 472 Conditioncond 0.0% 0 / 549 MC/DCmcdc 0.0% 0 / 307 Subroutinesub 0.0% 0 / 18 Podpod 0.0% 0 / 15 totaltotal 0.0% 0 / 2018 CC 237 SCAR 68.7
CC
237
Cov
0%
field_allfltkeys
1980.0
_facet_calc_counts
1560.0
_facet_build_groups
1122.0
CRAP 958.7
1 package AmberDB::Base::Facet;
2
3 use 5.016;
4 use warnings;
5 use Carp qw(croak cluck);
6
7 our $VERSION = '5.26.6';
8 my $CREATED = '2026-08-28';
9
10 # $adb->facet_rules($table_info, @record);
11 # ------------------------------------------------
12 sub facet_rules {
13
14 my ( $self, $table_info, @record ) = @_;
15
16 my $fa = $table_info->{facet_rules} or return 1;
17
18 # Single rule: [blk, op, val] or multiple: [[blk,op,val], ...]
19 my @rules = ( ref( $fa->[0] ) eq 'ARRAY' ) ? @$fa : ($fa);
20
21 for my $rule (@rules) {
22 my ( $spec, $op, $val ) = @$rule;
23 my $rv = $self->_resolve_field_value( $table_info, \@record, $spec );
24 return 0 if $rv eq '';
25 return 0 unless $self->_cmp_op( $rv, $op, $val );
26 }
27 return 1;
28 }
29
30 # =====================================================================
31 # İNDEKSLEME (.fac CRUD) FONKSİYONLARI (Yalnızca Aktif Kayıtlar)
32 # =====================================================================
33
34 # $adb->facet_add($table_path, $table_info, \@records);
35 # records = [ [$rid, @data...], ... ] — $rid index 0'da
36 # ------------------------------------------------
37 sub facet_add {
38
39 my ( $self, $table_path, $table_info, $records ) = @_;
40
41 return unless $table_info->{use_facet} && $table_info->{facet_block};
42 return unless ref($records) eq 'ARRAY' && @$records;
43
44 my @active_records;
45 my @new_active;
46 for my $rec (@$records) {
47 my $rid = $rec->[0];
48 my $is_active = $self->facet_rules( $table_info, @$rec );
49 if ($is_active) {
50 push @new_active, $rid;
51 push @active_records, $rec;
52 }
53 }
54
55 my $fac_path = "$table_path.fac";
56 return unless @active_records || ( $table_info->{facet_rules} && @new_active );
57 return unless $self->table_write($fac_path);
58
59 # Genel aktif ID setini ${table_path}.fac dosyasına kaydet
60 if ( $table_info->{facet_rules} && @new_active ) {
61 my ($raw_acts) = $self->index_get( $fac_path, "active", "raw" );
62 $raw_acts = $self->bin_add( $raw_acts, \@new_active );
63 $self->index_put( $fac_path, "active", $raw_acts, "bin" );
64 }
65
66 if (@active_records) {
67 # SADECE AKTİF kayıtları blok öneki ile (${table_path}.fac) dosyasına yaz
68 for my $blk_cfg ( @{ $table_info->{facet_block} } ) {
69 my $blk = ref($blk_cfg) eq 'HASH' ? $blk_cfg->{blk} : $blk_cfg;
70
71 for my $rec (@active_records) {
72 my $rid = $rec->[0];
73 next unless defined $rec->[$blk] && $rec->[$blk] ne '';
74 my @ids = $self->field_to_list( $rec->[$blk], $table_path, $table_info, $blk );
75 if (@ids) {
76 $self->index_put( $fac_path, "$blk:$rid", join( "\t", @ids ), 'raw' );
77 }
78 }
79 }
80 }
81
82 $self->table_close($fac_path);
83 }
84
85 # $adb->facet_modify($table_path, $table_info, \@pairs);
86 # pairs = [ [$rid, \@old_rec, \@new_rec], ... ]
87 # ------------------------------------------------
88 sub facet_modify {
89
90 my ( $self, $table_path, $table_info, $pairs ) = @_;
91
92 return unless $table_info->{use_facet} && $table_info->{facet_block};
93 return unless ref($pairs) eq 'ARRAY' && @$pairs;
94
95 my ( @add_active, @remove_active );
96 my ( @became_active, @became_passive, @stayed_active );
97
98 for my $pair (@$pairs) {
99 my ( $rid, $old_rec, $new_rec ) = @$pair;
100 next if $self->array_compare( $old_rec, $new_rec );
101 my $old_active = $self->facet_rules( $table_info, @$old_rec );
102 my $new_active = $self->facet_rules( $table_info, @$new_rec );
103
104 if ( $old_active && !$new_active ) {
105 push @remove_active, $rid;
106 push @became_passive, $pair;
107 }
108 elsif ( !$old_active && $new_active ) {
109 push @add_active, $rid;
110 push @became_active, $pair;
111 }
112 elsif ( $old_active && $new_active ) {
113 push @stayed_active, $pair;
114 }
115 }
116
117 my $fac_path = "$table_path.fac";
118 my $need_modify = ( $table_info->{facet_rules} && ( @add_active || @remove_active ) )
119 || @became_passive || @became_active || @stayed_active;
120 return 1 unless $need_modify;
121
122 return unless $self->table_write($fac_path);
123
124 # Genel aktif ID setini güncelle
125 if ( $table_info->{facet_rules} && ( @add_active || @remove_active ) ) {
126 my ($raw_acts) = $self->index_get( $fac_path, "active", "raw" );
127 $raw_acts //= '';
128 if (@remove_active) {
129 $raw_acts = $self->bin_punch( $raw_acts, \@remove_active );
130 }
131 if (@add_active) {
132 $raw_acts = $self->bin_add( $raw_acts, \@add_active );
133 }
134 if ( length($raw_acts) >= 8 ) {
135 $self->index_put( $fac_path, "active", $raw_acts, "bin" );
136 }
137 else {
138 $self->index_del( $fac_path, "active" );
139 }
140 }
141
142 # 1. Pasife dönenleri .fac dosyasından sil ($blk:$rid)
143 if (@became_passive) {
144 for my $blk_cfg ( @{ $table_info->{facet_block} } ) {
145 my $blk = ref($blk_cfg) eq 'HASH' ? $blk_cfg->{blk} : $blk_cfg;
146 for my $p (@became_passive) {
147 $self->index_del( $fac_path, "$blk:$p->[0]" );
148 }
149 }
150 }
151
152 # 2. Aktife dönenleri .fac dosyasına yaz ($blk:$rid)
153 if (@became_active) {
154 for my $blk_cfg ( @{ $table_info->{facet_block} } ) {
155 my $blk = ref($blk_cfg) eq 'HASH' ? $blk_cfg->{blk} : $blk_cfg;
156 for my $p (@became_active) {
157 my ( $rid, undef, $new_rec ) = @$p;
158 next unless defined $new_rec->[$blk] && $new_rec->[$blk] ne '';
159 my @ids = $self->field_to_list( $new_rec->[$blk], $table_path, $table_info, $blk );
160 if (@ids) {
161 $self->index_put( $fac_path, "$blk:$rid", join( "\t", @ids ), 'raw' );
162 }
163 }
164 }
165 }
166
167 # 3. Zaten aktif kalanların değişen bloklarını güncelle
168 if (@stayed_active) {
169 for my $blk_cfg ( @{ $table_info->{facet_block} } ) {
170 my $blk = ref($blk_cfg) eq 'HASH' ? $blk_cfg->{blk} : $blk_cfg;
171
172 my @changed_pairs;
173 for my $p (@stayed_active) {
174 my ( $rid, $old_rec, $new_rec ) = @$p;
175 my $ov = $old_rec->[$blk] // '';
176 my $nv = $new_rec->[$blk] // '';
177 if ( $ov ne $nv ) {
178 push @changed_pairs, $p;
179 }
180 }
181
182 next unless @changed_pairs;
183
184 for my $p (@changed_pairs) {
185 my ( $rid, undef, $new_rec ) = @$p;
186 if ( defined $new_rec->[$blk] && $new_rec->[$blk] ne '' ) {
187 my @ids = $self->field_to_list( $new_rec->[$blk], $table_path, $table_info, $blk );
188 if (@ids) {
189 $self->index_put( $fac_path, "$blk:$rid", join( "\t", @ids ), 'raw' );
190 }
191 else {
192 $self->index_del( $fac_path, "$blk:$rid" );
193 }
194 }
195 else {
196 $self->index_del( $fac_path, "$blk:$rid" );
197 }
198 }
199 }
200 }
201
202 $self->table_close($fac_path);
203
204 return 1;
205 }
206
207 # $adb->facet_del($table_path, $table_info, \@records);
208 # ------------------------------------------------
209 sub facet_del {
210
211 my ( $self, $table_path, $table_info, $records ) = @_;
212
213 return unless $table_info->{use_facet};
214 return unless ref($records) eq 'ARRAY' && @$records;
215
216 my $fac_path = "$table_path.fac";
217 return 1 unless -e $fac_path;
218 return unless $self->table_write($fac_path);
219
220 # Genel aktif ID setinden sil
221 if ( $table_info->{facet_rules} ) {
222 my @remove_active = map { $_->[0] } @$records;
223 if (@remove_active) {
224 my ($raw_acts) = $self->index_get( $fac_path, "active", "raw" );
225 if ( defined $raw_acts && length($raw_acts) > 0 ) {
226 my $orig_len = length($raw_acts);
227 $raw_acts = $self->bin_punch( $raw_acts, \@remove_active );
228 if ( length($raw_acts) != $orig_len ) {
229 if ( length($raw_acts) >= 8 ) {
230 $self->index_put( $fac_path, "active", $raw_acts, "bin" );
231 }
232 else {
233 $self->index_del( $fac_path, "active" );
234 }
235 }
236 }
237 }
238 }
239
240 # Blok bazlı indekslerden ($blk:$rid) sil
241 for my $blk_cfg ( @{ $table_info->{facet_block} || [] } ) {
242 my $blk = ref($blk_cfg) eq 'HASH' ? $blk_cfg->{blk} : $blk_cfg;
243 for my $rec (@$records) {
244 my $rid = $rec->[0];
245 $self->index_del( $fac_path, "$blk:$rid" );
246 }
247 }
248
249 $self->table_close($fac_path);
250
251 return 1;
252 }
253
254 # =====================================================================
255 # SORGULAMA VE SAYIM FONKSİYONLARI
256 # =====================================================================
257
258 # $hashref = $adb->field_fltkeys($tableid, \%options);
259 # options: target_block => 2, base_ids => \@subset, filter => { 1 => 5, 3 => [10,12] }
260 # ------------------------------------------------
261 sub field_fltkeys {
262
263 my ( $self, $tableid, @args ) = @_;
264
265 $tableid or return;
266
267 my $table_info = $self->table_info($tableid);
268 return unless $table_info && $table_info->{use_facet};
269
270 my $use_ramdisk = $table_info ? ( $table_info->{use_ramdisk} // $table_info->{use_cache} // 0 ) : 0;
271 if ($use_ramdisk) {
272 $self->ramdisk_ensure($tableid);
273 }
274 my $table_path = $self->table_path($tableid);
275 my $idx_path = $use_ramdisk ? $self->ramdisk_path($tableid) : $table_path;
276 my $fac_path = ( -e "${idx_path}.fac" ) ? "${idx_path}.fac" : "${table_path}.fac";
277 my $unq_path = ( -e "${idx_path}.unq" ) ? "${idx_path}.unq" : "${table_path}.unq";
278 my $index_path = ( -e "${idx_path}.inx" ) ? "${idx_path}.inx" : "${table_path}.inx";
279
280 # Parameter parsing
281 my ( $target_block, %active_filter, $base_scope );
282
283 if ( ref( $args[0] ) eq 'HASH' ) {
284 $target_block = $args[0]->{target_block};
285 %active_filter = %{ $args[0]->{where} || $args[0]->{filter} || $args[0]->{match} || {} };
286 $base_scope = $args[0]->{base_ids} || $args[0]->{scope_ids} || undef;
287
288 if ( my $ranges = $self->normalize_range_opts( $tableid, $args[0] ) ) {
289 if ( $base_scope && @$base_scope ) {
290 my @scoped = $self->filter_ids_by_range( $tableid, $base_scope, $ranges );
291 $base_scope = \@scoped;
292 }
293 else {
294 my ( undef, @all_active );
295 ( undef, @all_active ) = $self->index_get( $fac_path, "active" ) if -e $fac_path;
296 unless (@all_active) {
297 ( undef, @all_active ) = $self->index_get( $index_path, "keys" ) if -e $index_path;
298 }
299 @all_active = $self->table_keys($tableid) unless @all_active;
300 my @scoped = $self->filter_ids_by_range( $tableid, \@all_active, $ranges );
301 $base_scope = \@scoped;
302 }
303 }
304 }
305 else {
306 my ( $fld1, $fld2, $val1 ) = @args;
307 $target_block = $fld2;
308 %active_filter = ( $fld1 => $val1 ) if defined($fld1) && defined($val1);
309 }
310
311 defined($target_block) or return;
312
313 # Hedef blok hariç diğer filtreleri baz ID listesi için uygula
314 my %excl = map { $_ => $active_filter{$_} }
315 grep { $_ ne $target_block } keys %active_filter;
316
317 my @base_ids;
318 if (%excl) {
319 my $filter_obj = $self->field_filter(
320 $tableid,
321 {
322 type => 'and',
323 filter => \%excl,
324 ( ( $base_scope && @$base_scope ) ? ( base_ids => $base_scope ) : () ),
325 }
326 );
327 @base_ids = @{ $filter_obj->{ids} || [] };
328 if ( $base_scope && @$base_scope ) {
329 my %scope_map = map { $_ => 1 } @$base_scope;
330 @base_ids = grep { $scope_map{$_} } @base_ids;
331 }
332 }
333
334 elsif ( $base_scope && @$base_scope ) {
335 @base_ids = @$base_scope;
336 }
337 else {
338 my $raw_counts = $self->field_allfltkeys( $tableid, [$target_block] );
339 return $raw_counts->{$target_block} || {};
340 }
341
342 return {} unless @base_ids;
343
344 # Doğrudan ilgili bloğun indeksinden (.fac) oku ($target_block:$rid)
345 my %count_map;
346
347 if ( -e $fac_path ) {
348 my @keys = map { "$target_block:$_" } @base_ids;
349 my $res = $self->recs_get( $fac_path, @keys );
350 for my $id (@base_ids) {
351 my $raw = $res ? $res->{"$target_block:$id"} : undef;
352 next unless defined $raw && $raw ne '';
353 my @vals = ( index( $raw, "\t" ) == -1 ) ? ($raw) : split /\t/, $raw;
354 for my $v (@vals) {
355 $count_map{$v}++;
356 }
357 }
358 }
359 elsif (@base_ids) {
360 my @recs = $self->read_list( $tableid, \@base_ids );
361 for my $r (@recs) {
362 next unless ref($r) eq 'ARRAY';
363 my $raw = $r->[$target_block];
364 next unless defined $raw && $raw ne '';
365 my @vals = ref($raw) eq 'ARRAY' ? @$raw : ( $raw =~ /[,;\t]/ ? split(/\s*[,;\t]\s*/, $raw) : ($raw) );
366 for my $v (@vals) {
367 $count_map{$v}++;
368 }
369 }
370 }
371
372 if ( -e $unq_path && %count_map ) {
373 my @val_ids = keys %count_map;
374 my @n_keys = map { "$target_block:n:$_" } @val_ids;
375 my $names = $self->index_get( $unq_path, \@n_keys, 'raw' );
376 if ( $names && ref($names) eq 'HASH' && %$names ) {
377 my %named_map;
378 for my $vid (@val_ids) {
379 my $name = $names->{"$target_block:n:$vid"} // $vid;
380 $named_map{$name} = $count_map{$vid};
381 }
382 return \%named_map;
383 }
384 }
385
386 return \%count_map;
387 }
388
389 # Returns count map for multiple blocks in a single pass.
390 # my $all = $adb->field_allfltkeys("tableid", \%options);
391 # options: target_blocks => \@blk_list, base_ids => \@base_scope
392 # Legacy: $adb->field_allfltkeys("tableid", \@blk_list, \@base_scope);
393 # Returns: { blk => { val => count }, ... }
394 # ------------------------------------------------
395 sub field_allfltkeys {
396
397 my ( $self, $tableid, @args ) = @_;
398
399 $tableid or return {};
400
401 my ( $blks, $base_scope );
402
403 if ( @args == 1 && ref( $args[0] ) eq 'HASH' ) {
404 my $opts = $args[0];
405 $blks = $opts->{target_blocks} || $opts->{blocks} || $opts->{blks} || $opts->{target_block};
406 $base_scope = $opts->{base_ids} || $opts->{scope_ids} || $opts->{base_scope};
407 }
408 elsif ( @args >= 1 ) {
409 $blks = $args[0];
410 if ( @args >= 2 ) {
411 if ( ref( $args[1] ) eq 'HASH' ) {
412 $base_scope = $args[1]->{base_ids} || $args[1]->{scope_ids} || $args[1]->{base_scope};
413 }
414 elsif ( ref( $args[1] ) eq 'ARRAY' ) {
415 $base_scope = $args[1];
416 }
417 }
418 }
419
420 $blks = [$blks] if defined $blks && !ref($blks);
421 ref $blks eq 'ARRAY' && @$blks or return {};
422
423 my $table_info = $self->table_info($tableid);
424 return {} unless $table_info && $table_info->{use_facet};
425
426 my $use_ramdisk = $table_info ? ( $table_info->{use_ramdisk} // $table_info->{use_cache} // 0 ) : 0;
427 if ($use_ramdisk) {
428 $self->ramdisk_ensure($tableid);
429 }
430 my $table_path = $self->table_path($tableid);
431 my $idx_path = $use_ramdisk ? $self->ramdisk_path($tableid) : $table_path;
432 my $fac_path = ( -e "${idx_path}.fac" ) ? "${idx_path}.fac" : "${table_path}.fac";
433 my $unq_path = ( -e "${idx_path}.unq" ) ? "${idx_path}.unq" : "${table_path}.unq";
434 my $index_path = ( -e "${idx_path}.inx" ) ? "${idx_path}.inx" : "${table_path}.inx";
435
436 my $r_opts = ( @args == 1 && ref($args[0]) eq 'HASH' ) ? $args[0] : ( @args >= 2 && ref($args[1]) eq 'HASH' ? $args[1] : undef );
437 if ($r_opts) {
438 if ( my $ranges = $self->normalize_range_opts( $tableid, $r_opts ) ) {
439 if ( $base_scope && @$base_scope ) {
440 my @scoped = $self->filter_ids_by_range( $tableid, $base_scope, $ranges );
441 $base_scope = \@scoped;
442 }
443 else {
444 my ( undef, @all_active );
445 ( undef, @all_active ) = $self->index_get( $fac_path, "active" ) if -e $fac_path;
446 unless (@all_active) {
447 ( undef, @all_active ) = $self->index_get( $index_path, "keys" ) if -e $index_path;
448 }
449 @all_active = $self->table_keys($tableid) unless @all_active;
450 my @scoped = $self->filter_ids_by_range( $tableid, \@all_active, $ranges );
451 $base_scope = \@scoped;
452 }
453 }
454 }
455
456 my @scan_ids;
457 if ( $base_scope && ref($base_scope) eq 'ARRAY' && @$base_scope ) {
458 @scan_ids = @$base_scope;
459 }
460 elsif ( $table_info->{facet_rules} && -e $fac_path ) {
461 ( undef, @scan_ids ) = $self->index_get( $fac_path, "active" );
462 }
463
464 my %all_counts;
465
466 if ( -e $fac_path ) {
467 if (@scan_ids) {
468 for my $blk (@$blks) {
469 my @keys = map { "$blk:$_" } @scan_ids;
470 my $res = $self->recs_get( $fac_path, @keys );
471 for my $id (@scan_ids) {
472 my $raw = $res ? $res->{"$blk:$id"} : undef;
473 next unless defined $raw && $raw ne '';
474 my @vals = ( index( $raw, "\t" ) == -1 ) ? ($raw) : split /\t/, $raw;
475 for my $v (@vals) {
476 $all_counts{$blk}{$v}++;
477 }
478 }
479 }
480 }
481 else {
482 my %wanted_blks = map { ( ref($_) eq 'HASH' ? $_->{blk} : $_ ) => 1 } @$blks;
483 $self->recs_scan(
484 $fac_path,
485 sub {
486 my ( $k, $raw ) = @_;
487 return unless defined $raw && $raw ne '';
488 return unless $k =~ /^(\d+):(\d+)$/;
489 my ( $k_blk, $rid ) = ( $1, $2 );
490 return unless $wanted_blks{$k_blk};
491 my @vals = ( index( $raw, "\t" ) == -1 ) ? ($raw) : split /\t/, $raw;
492 for my $v (@vals) {
493 $all_counts{$k_blk}{$v}++;
494 }
495 }
496 );
497 }
498 }
499 elsif (@scan_ids) {
500 my @recs = $self->read_list( $tableid, \@scan_ids );
501 for my $blk (@$blks) {
502 my $b = ref($blk) eq 'HASH' ? $blk->{blk} : $blk;
503 for my $r (@recs) {
504 next unless ref($r) eq 'ARRAY';
505 my $raw = $r->[$b];
506 next unless defined $raw && $raw ne '';
507 my @vals = ref($raw) eq 'ARRAY' ? @$raw : ( $raw =~ /[,;\t]/ ? split(/\s*[,;\t]\s*/, $raw) : ($raw) );
508 for my $v (@vals) {
509 $all_counts{$b}{$v}++;
510 }
511 }
512 }
513 }
514 else {
515 return \%all_counts;
516 }
517
518 if ( -e $unq_path && %all_counts ) {
519 for my $blk ( keys %all_counts ) {
520 my $cnt_map = $all_counts{$blk};
521 next unless $cnt_map && ref($cnt_map) eq 'HASH' && %$cnt_map;
522 my @val_ids = keys %$cnt_map;
523 my @n_keys = map { "$blk:n:$_" } @val_ids;
524 my $names = $self->index_get( $unq_path, \@n_keys, 'raw' );
525 if ( $names && ref($names) eq 'HASH' && %$names ) {
526 my %named_map;
527 for my $vid (@val_ids) {
528 my $name = $names->{"$blk:n:$vid"} // $vid;
529 $named_map{$name} = $cnt_map->{$vid};
530 }
531 $all_counts{$blk} = \%named_map;
532 }
533 }
534 }
535
536 return \%all_counts;
537 }
538
539 # Generates schema-driven facet menu structure and performs active filtering.
540 # my $result = $adb->facet_menu($tableid, [\%options]);
541 # options: selected => \%selected, facet_defs => \@facet_defs, offset => 0, limit => 20, base_ids => \@base_scope
542 # Legacy: my $result = $adb->facet_menu($tableid, \%selected, \@facet_defs, \%opts);
543 # ------------------------------------------------
544 sub facet_menu {
545
546 my ( $self, $tableid, @args ) = @_;
547
548 $tableid or return ( wantarray ? () : {} );
549 my $table_info = $self->table_info($tableid);
550 return ( wantarray ? () : {} ) unless $table_info && $table_info->{use_facet};
551
552 my ( $fac_path, $unq_path, $index_path, $table_path ) = $self->_facet_paths( $tableid, $table_info );
553
554 my ( $selected, $facet_defs, $opts, $base_scope, $active_filter ) =
555 $self->_facet_parse_args( $tableid, $table_info, $fac_path, $index_path, @args );
556
557 # Engine-level volatile RAM-disk Facet Cache (Tier 3 catalog_facetmem)
558 my ( $cache_table, $cache_key ) = $self->_facet_cache_info( $tableid, $table_info, $opts, $base_scope, $active_filter );
559 if ( $cache_table && $cache_key ) {
560 if ( my $cached = $self->_facet_cache_read( $cache_table, $cache_key ) ) {
561 return wantarray ? @{ $cached->{groups} || [] } : $cached;
562 }
563 }
564
565 # 1. Active Filtering (Filtered IDs)
566 my ( $total_count, $filtered_ids, $all_filtered_ids ) = $self->_facet_filter_ids(
567 $tableid, $active_filter, $base_scope, $opts->{offset} // 0, $opts->{limit} // 0, $fac_path, $index_path
568 );
569
570 # 2. Compute Facet Counts (Disjunctive / Multi-pass Optimized)
571 my $all_counts = $self->_facet_calc_counts(
572 $tableid, $facet_defs, $active_filter, $base_scope, $all_filtered_ids, $fac_path, $unq_path
573 );
574
575 # 3. Build Menu Groups, Whitelist & Batch Label Resolution (.unq / RDBM)
576 my ( $groups, $groups_by_blk, $active_counts ) = $self->_facet_build_groups(
577 $tableid, $table_info, $facet_defs, $all_counts, $active_filter, $table_path
578 );
579
580 my $res = {
581 count => $total_count,
582 ids => $filtered_ids,
583 groups => $groups,
584 groups_by_blk => $groups_by_blk,
585 active_counts => $active_counts,
586 counts => $all_counts,
587 };
588
589 if ( $cache_table && $cache_key ) {
590 $self->_facet_cache_write( $cache_table, $cache_key, $res );
591 }
592
593 return wantarray ? @$groups : $res;
594 }
595
596 # =====================================================================
597 # PRIVATE HELPER METHODS FOR facet_menu
598 # =====================================================================
599
600 sub _facet_paths {
601 my ( $self, $tableid, $table_info ) = @_;
602
603 my $use_ramdisk = $table_info ? ( $table_info->{use_ramdisk} // $table_info->{use_cache} // 0 ) : 0;
604 if ($use_ramdisk) {
605 $self->ramdisk_ensure($tableid);
606 }
607 my $table_path = $self->table_path($tableid);
608 my $idx_path = $use_ramdisk ? $self->ramdisk_path($tableid) : $table_path;
609 my $fac_path = ( -e "${idx_path}.fac" ) ? "${idx_path}.fac" : "${table_path}.fac";
610 my $unq_path = ( -e "${idx_path}.unq" ) ? "${idx_path}.unq" : "${table_path}.unq";
611 my $index_path = ( -e "${idx_path}.inx" ) ? "${idx_path}.inx" : "${table_path}.inx";
612
613 return ( $fac_path, $unq_path, $index_path, $table_path );
614 }
615
616 sub _facet_parse_args {
617 my ( $self, $tableid, $table_info, $fac_path, $index_path, @args ) = @_;
618
619 my ( $selected, $facet_defs, $opts );
620 if ( @args == 1 && ref( $args[0] ) eq 'HASH' ) {
621 my $arg = $args[0];
622 if ( exists $arg->{selected}
623 || exists $arg->{facet_defs}
624 || exists $arg->{offset}
625 || exists $arg->{start}
626 || exists $arg->{limit}
627 || exists $arg->{base_ids}
628 || exists $arg->{scope_ids}
629 || exists $arg->{blocks}
630 || exists $arg->{filter}
631 || exists $arg->{where}
632 || exists $arg->{match} )
633 {
634 $opts = $arg;
635 $selected = $arg->{selected} || $arg->{filter} || $arg->{where} || $arg->{match} || {};
636 $facet_defs = $arg->{facet_defs} || $arg->{blocks} || $table_info->{facet_block} || [];
637 }
638 else {
639 $selected = $arg;
640 $facet_defs = $table_info->{facet_block} || [];
641 $opts = {};
642 }
643 }
644 else {
645 ( $selected, $facet_defs, $opts ) = @args;
646 }
647
648 $selected ||= {};
649 $facet_defs ||= $table_info->{facet_block} || [];
650 $opts ||= {};
651
652 my $base_scope = $opts->{base_ids} || $opts->{scope_ids} || undef;
653 if ( my $ranges = $self->normalize_range_opts( $tableid, { filter => $selected } ) ) {
654 if ( $base_scope && @$base_scope ) {
655 my @scoped = $self->filter_ids_by_range( $tableid, $base_scope, $ranges );
656 $base_scope = \@scoped;
657 }
658 else {
659 my ( undef, @all_active );
660 ( undef, @all_active ) = $self->index_get( $fac_path, "active" ) if -e $fac_path;
661 unless (@all_active) {
662 ( undef, @all_active ) = $self->index_get( $index_path, "keys" ) if -e $index_path;
663 }
664 @all_active = $self->table_keys($tableid) unless @all_active;
665 my @scoped = $self->filter_ids_by_range( $tableid, \@all_active, $ranges );
666 $base_scope = \@scoped;
667 }
668 }
669
670 my %active_filter;
671 for my $raw_k ( keys %$selected ) {
672 my $blk = $raw_k;
673 $blk =~ s/^f//;
674 my $v = $selected->{$raw_k};
675 if ( defined $v && $v ne '' ) {
676 if ( ref($v) eq 'HASH' ) {
677 $active_filter{$blk} = $v;
678 }
679 else {
680 my @vals = ref($v) eq 'ARRAY' ? @$v : split /,/, $v;
681 @vals = grep { defined $_ && $_ ne '' } @vals;
682 $active_filter{$blk} = \@vals if @vals;
683 }
684 }
685 }
686
687 return ( $selected, $facet_defs, $opts, $base_scope, \%active_filter );
688 }
689
690 sub _facet_cache_info {
691 my ( $self, $tableid, $table_info, $opts, $base_scope, $active_filter ) = @_;
692
693 my ($dbase) = ( $tableid =~ /^([a-z0-9]+)_/i );
694 $dbase //= "catalog";
695 my $candidate_table = "${dbase}_facetmem";
696 my $cinfo = $self->table_info($candidate_table);
697
698 my $cache_table = $opts->{cache_table}
699 || $table_info->{facet_cache_table}
700 || ( ( $cinfo && ( $cinfo->{use_ramdisk} // 0 ) == 3 ) ? $candidate_table : undef );
701
702 return () unless $cache_table;
703
704 my $scope_sig = "all";
705 if ( defined $opts->{scope_key} && length $opts->{scope_key} ) {
706 $scope_sig = $opts->{scope_key};
707 }
708 elsif ( $base_scope && ref($base_scope) eq 'ARRAY' && @$base_scope ) {
709 if ( @$base_scope <= 10 ) {
710 $scope_sig = "s:" . join( ',', @$base_scope );
711 }
712 else {
713 $scope_sig = "s:" . scalar(@$base_scope) . ":" . $base_scope->[0] . ":" . $base_scope->[-1];
714 }
715 }
716
717 my $flt_sig = "all";
718 if ( $active_filter && %$active_filter ) {
719 my @f_tokens;
720 for my $blk ( sort { $a cmp $b } keys %$active_filter ) {
721 my $v = $active_filter->{$blk};
722 if ( ref($v) eq 'HASH' ) {
723 push @f_tokens, "$blk=" . ( $v->{min} // '' ) . '-' . ( $v->{max} // '' );
724 }
725 elsif ( ref($v) eq 'ARRAY' ) {
726 push @f_tokens, "$blk=" . join( ',', sort @$v );
727 }
728 else {
729 push @f_tokens, "$blk=$v";
730 }
731 }
732 $flt_sig = join( ';', @f_tokens );
733 }
734
735 my $cache_key = "fm:$tableid:$scope_sig:$flt_sig";
736 return ( $cache_table, $cache_key );
737 }
738
739 sub _facet_cache_read {
740 my ( $self, $cache_table, $cache_key ) = @_;
741
742 my @cached_rec = $self->read_id( $cache_table, $cache_key );
743 if ( @cached_rec && defined $cached_rec[1] && ref( $cached_rec[1] ) eq 'HASH' ) {
744 return $cached_rec[1];
745 }
746 return;
747 }
748
749 sub _facet_cache_write {
750 my ( $self, $cache_table, $cache_key, $res ) = @_;
751
752 my $bin = $self->db_encode($res);
753 if ( defined $bin && length $bin ) {
754 $self->insert_id( $cache_table, $cache_key, $bin );
755 }
756 }
757
758 sub _facet_filter_ids {
759 my ( $self, $tableid, $active_filter, $base_scope, $offset, $limit, $fac_path, $index_path ) = @_;
760
761 my ( $filtered_ids, $total_count ) = ( [], 0 );
762 my $all_filtered_ids = [];
763
764 if ( $active_filter && %$active_filter ) {
765 my $f_res = $self->field_filter(
766 $tableid,
767 {
768 type => 'and',
769 filter => $active_filter,
770 ( ( $base_scope && @$base_scope ) ? ( base_ids => $base_scope ) : () ),
771 }
772 );
773
774 $all_filtered_ids = $f_res->{ids} || [];
775 if ( $base_scope && @$base_scope ) {
776 my %scope_map = map { $_ => 1 } @$base_scope;
777 $all_filtered_ids = [ grep { $scope_map{$_} } @$all_filtered_ids ];
778 }
779 }
780 elsif ( $base_scope && @$base_scope ) {
781 $all_filtered_ids = $base_scope;
782 }
783 else {
784 my @all_active;
785 ( undef, @all_active ) = $self->index_get( $fac_path, "active" ) if -e $fac_path;
786 unless (@all_active) {
787 ( undef, @all_active ) = $self->index_get( $index_path, "keys" ) if -e $index_path;
788 }
789 @all_active = $self->table_keys($tableid) unless @all_active;
790 $all_filtered_ids = \@all_active;
791 }
792
793 $total_count = scalar @$all_filtered_ids;
794 if ($limit) {
795 my ( undef, @slice ) = $self->recs_cutting( $offset, $limit, @$all_filtered_ids );
796 $filtered_ids = \@slice;
797 }
798 else {
799 $filtered_ids = $all_filtered_ids;
800 }
801
802 return ( $total_count, $filtered_ids, $all_filtered_ids );
803 }
804
805 sub _facet_calc_counts {
806 my ( $self, $tableid, $facet_defs, $active_filter, $base_scope, $all_filtered_ids, $fac_path, $unq_path ) = @_;
807
808 my %all_counts;
809 if ( !$active_filter || !%$active_filter ) {
810 my @blks = map { ref($_) eq 'HASH' ? $_->{blk} : $_ } @$facet_defs;
811 my $raw_counts = $self->field_allfltkeys( $tableid, \@blks, $base_scope );
812 return $raw_counts || {};
813 }
814
815 my ( @unselected_blks, @selected_blks );
816 for my $cfg (@$facet_defs) {
817 my $blk = ref($cfg) eq 'HASH' ? $cfg->{blk} : $cfg;
818 if ( exists $active_filter->{$blk} ) {
819 push @selected_blks, $blk;
820 }
821 else {
822 push @unselected_blks, $blk;
823 }
824 }
825
826 my %rec_cache;
827 my $get_records = sub {
828 my ($ids) = @_;
829 return [] unless $ids && @$ids;
830 my @missing = grep { !exists $rec_cache{$_} } @$ids;
831 if (@missing) {
832 my @fetched = $self->read_list( $tableid, \@missing );
833 for my $r (@fetched) {
834 if ( ref($r) eq 'ARRAY' && defined $r->[0] ) {
835 $rec_cache{ $r->[0] } = $r;
836 }
837 }
838 }
839 return [ map { $rec_cache{$_} } grep { defined $rec_cache{$_} } @$ids ];
840 };
841
842 # A. Tally unselected blocks from $all_filtered_ids in a single pass
843 if (@unselected_blks) {
844 if ( -e $fac_path && @$all_filtered_ids ) {
845 for my $blk (@unselected_blks) {
846 my @keys = map { "$blk:$_" } @$all_filtered_ids;
847 my $res = $self->recs_get( $fac_path, @keys );
848 for my $id (@$all_filtered_ids) {
849 my $raw = $res ? $res->{"$blk:$id"} : undef;
850 next unless defined $raw && $raw ne '';
851 my @vals = ( index( $raw, "\t" ) == -1 ) ? ($raw) : split /\t/, $raw;
852 $all_counts{$blk}{$_}++ for @vals;
853 }
854 }
855 }
856 elsif (@$all_filtered_ids) {
857 my $recs = $get_records->($all_filtered_ids);
858 for my $r (@$recs) {
859 for my $blk (@unselected_blks) {
860 my $raw = $r->[$blk];
861 next unless defined $raw && $raw ne '';
862 my @vals = ref($raw) eq 'ARRAY' ? @$raw : ( $raw =~ /[,;\t]/ ? split( /\s*[,;\t]\s*/, $raw ) : ($raw) );
863 $all_counts{$blk}{$_}++ for @vals;
864 }
865 }
866 }
867 else {
868 for my $blk (@unselected_blks) {
869 $all_counts{$blk} = {};
870 }
871 }
872 }
873
874 # B. Tally selected blocks (disjunctive filtering)
875 for my $blk (@selected_blks) {
876 my %excl = %$active_filter;
877 delete $excl{$blk};
878
879 if ( !%excl ) {
880 if ( $base_scope && @$base_scope ) {
881 if ( -e $fac_path ) {
882 my @keys = map { "$blk:$_" } @$base_scope;
883 my $res = $self->recs_get( $fac_path, @keys );
884 for my $id (@$base_scope) {
885 my $raw = $res ? $res->{"$blk:$id"} : undef;
886 next unless defined $raw && $raw ne '';
887 my @vals = ( index( $raw, "\t" ) == -1 ) ? ($raw) : split /\t/, $raw;
888 $all_counts{$blk}{$_}++ for @vals;
889 }
890 }
891 else {
892 my $recs = $get_records->($base_scope);
893 for my $r (@$recs) {
894 my $raw = $r->[$blk];
895 next unless defined $raw && $raw ne '';
896 my @vals = ref($raw) eq 'ARRAY' ? @$raw : ( $raw =~ /[,;\t]/ ? split( /\s*[,;\t]\s*/, $raw ) : ($raw) );
897 $all_counts{$blk}{$_}++ for @vals;
898 }
899 }
900 }
901 else {
902 my $raw_counts = $self->field_allfltkeys( $tableid, [$blk] );
903 $all_counts{$blk} = $raw_counts->{$blk} || {};
904 }
905 }
906 else {
907 my $fobj = $self->field_filter(
908 $tableid,
909 {
910 type => 'and',
911 filter => \%excl,
912 ( ( $base_scope && @$base_scope ) ? ( base_ids => $base_scope ) : () ),
913 }
914 );
915 my $sub_ids = $fobj->{ids} || [];
916 if ( $base_scope && @$base_scope ) {
917 my %smap = map { $_ => 1 } @$base_scope;
918 $sub_ids = [ grep { $smap{$_} } @$sub_ids ];
919 }
920 if ( -e $fac_path && @$sub_ids ) {
921 my @keys = map { "$blk:$_" } @$sub_ids;
922 my $res = $self->recs_get( $fac_path, @keys );
923 for my $id (@$sub_ids) {
924 my $raw = $res ? $res->{"$blk:$id"} : undef;
925 next unless defined $raw && $raw ne '';
926 my @vals = ( index( $raw, "\t" ) == -1 ) ? ($raw) : split /\t/, $raw;
927 $all_counts{$blk}{$_}++ for @vals;
928 }
929 }
930 elsif (@$sub_ids) {
931 my $recs = $get_records->($sub_ids);
932 for my $r (@$recs) {
933 my $raw = $r->[$blk];
934 next unless defined $raw && $raw ne '';
935 my @vals = ref($raw) eq 'ARRAY' ? @$raw : ( $raw =~ /[,;\t]/ ? split( /\s*[,;\t]\s*/, $raw ) : ($raw) );
936 $all_counts{$blk}{$_}++ for @vals;
937 }
938 }
939 else {
940 $all_counts{$blk} = {};
941 }
942 }
943 }
944
945 # Resolve dictionary names from .unq if present
946 if ( -e $unq_path && %all_counts ) {
947 for my $blk ( keys %all_counts ) {
948 my $cnt_map = $all_counts{$blk};
949 next unless $cnt_map && ref($cnt_map) eq 'HASH' && %$cnt_map;
950 my @val_ids = keys %$cnt_map;
951 my @n_keys = map { "$blk:n:$_" } @val_ids;
952 my $names = $self->index_get( $unq_path, \@n_keys, 'raw' );
953 if ( $names && ref($names) eq 'HASH' && %$names ) {
954 my %named_map;
955 for my $vid (@val_ids) {
956 my $name = $names->{"$blk:n:$vid"} // $vid;
957 $named_map{$name} = $cnt_map->{$vid};
958 }
959 $all_counts{$blk} = \%named_map;
960 }
961 }
962 }
963
964 return \%all_counts;
965 }
966
967 sub _facet_build_groups {
968 my ( $self, $tableid, $table_info, $facet_defs, $all_counts, $active_filter, $table_path ) = @_;
969
970 my @groups;
971 my %groups_by_blk;
972 my %active_counts;
973
974 for my $cfg (@$facet_defs) {
975 my $blk = ref($cfg) eq 'HASH' ? $cfg->{blk} : $cfg;
976 my $label = ref($cfg) eq 'HASH' ? ( $cfg->{label} // "Grup $blk" ) : "Grup $blk";
977 $label = $self->utf_decode($label) if defined $label;
978 my $counts = $all_counts->{$blk} // {};
979
980 next unless %$counts || ( ref($cfg) eq 'HASH' && $cfg->{required} );
981
982 my @vals = keys %$counts;
983
984 # Whitelist: filter_block
985 if ( ref($cfg) eq 'HASH' && $cfg->{filter_block} ) {
986 my @fb = @{ $cfg->{filter_block} };
987 my ( $fb_blk, $fb_op, $fb_val ) = @fb == 3 ? @fb : ( $fb[0], 'eq', $fb[1] );
988 my $all_map = $self->field_keyvals( $cfg->{table}, $fb_blk );
989 my %allowed;
990 for my $k ( keys %$all_map ) {
991 if ( $self->_cmp_op( $k, $fb_op, $fb_val ) ) {
992 $allowed{$_} = 1 for @{ $all_map->{$k} };
993 }
994 }
995 @vals = grep { $allowed{$_} } @vals;
996 }
997
998 # filter_op on value
999 if ( ref($cfg) eq 'HASH' && $cfg->{filter_op} ) {
1000 my ( $fo_op, $fo_val ) = @{ $cfg->{filter_op} };
1001 @vals = grep { $self->_cmp_op( $_, $fo_op, $fo_val ) } @vals;
1002 }
1003
1004 # csv_list whitelist if defined
1005 if ( ref($cfg) eq 'HASH' && defined $cfg->{csv_list} && $cfg->{csv_list} ne '' ) {
1006 my %csv_allowed = map { $_ => 1 } split /,/, $cfg->{csv_list};
1007 @vals = grep { $csv_allowed{$_} } @vals;
1008 }
1009
1010 # Skip empty strings and optionally zero
1011 if ( ref($cfg) eq 'HASH' && ( $cfg->{skip_zero} || ( $cfg->{id} && $cfg->{id} eq 'year' ) ) ) {
1012 @vals = grep { defined $_ && $_ ne '' && $_ ne '0' && $_ != 0 } @vals;
1013 }
1014 else {
1015 @vals = grep { defined $_ && $_ ne '' } @vals;
1016 }
1017
1018 # Sorting
1019 my $sort_mode = ( ref($cfg) eq 'HASH' ? $cfg->{sort} : '' ) || 'count';
1020 if ( $sort_mode eq 'count' ) {
1021 @vals = sort { ( $counts->{$b} || 0 ) <=> ( $counts->{$a} || 0 ) } @vals;
1022 }
1023 elsif ( $sort_mode eq 'value' ) {
1024 my $sort_dir = ( ref($cfg) eq 'HASH' ? ( $cfg->{sort_dir} || 'desc' ) : 'desc' );
1025 if ( $sort_dir eq 'desc' ) {
1026 @vals = sort { ( $b =~ /^\d+$/ && $a =~ /^\d+$/ ) ? ( $b <=> $a ) : ( $b cmp $a ) } @vals;
1027 }
1028 else {
1029 @vals = sort { ( $a =~ /^\d+$/ && $b =~ /^\d+$/ ) ? ( $a <=> $b ) : ( $a cmp $b ) } @vals;
1030 }
1031 }
1032
1033 # Top-N Limiting (defaults to 20 for rich UI presentation)
1034 my $limit_n = ( ref($cfg) eq 'HASH' ? ( $cfg->{limit} // $cfg->{display_limit} // 20 ) : 20 );
1035 if ( $limit_n && @vals > $limit_n ) {
1036 @vals = @vals[ 0 .. ( $limit_n - 1 ) ];
1037 }
1038
1039 # Batch Label Resolution (RDBM -> .unq bidirectional -> option)
1040 my %name_map;
1041 if ( ref($cfg) eq 'HASH' && $cfg->{table} ) {
1042 if (@vals) {
1043 my @recs = $self->read_list( $cfg->{table}, \@vals );
1044 my $name_idx = $cfg->{name_idx} // 2;
1045 %name_map = map { $_->[0] => $_->[$name_idx] } @recs;
1046 }
1047 }
1048 else {
1049 my $unq_file = "${table_path}.unq";
1050 if ( -e $unq_file && @vals ) {
1051 my @n_keys = map { "$blk:n:$_" } @vals;
1052 my $res = $self->index_get( $unq_file, \@n_keys, 'raw' );
1053 if ( $res && ref($res) eq 'HASH' ) {
1054 for my $val (@vals) {
1055 my $text = $res->{"$blk:n:$val"};
1056 if ( defined $text && $text ne '' ) {
1057 $name_map{$val} = $text;
1058 }
1059 }
1060 }
1061 }
1062
1063 my $opt_str = $table_info->{blocks}->[$blk]->{option} // '';
1064 if ($opt_str) {
1065 for my $pair ( split /,/, $opt_str ) {
1066 my ( $v, $l ) = split /:/, $pair, 2;
1067 $name_map{$v} //= $l // $v;
1068 }
1069 }
1070 }
1071
1072 # Active status for this block
1073 my %selected_vals;
1074 my $active_cnt = 0;
1075 if ( $active_filter && exists $active_filter->{$blk} ) {
1076 my $v = $active_filter->{$blk};
1077 if ( ref($v) eq 'ARRAY' ) {
1078 %selected_vals = map { $_ => 1 } @$v;
1079 $active_cnt = scalar keys %selected_vals;
1080 }
1081 elsif ( ref($v) eq 'HASH' ) {
1082 $active_cnt = ( ( defined $v->{min} && length( $v->{min} ) ) || ( defined $v->{max} && length( $v->{max} ) ) ) ? 1 : 0;
1083 }
1084 elsif ( defined $v && $v ne '' ) {
1085 $selected_vals{$v} = 1;
1086 $active_cnt = 1;
1087 }
1088 }
1089 $active_counts{$blk} = $active_cnt;
1090
1091 my @items;
1092 for my $val (@vals) {
1093 push @items, {
1094 uid => "fc_${blk}_${val}",
1095 param => "f$blk",
1096 val => $val,
1097 label => ( $name_map{$val} // $val ),
1098 count => ( $counts->{$val} // 0 ),
1099 checked => ( $selected_vals{$val} ? "1" : "" ),
1100 };
1101 }
1102
1103 my $group_data = {
1104 blk => $blk,
1105 name => $label,
1106 active => ( $active_cnt ? "1" : "" ),
1107 active_count => $active_cnt,
1108 records => \@items,
1109 };
1110
1111 push @groups, $group_data;
1112 $groups_by_blk{$blk} = \@items;
1113 }
1114
1115 return ( \@groups, \%groups_by_blk, \%active_counts );
1116 }
1117
1118 =encoding utf8
1119
1120 =head1 NAME
1121
1122 AmberDB::Index::Facet - Column-oriented facet indexing, disjunctive counting, and navigation menu generator
1123
1124 =head1 SYNOPSIS
1125
1126 # Querying from AmberDB instance ($adb inherits AmberDB::Index::Facet):
1127
1128 # 1. Generate full-catalog or filtered facet menu with disjunctive counts:
1129 my $menu_data = $adb->facet_menu(
1130 "catalog_product",
1131 { 1 => "5", 2 => [ "12", "14" ] }, # %selected_filters
1132 \@facet_block_definitions,
1133 { sort => 'count', top => 10 } # %options
1134 );
1135
1136 # 2. Dynamic Scoped facet menu (e.g. within search results or category scope):
1137 my $search_facets = $adb->facet_menu(
1138 "catalog_product",
1139 \%selected,
1140 \@facet_defs,
1141 { base_ids => \@search_result_ids }
1142 );
1143
1144 # 3. Direct facet key counts for a single block:
1145 my $counts = $adb->field_fltkeys("catalog_product", {
1146 target_block => 2,
1147 base_ids => \@active_product_ids,
1148 });
1149
1150 =head1 DESCRIPTION
1151
1152 C<AmberDB::Index::Facet> provides a high-performance, column-oriented forward indexing and disjunctive facet aggregation engine designed for low-latency faceted navigation across large-scale catalogs.
1153
1154 B<Inheritance Note:> C<AmberDB> inherits from C<AmberDB::Index::Facet> via C<use parent>. All facet query and menu methods documented below are invoked directly on C<$adb>.
1155
1156 =head1 KEY ARCHITECTURAL FEATURES
1157
1158 =over 4
1159
1160 =item * B<1. Columnar Unified Storage (C<$table_path.fac>):> Facet data is stored in a unified columnar forward index file (C<$table_path.fac>). Each record's block values are keyed as C<$blk:$rid> mapping to packed value IDs, enabling fast single-column and multi-column scans.
1161
1162 =item * B<2. Active-Only Storage Guarantee:> Facet index files store B<only currently active records>. Inactive, discontinued, or out-of-stock records violating C<facet_rules> / C<junk_rules> are excluded during indexing, eliminating the overhead of scanning historical records.
1163
1164 =item * B<3. Bidirectional String Dictionary (C<.unq>):> Text facets (e.g. colors, specifications) map transparently between string labels and compact numeric dictionary IDs.
1165
1166 =item * B<4. Dynamic Scoping (C<base_ids>):> When computing facet counts within search results or subcategories, passing C<base_ids =E<gt> \@ids> bounds the aggregation strictly to matching records.
1167
1168 =item * B<5. Multi-Select Disjunctive Faceting:> Supports multi-selection where checking multiple items within the same filter group uses OR logic (showing counts of remaining options), while combining across different filter groups uses AND logic.
1169
1170 =back
1171
1172 =head1 METHODS
1173
1174 =head2 facet_menu($tableid, [\%options])
1175
1176 High-level faceted navigation menu generator.
1177
1178 Options:
1179 =over 4
1180 =item * C<selected>: Hash of currently active filter selections: C<{ block_idx =E<gt> $val_or_arr_ref }>. (Aliases: C<filter>, C<where>, C<match>).
1181 =item * C<facet_defs>: Array of facet block definitions (or reads directly from table schema C<facet_block> if omitted).
1182 =item * C<offset>: Pagination start offset (default: 0).
1183 =item * C<limit>: Page size limit (default: 0 = unpaginated).
1184 =item * C<base_ids>: (Alias: C<scope_ids>) Array reference of record IDs to scope calculation (e.g. search result IDs).
1185 =item * C<sort>: C<'count'> (default, descending count) or C<'label'> / C<'name'> (alphabetical).
1186 =item * C<top>: Limit maximum items returned per facet group (e.g. 10).
1187 =item * C<min_count>: Minimum count required to include an item (default: 1).
1188 =item * C<range>: Numerical / chronological range filtering C<{ block => 4, min => 1000, max => 2000 }>.
1189 =back
1190
1191 Returns a comprehensive result hash:
1192 C<{ count => $total, ids => \@filtered_ids, groups => \@groups, active_counts => \%counts, counts => \%all_counts }>.
1193
1194 my $menu = $adb->facet_menu("catalog_product", {
1195 selected => { 1 => "5" },
1196 range => { block => "price", min => 1000, max => 2000 },
1197 offset => 0,
1198 limit => 20,
1199 });
1200
1201 Legacy invocation C<$adb->facet_menu($tableid, \%selected, \@facet_defs, \%options)> remains fully supported.
1202
1203 =head2 field_fltkeys($tableid, \%opts)
1204
1205 Calculates facet key counts for a target block directly from active C<.fac>. Automatically resolves dictionary string labels.
1206
1207 Options:
1208 =over 4
1209 =item * C<target_block>: (Required) Attribute block index to aggregate facet counts for.
1210 =item * C<filter>: (Optional, aliases: C<where>, C<match>) Active filter conditions on other blocks C<{ block_idx => $value }>.
1211 =item * C<base_ids>: (Optional, alias: C<scope_ids>) Array reference of record IDs to scope calculation to.
1212 =item * C<range>: (Optional) Numerical / chronological range filtering C<{ block => 4, min => 1000, max => 2000 }>.
1213 =back
1214
1215 my $counts = $adb->field_fltkeys("catalog_product", {
1216 target_block => 2,
1217 filter => { 1 => "5" },
1218 range => { block => "price", min => 1000 },
1219 base_ids => \@scoped_ids,
1220 });
1221
1222 =head2 field_allfltkeys($tableid, [\%options])
1223
1224 Calculates facet key counts across multiple configured blocks from unified C<.fac> in a single pass.
1225
1226 Options:
1227 =over 4
1228 =item * C<target_blocks>: (Required, alias: C<blocks>) Array reference of block indices to aggregate facet counts for.
1229 =item * C<base_ids>: (Optional, alias: C<scope_ids>) Array reference of record IDs to scope calculation to.
1230 =item * C<range>: (Optional) Numerical / chronological range filtering C<{ block => 4, min => 1000, max => 2000 }>.
1231 =back
1232
1233 my $all = $adb->field_allfltkeys("catalog_product", {
1234 target_blocks => [ 1, 2, 4 ],
1235 base_ids => \@scoped_ids,
1236 });
1237
1238 Legacy invocation C<$adb->field_allfltkeys($tableid, \@blk_list, \@base_scope)> remains fully supported.
1239
1240 =head2 facet_rules($table_info, @record)
1241
1242 Evaluates whether a record qualifies for inclusion in facet index files. Automatically integrates with C<junk_rules>.
1243
1244 =head1 AUTHOR
1245
1246 Maruf Cetin <marufcetin@gmail.com>
1247
1248 =head1 LICENSE AND COPYRIGHT
1249
1250 Copyright (C) 2020-2026 Maruf Cetin.
1251
1252 This library is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.
1253
1254 =cut
1255
1256 1;