NAME

Tapper::Metadata

SYNOPSIS

    require YAML::Syck;
    require Tapper::Metadata;
    my $or_meta = Tapper::Metadata->new({
        dbh    => $or_dbh,
        debug  => 0,
        config => YAML::Syck::LoadFile('~/conf/tapper_metadata.conf'),
    });

    my $b_success = $or_meta->add_multi_metadata([
        {
            TESTRUN => 12345,
            key_1   => 'value_1',
            key_2   => 'value_2',
        },{
            TESTRUN => 12346,
            key_3   => 'value_3',
        },
        ...
    ],{
        force => 1,
    });

    my $or_metadata_points = $or_meta->search({
        select      => [
            'TESTRUN',
            'key_2',
        ],
        where       => [
            { operator => '!=', column => 'key_1', values => 'value_1', },
            { operator => '=' , column => 'key_2', values => 'value_2', },
        ],
        order_by    => [
            'key_3',
            { column => 'TESTRUN', direction => 'ASC', numeric => 1 },
        ],
        exclusive   => 1,
        limit       => 2,
        offset      => 1,
    });

    while my $hr_metadata_point ( $or_metadata_points->fetchrow_hashref() ) {
        ...
    }

DESCRIPTION

Tapper::Metadata is a module for adding metadata values in a standardised way to the the database. A search function with complexe filters already exists.

Class Methods

new

  • Create a new Tapper::Metadata object.

        my $or_meta = Tapper::Metadata->new({
            dbh    => $or_dbh,
            debug  => 0,
            config => YAML::Syck::LoadFile('~/conf/tapper_metadata.conf'),
        });
    dbh

    A DBI database handle.

    config [optional]

    Containing the path to the Tapper::Metadata-Configuration-File. See Configuration for details.

    debug [optional]

    Setting debug to a true value results in multiple debugging informations written to STDOUT. The default is 0.

add_single_metadata

  • Add one or more data points to a single metadata to the database.

        my $b_success = $or_meta->add_single_metadata({
            TESTRUN => 12345,
            key_1   => 'value_1',
            key_2   => 'value_2',
        },{
            force => 1
        });
    1st Parameter HASH
    1.1 Parameter Hash => TESTRUN

    The Testrun ID to relate metadata with a testrun.

    2nd Parameter Hash => force [optional]

    Ignore forgivable errors while writing.

add_multi_metadata

Add one or more data points to a multiple metadata to the database.

    my @a_error_idxs = $or_meta->add_multi_metadata([
        {
            TESTRUN => 12345,
            key_1   => 'value_1',
            key_2   => 'value_2',
        },{
            TESTRUN => 12346,
            key_3   => 'value_3',
        },
        ...
    ],{
        force => 1
    });
1st Parameter ARRAY of HASHES
1st 1st Parameter Hash => TESTRUN

The Testrun ID to relate metadata with a testrun.

2nd Parameter Hash => force [optional]

Ignore forgivable errors while writing.

Search for metadata points in the database. Function returns a DBI Statement Handle.

    my $or_metadata_points = $or_meta->search({
        select      => [
            'TESTRUN',
            'key_2',
        ],
        where       => [
            { operator => '!=', column => 'key_1', values => 'value_1', },
            { operator => '=' , column => 'key_2', values => 'value_2', },
        ],
        where_sql   => q#,
            AND NOT(
                   ${TESTRUN} = 123
                OR ${VALUE}   = '144'
            )
        #,
        order_by    => [
            'key_3',
            { column => 'TESTRUN', direction => 'ASC', numeric => 1 },
        ],
        exclusive   => 1,
        limit       => 2,
        offset      => 1,
    });
select [optional]

An Array of Strings or Hash References containing additional selected columns. The default selected columns are: TESTRUN

Add additional data "key_2" as column to selection.

    ...
        select      => [
            'TESTRUN',
            'key_2',
        ],
    ...

Get the maximum "TESTRUN" of all selected data points. All other columns without an aggregation become the default_aggregation from Tapper::Metadata-Configuration. Possible aggregation types are:

    - min = minimum
    - max = maximum
    - avg = average
    - gem = geometric mean
    - sum = summary
    - cnt = count
    - cnd = distinct value count

    ...
        select      => [
            { column => 'TESTRUN', aggregate => 'max', },
            { column => 'key_2'  ,                     },
        ],
    ...

