NAME

Database::BI::Extract -- SQLite materialisation cache for Database::BI

SYNOPSIS

use Database::BI::Extract;

my $cache = Database::BI::Extract->new(model_dir => '.bi');

# Check cache
my $path = $cache->get($spec, $mtime, $size);
unless ($path) {
    my $bytes = ...; # build the SQLite file
    $path = $cache->put($spec, $mtime, $size, $bytes);
}

DESCRIPTION

Stores SQLite materialisation files (extracts) under model_dir/extracts/. The cache key is an MD5 of the dataset spec, its source mtime, and its size. Deleting the extracts directory leaves the application fully functional.

The application reads the extract of an accelerated dataset through get, and script/bi-extract builds one through put; see "Accelerated datasets" in Database::BI. The caller decides when to build an extract, and the class only stores and finds the bytes.

METHODS

new

API SPECIFICATION

INPUT

{ model_dir => 'string' }   # required; extracts live in <model_dir>/extracts/

OUTPUT

A Database::BI::Extract object. Croaks model_dir is required without model_dir. Nothing is created on disc until put.

path

API SPECIFICATION

INPUT

$spec    # the dataset spec, e.g. 'table:sales'
$mtime   # source modification time (undef is 0)
$size    # source size in bytes (undef is 0)

OUTPUT

'string'   # <model_dir>/extracts/<md5 of spec, mtime and size>.db

The path is computed, not checked: the file need not exist.

get

API SPECIFICATION

INPUT

The same three arguments as path.

OUTPUT

'string' | undef   # the path when that file exists, otherwise undef

A changed mtime or size gives a different path, so a stale extract is a miss.

put

API SPECIFICATION

INPUT

$spec, $mtime, $size   # as for path
$bytes                 # required; the SQLite file's contents

OUTPUT

'string'   # the path written

Creates extracts/ when it is missing. Croaks sqlite_bytes are required when $bytes is undefined or empty, and croaks naming the path when the directory or file cannot be written.

evict

API SPECIFICATION

INPUT

$spec   # accepted but not used: see below

OUTPUT

'integer'   # the number of files removed (0 when there is no extracts/)

A fingerprint cannot be traced back to its spec, so evict removes every .db file in extracts/, not only $spec's.

AUTHOR

Nigel Horne <njh@nigelhorne.com>

LICENCE AND COPYRIGHT

Copyright 2026 Nigel Horne. Usage is subject to the GPL2 licence terms.

cpanm Database::BI

perl -MCPAN -e shell
install Database::BI