/ 
Elastic-Model-0.52
River stage one • 1 direct dependent • 1 total dependent
/ Elastic::Model::Results

NAME

Elastic::Model::Results - An iterator over bounded/finite search results

VERSION

version 0.52

SYNOPSIS

Retrieve a list of objects

Twenty most recently updated active users:

$users = $model->view
               ->index  ( 'my_domain' )
               ->type   ( 'user' )
               ->filterb( 'status'    => 'active' )
               ->sort   ( 'timestamp' => 'desc'   )
               ->size   ( 20 )
               ->search
               ->as_objects;

while ( my $user = $users->next ) {
    say $user->name;
}

Retrieve search results

Ten most relevant posts for keywords perl moose created since the beginning of 2012, with highlighted snippets, plus the most popular tags:

$results  = $model->view
                  ->index    ( 'my_domain' )
                  ->type     ( 'posts' )
                  ->queryb   ( 'content' => 'perl moose'  )
                  ->filterb  ( 'created' => { gt => '2012-01-01' } )
                  ->highlight( 'content' )
                  ->facets   ( 'tags' => { terms => { field => 'tags' }} )
                  ->search;

printf  "Showing %d of %d matching docs\n".
         $results->size, $results->total;

Highlights

while ( my $result = $results->next ) {
    say "Title:"      . $result->object->title;
    say "Highlights:" .join ', ', $result->highlight('content');
}

Aggregations

my $tags  = $results->agg('tags');
my $terms = $tags->{buckets};

say "Popular tags: ";
for ( @$terms ) {
    say "$_->{key}:  $_->{doc_count}";
}

Facets

my $tags  = $results->facet('tags');
my $terms = $tags->{terms};

say "Popular tags: ";
for ( @$terms ) {
    say "$_->{term}:  $_->{count}";
}

printf "And $tags->{other} more... ", ;

DESCRIPTION

An Elastic::Model::Results object is returned when you call "search()" in Elastic::Model::View, and is intended for searches that retrieve a maximum of size results in a single request.

A $results object can iterate through Elastic::Model::Result objects (with all the result metadata), or just the DocClass object itself (eg MyApp::User). For instance, you can do:

$result = $results->next_result;
$object = $results->next_object;

Or you can set the default type to return:

$results->as_objects;
$object = $results->next;

$results->as_results;
$result = $results->next;

By default, the short accessors return Elastic::Model::Result objects.

Most attributes and accessors in this class come from Elastic::Model::Role::Results and Elastic::Model::Role::Iterator.

Also, see Elastic::Manual::Searching.

ATTRIBUTES

took

$took = $results->took

The number of milliseconds that the request took to run.

size

$size = $results->size

The number of "elements" in the $results object;

total

$total_matching = $results->total

The total number of matching docs found by Elasticsearch. This is distinct from the "size" which contains the number of results RETURNED by Elasticsearch.

max_score

$max_score = $results->max_score

The highest score (relevance) found by Elasticsearch. Note: if you are sorting by a field other than _score then you will need to set "track_scores" in Elastic::Model::View to true to retrieve the "max_score".

aggs

agg

$aggs = $results->aggs
$agg  = $results->agg($agg_name)

Aggregation results, if any were requested with "aggs" in Elastic::Model::View.

facets

facet

$facets = $results->facets
$facet  = $results->facet($facet_name)

Facet results, if any were requested with "facets" in Elastic::Model::View.

elements

\@elements = $results->elements;

An array ref containing all of the data structures that we can iterate over.

\%search_args = $results->search

Contains the hash ref of the search request passed to "search()" in Elastic::Model::Role::Store

ITERATOR CONTROL

index

$index = $results->index;      # index of the current element, or undef
$results->index(0);            # set the current element to the first element
$results->index(-1);           # set the current element to the last element
$results->index(undef);        # resets the iterator, no current element

"index" contains the current index of the iterator. Before you start iterating, it will return undef.

reset

$results->reset;

Resets the iterator so that the next call to "next" will return the first element. Note: any calls to "shift" means that those elements have been discarded. "reset" will not reload these.

INFORMATIONAL ACCESSORS

size

$size = $results->size;

Returns the number of "elements".

even

$bool = $results->even