A aggregation is also possible for the default columns.

    ...
        select      => [
            { column => 'TESTRUN', aggregate => 'max', },
            { column => 'key_2'  , aggregate => 'avg', },
        ],
    ...

All additional values internally stored as strings. For the numeric aggegation functions "min", "max", "avg", "gem" and "sum" the "numeric" flag must be set to a true value to cast the value as a numeric.

    ...
        select      => [
            { column => 'TESTRUN', aggregate => 'max', numeric => 1, },
            { column => 'key_2'  , aggregate => 'avg',               },
        ],
    ...
where [optional]

An Array of Hash References containing restrictions for metadata points.

    ...
        where       => [
            { operator => '!=', column => 'key_1', values => 'value_1', },
            { operator => '=' , column => 'key_2', values => 'value_2', },
        ],
    ...

- Parameter in Sub-Hash = operator

    =           - equal
    !=          - not equal
    <           - lower
    >           - greater
    <=          - lower equal
    >=          - greater equal
    like        - SQL LIKE
    not like    - SQL NOT LIKE

- Parameter in Sub-Hash = column

A restriction is possible for additional values and the default columns.

- Parameter in Sub-Hash = values

In general there is just a single value. For '=' and '!=' a check for multiple values is possible. Insert a array reference of values in this case. In SQL it is implemented with IN and NOT IN.

- Parameter in Sub-Hash = numeric [ optional ]

All additional values internally stored as strings. For the numeric operators '<', '<=', '>' and '>=' this flag must be set to a true value to cast the value as a numeric.

where_sql [optional]

A String containing an additional where clause. Please use this feature just if the "where" parameter is not sufficient to restrict.

order_by [optional]

An Array of Strings or an Array of Array References determining the order of returned metadata points.

Array of Strings: column to sort with default order direction "ASC" (ascending)

Array of Strings or Hash References column : column to sort direction : order direction with possible values "ASC" (ascending) and "DESC" (descending) numeric : set a true value for a numeric sort

    ...
        order_by    => [
            'key_3',
            { column => 'TESTRUN', direction => 'ASC', numeric => 1 },
        ],
    ...
limit [optional]

An integer value which determine the number of returned metadata points.

offset [optional]

An integer value which determine the number of omitted metadata points.

Select testruns which contains just the metadata "columns" given by the where attribute.

search_array

Returning all metadata points as Array of Hashes.

    my $ar_metadata_points = $or_meta->search_array({
        select      => [
            'TESTRUN',
            'key_2',
        ],
        where       => [
            { operator => '!=', column => 'key_1', values => 'value_1', },
            { operator => '=' , column => 'key_2', values => 'value_2', },
        ],
        order_by    => [
            'key_3',
            { column => 'TESTRUN', direction => 'ASC', numeric => 1 },
        ],
        limit       => 2,
        offset      => 1,
    });

search_hash

Returning all metadata points as Hash of Hashes. As compared to search search_array this function needs the parameter keys. keys is an Array of Strings which determine the columns used as the keys for the nested hashes. Every "key" create a new nested hash.

    my $or_metadata_points = $or_meta->search_array({
        keys        => [
            'TESTRUN',
            'key_2',
        ],
        select      => [
            'TESTRUN',
            'key_2',
        ],
        where       => [
            { operator => '!=', column => 'key_1', values => 'value_1', },
            { operator => '=' , column => 'key_2', values => 'value_2', },
        ],
        order_by    => [
            'key_3',
            { column => 'TESTRUN', direction => 'ASC', numeric => 1 },
        ],
        limit       => 2,
        offset      => 1,
    });

NAME

Tapper::Metadata - Save and search Metadata points by database

Configuration

The following elements are required in configuration:

default_aggregation

Default aggregation used for non aggregated columns if an aggregation on any other column is found.

tables

Containing the names of the tables used bei Tapper::Metadata

    tables => {
        additional_type_table            => 'bench_additional_types',
        additional_value_table           => 'bench_additional_values',
        additional_type_relation_table   => 'bench_additional_type_relations',
    }
select_cache [optional]

In case of a true value the module cache some select results

AUTHOR

Roberto Schaefer <schaefr@amazon.com>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2016 by Amazon.com, Inc. or its affiliates.

This is free software, licensed under:

  The (two-clause) FreeBSD License