/ 
XAS-Service-0.01
River stage zero No dependents
/ XAS::Service::Search

NAME

XAS::Service::Search - A class to build database queries.

SYNOPSIS

use XAS::Service::Search;
use XAS::Model::Schema;
use XAS::Model::Database
    schema => 'Database',
    tables => ':all'
;

my @fields = ['one', 'two', 'three', 'four', 'five'];
my $params = {
    start => 1,
    limit => 25,
    sort  => qq/[{"field": "one", "direction": "DESC"}]/,
};

my $schema = XAS::Model::Schema->opendb('database');
my $search = XAS::Service::Search->new(-columns => \@fields);
my ($criteria, $options) = $search->build($params);

if (my $records = DataBase->search($schema, $criteria, $options)) {

    while ($my $rec = $records->next) {

    }

}

DESCRIPTION

This module takes a set of parameters and builds search criteria and optional actions for that criteria.

PAGING

Paging of the data source is implemented with these parameters.

start

The start of the offset within the data store. This is a positive integer.

limit

The number of items to return from that offset. This is a positive integer.

Example
$params = {
    start => 0,
    limit => 25
};

SORTING

Sorting of the items in the data source is implemented with these parameters.

sort

This will be a serialized JSON data structure. This needs to be converted into a Perl data structure. This data structure will be an array of hashs and each hash has these fields defined:

field     - the name of the field to sort on
direction - the direction of the sort

Where "field" will be verified as a valid field name, and "direction" must be either "ASC" or "DESC".

Example
$params = {
    sort => qq/[{"field":"email","direction":"DESC"}]/
};

GROUPING

Grouping of the items in the data source is implemented with these parameters.

group

This will be a serialized JSON data structure. This needs to be converted into a Perl data structure. This data structure will be an array of hashs and each hash has these fields defined:

field     - the name of the field to sort on
direction - the direction of the sort

Where "field" will be verified as a valid field name, and "direction" must be either "ASC" or "DESC".

Example
$params = {
    group => qq/[{"field":"email","direction":"ASC"}]/
};

FILTERING

This allows for selecting specific items from the data source. This is implemented with these parameters.

filter

This will be a serialized JSON data structure. This needs to be converted into a Perl data structure. This data structure will be an array of hashs and each hash has these fields defined:

field      - the name of the field
type       - the type of the field
value      - the value for that field
comparison - optional

Where "field" will be verified as a valid field name and "type" can be one of the following:

string, number, list, boolean, date

and "value" depends on the context of the type. So a basic filter would be the following:

$params = {
    filter => qq/[{"field":"email", "type": "string", "value": "kesteb@wsipc.org"}]/
};

Here is an example were "value" can change from a simple string to something else:

$params = {
    filter => qq/[{"field":"email", "type": "list", "value": ["kesteb@wsipc.org","kevin@example.org"]}]/
};

In this case since the "type" is "list", the "value" would be an array. The optional "comparison" parameter can have the following values associated:

lt - less then the value
le - less then or equal to the value
gt - greater then the value
ge - greater then or equal to the value
lk - like the value
be - between two values
eq - equal to the value

The "comparision" parameter is only meaningful with the "string", "number" and "date" types. So now we can expand our filter with something like this:

$params = {
    filter => qq/[{"field":"one", "type": "string", "comparison": "be", "value": ["0", "10"]}]/
};

Which should return all the items where the field "one" is between 0 and 10. So you can build some fairly interesting filters. But remember that if you have multiple filters for on field. The last one will be used. So something like this:

$params = {
    filter => qq/[{"field":"one", "type": "string", "comparison": "lt", "value": "2016-07-30"},
                  {"field":"one", "type": "string", "comparison": "gt", "value": "2016-07-24"}
                 ]/
};

Which would only return items where the field "one" is greater then "2016-07-24" and the cutoff of "2016-07-30" would be silently ignored.

So you can build some rather sophisticated search parameters:

Example
$params => {
    start  => 0,
    limit  => 25,
    sort   => qq/[{"field":"email", "direction":"ASC"}]/,
    filter => qq/[{"field":"email", "type": "string", "comparison": "lk", "value": "kesteb"}]/
};

Which should return all items in a paged response where the field "email" is like 'kesteb'.

METHODS

new

This method initializes the module and takes the following parameter:

-columns

The colums from the database. This is used to verify the search parameters and build the correct data structures for the database queries.

build($params)

This method will build and return the criteria and options data structures for a search query.

$params

A hashref of parameters used for building the search criteria and optional actions for that criteria.

SEE ALSO

XAS::Service
XAS

AUTHOR

Kevin Esteb, <kevin@kesteb.us>

COPYRIGHT AND LICENSE

Copyright (C) 2016 by Kevin L. Esteb

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.