Is the current "index" even?

odd

$bool = $results->odd

Is the current "index" odd?

parity

$parity = $results->parity

Returns 'odd' or 'even'. Useful for alternating the colour of rows:

while ( my $el = $results->next ) {
    my $css_class = $el->parity;
    # display row
}

is_first

$bool = $results->is_first

Is the "current" element the first element?

is_last

$bool = $results->is_last

Is the "current" element the last element?

has_next

$bool = $results->has_next

Is there a "next" element?

has_prev

$bool = $results->has_prev

Is there a "prev" element?

WRAPPERS

as_results()

$results = $results->as_results;

Sets the "short" accessors (eg "next", "prev") to return Elastic::Model::Result objects.

as_objects()

$objects = $objects->as_objects;

Sets the "short" accessors (eg "next", "prev") to return the object itself, eg MyApp::User

as_elements()

$results->as_elements()

Sets the "short" accessors (eg "next", "prev") to return the raw result returned by Elasticsearch.

as_partials()

$results->as_partials()

Sets the "short" accessors (eg "next", "prev") to return partial objects as specified by "include_paths / exclude_paths" in Elastic::Model::View.

ELEMENT ACCESSORS

All of the accessors below have 4 forms:

  • Result, eg next_result which returns the full result metadata as an Elastic::Model::Result object.

  • Object, eg next_object which returns the original matching object, eg an instance of MyApp::User

  • Element, eg next_element which returns the raw hashref from Elasticsearch

  • Partial Doc, eg next_partial which returns a partial object as specified by "include_paths / exclude_paths" in Elastic::Model::View.

  • Short, which can return any one of the above, depending on which Wrapper is currently in effect.

Typically you would select the type that you need, then use the short accessors, eg:

$results->as_objects;

while (my $object = $result->next ) {...}

first

$el = $results->first

Returns the first element, and resets the iterator so that a call to "next" will return the second element. If there is no first element, it returns undef.

Also first_result, first_object, first_element, first_partial

next

$el = $results->next;

Returns the next element, and advances the iterator by one. If there is no next element, it returns undef. If the next element is the last element, then it will work like this:

$results->next;        # returns last element
$results->next;        # returns undef, and resets iterator
$results->next;        # returns first element

Also next_result, next_object, next_element, next_partial

prev

$el = $results->prev

Returns the previous element, and moves the iterator one step in reverse. If there is no previous element, it returns undef. If the previous element is the first element, then it will work like this:

$results->prev;        # returns prev element
$results->prev;        # returns undef, and resets iterator to end
$results->prev;        # returns last element

Also prev_result, prev_object, prev_element, prev_partial

current

$el = $results->current

Returns the current element, or undef

Also current_result, current_object, current_element, current_partial

last

$el = $results->last

Returns the last element, and resets the iterator so that a call to "next" will return undef, and a second call to "next" will return the first element If there is no last element, it returns undef.

Also last_result, last_object, last_element, last_partial

peek_next

$el = $results->peek_next

Returns the next element (or undef), but doesn't move the iterator.

Also peek_next_result, peek_next_object, peek_next_element, peek_next_partial

peek_prev

$el = $results->peek_prev

Returns the previous element (or undef), but doesn't move the iterator.

Also peek_prev_result, peek_prev_object, peek_prev_element, peek_prev_partial

shift

$el = $results->shift

Returns the "first" element and removes it from from the list. "size" will decrease by 1. Returns undef if there are no more elements.

Also shift_result, shift_object, shift_element, shift_partial

slice

@els = $results->slice($offset,$length);

Returns a list of (max) $length elements, starting at $offset (which is zero-based):

$results->slice();             # all elements;
$results->slice(5);            # elements 5..size
$results->slice(-5);           # elements size-5..size
$results->slice(0,10);         # elements 0..9
$results->slice(5,10);         # elements 5..14

If your iterator only contains 5 elements:

$results->slice(3,10);         # elements 3..4
$results->slice(10,10);        # an empty list

Also slice_results, slice_objects, slice_elements, slice_partials

all

@els = $results->all

Returns all "elements" as a list.

Also all_results, all_objects, all_elements, all_partials

AUTHOR

Clinton Gormley <drtech@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by Clinton Gormley.

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