torsten-deriv / perl-flyby

NAME

FlyBy - Ad hoc denormalized querying

SYNOPSIS

use FlyBy;

my $fb = FlyBy->new;
$fb->add_records({array => 'of'}, {hash => 'references'}, {with => 'fields'});
my @array_of_hash_refs = $fb->query({'key' => ['value', 'other value']});

# Or with a 'reduction list':
my @array = $fb->query({'key' => 'value'}, ['some key']);
my @array_of_array_refs = $fb->query({'key' =>'value', 'other key' => 'other value'},
  ['some key', 'some other key']);

DESCRIPTION

FlyBy is a system to allow for ad hoc querying of data which may not exist in a traditional datastore at runtime

USAGE

• add_records

    $fb->add_records({array => 'of'}, {hash => 'references'}, {with => 'fields'});
  

  Supply one or more hash references to be added to the store.

  Keys with undefined values will be silently stripped from each record. If the record is then empty it will be discarded.

  `croak` on error; returns `1` on success

• query

  • string

      $fb->query("'type' IS 'shark' AND 'food' IS 'seal' -> 'called', 'lives_in'");
    

    The query parameters are joined with `IS` for equality testing, or `IS NOT` for its inverse.

    Multiple values for a given key can be combined with `OR`.

    Multiple keys are joined with AND.

    The optional reductions are prefaced with `->`.

    If no reduction is provided a list of the full record hash references is returned. If a reduction list of length 1 is provided, a list of the distinct values for the matching key is returned. If a longer reduction list is provided, a list of distinct value array references (in the provided key order) is returned.

  • raw

      $fb->query({'type' => 'shark', 'food' => 'seal'}, ['called', 'lives_in']");
    

    The query clause is supplied as hash reference of keys and values to be `AND`-ed together for the final result.

    An array reference value is treated as a sucession of 'or'-ed values for the provided key.

    All values prepended with an `!` are deemed to be a negation of the rest of the string as a value.

    A second optional reduction list of strings may be provided which reduces the result as above.

  Will `croak` on improperly supplied query formats.

• all_keys

  Returns an array with all known keys against which one might query.

• values_for_key

  Returns an array of all known values for a given key.

CAVEATS

Note that supplied keys may not begin with an `!`. Thought has been given to making this configurable at creation, but it was deemed to be unnecessary complexity.

This software is in an early state. The internal representation and external API are subject to deep breaking change.

This software is not tuned for efficiency. If it is not being used to resolve many queries on each instance or if the data is available from a single canonical source, there are likely better solutions available in CPAN.

AUTHOR

Binary.com

COPYRIGHT

Copyright 2015- Binary.com

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.