NAME

Rethinkdb::Query - RethinkDB Query

SYNOPSIS

DESCRIPTION

ATTRIBUTES

Rethinkdb::Query implements the following attributes.

args

my $query = r->table('marvel')->get(1);
say $query->args;

The arguments for this instance of a query.

optargs

my $query = r->table('marvel')->get_all(1, { index => 'rank' });
say $query->optargs;

The optional arguments for this instance of a query.

METHODS

Rethinkdb::Query implements the following methods.

new

This is a specialized constructor that enables chaining the queries together in a rational way. This constructor should never be called directly by consumers of this library.

run

r->table('marvel')->run;

Run a query on a connection.

The callback will get either an error, a single JSON result, or a cursor, depending on the query.

update

r->table('posts')->get(1)->update({status => 'published'})->run;

Update JSON documents in a table. Accepts a JSON document, a ReQL expression, or a combination of the two.

replace

r->table('posts')->get(1)->replace({
  id      => 1,
  title   => 'Lorem ipsum',
  content => 'Aleas jacta est',
  status  => 'draft'
})->run;

Replace documents in a table. Accepts a JSON document or a ReQL expression, and replaces the original document with the new one. The new document must have the same primary key as the original document.

delete

r->table('comments')->
  get('7eab9e63-73f1-4f33-8ce4-95cbea626f59')->delete->run;

Delete one or more documents from a table.

filter

r->table('users')->filter({'age' => 30})->run;

Get all the documents for which the given predicate is true.

"filter" can be called on a sequence, selection, or a field containing an array of elements. The return type is the same as the type on which the function was called on.

The body of every filter is wrapped in an implicit default(r->false), which means that if a non-existence errors is thrown (when you try to access a field that does not exist in a document), RethinkDB will just ignore the document. The default value can be changed by passing the named argument default. Setting this optional argument to r->error will cause any non-existence errors to return a runtime_error.

inner_join

r->table('marvel')->inner_join(r->table('dc'), sub($$) {
  my ($marvel, $dc) = @_;
  return marvel->attr('strength')->lt($dc->attr('strength'));
})->run;

Returns the inner product of two sequences (e.g. a table, a filter result) filtered by the predicate. The query compares each row of the left sequence with each row of the right sequence to find all pairs of rows which satisfy the predicate. When the predicate is satisfied, each matched pair of rows of both sequences are combined into a result row.

outer_join

r->table('marvel')->outer_join(r->table('dc'), sub ($$) {
  my ($marvel, $dc) = @_;
  return $marvel->attr('strength')->lt($dc->attr('strength'));
})->run;

Computes a left outer join by retaining each row in the left table even if no match was found in the right table.

eq_join

r->table('players')->eq_join('gameId', r->table('games'))->run;

Join tables using a field on the left-hand sequence matching primary keys or secondary indexes on the right-hand table. "eq_join" is more efficient than other ReQL join types, and operates much faster. Documents in the result set consist of pairs of left-hand and right-hand documents, matched when the field on the left-hand side exists and is non-null and an entry with that field's value exists in the specified index on the right-hand side.

zip

r->table('marvel')->eq_join('main_dc_collaborator',
  r->table('dc'))->zip()->run;

Used to zip up the result of a join by merging the right fields into left fields of each member of the sequence.

map

r->table('marvel')->map(sub {
  my $hero = shift;
  return $hero->attr('combatPower')->add(
    $hero->('compassionPower')->mul(2)
  );
})->run;

Transform each element of the sequence by applying the given mapping function.

with_fields

r->table('users')->with_fields('id', 'username', 'posts')->run;

Plucks one or more attributes from a sequence of objects, filtering out any objects in the sequence that do not have the specified fields. Functionally, this is identical to "has_fields" followed by "pluck" on a sequence.

concat_map

r->table('marvel')->concatMap(sub {
  my $hero = shift;
  return $hero->attr('defeatedMonsters');
})->run;

Concatenate one or more elements into a single sequence using a mapping function.

order_by

r->table('posts')->order_by({index => 'date'})->run;
r->table('posts')->order_by({index => r->desc('date')})->run;

Sort the sequence by document values of the given key(s). To specify the ordering, wrap the attribute with either r->asc or r->desc (defaults to ascending).

Sorting without an index requires the server to hold the sequence in memory, and is limited to 100,000 documents. Sorting with an index can be done on arbitrarily large tables, or after a "between" in Rethinkdb::Query::Table command using the same index.

skip

r->table('marvel')->order_by('successMetric')->skip(10)->run;

Skip a number of elements from the head of the sequence.

limit

r->table('marvel')->order_by('belovedness')->limit(10)->run;

End the sequence after the given number of elements.

slice

r->table('players')->order_by({index => 'age'})->slice(3, 6)->run;

Return the elements of a sequence within the specified range.

nth

r->expr([1,2,3])->nth(1)->run;

Get the nth element of a sequence.

offsets_of

r->expr(['a','b','c'])->offsets_of('c')->run;

Get the indexes of an element in a sequence. If the argument is a predicate, get the indexes of all elements matching it.

is_empty

r->table('marvel')->is_empty->run;

Test if a sequence is empty.

union

r->table('marvel')->union(r->table('dc'))->run;

Concatenate two sequences.

sample

r->table('marvel')->sample(3)->run;

Select a given number of elements from a sequence with uniform random distribution. Selection is done without replacement.

group

r->table('games')->group('player')->max('points')->run;

Takes a stream and partitions it into multiple groups based on the fields or functions provided. Commands chained after "group" will be called on each of these grouped sub-streams, producing grouped data.

ungroup

r->table('games')
  ->group('player')->max('points')->attr('points')
  ->ungroup()->order_by(r->desc('reduction'))->run;

Takes a grouped stream or grouped data and turns it into an array of objects representing the groups. Any commands chained after "ungroup" will operate on this array, rather than operating on each group individually. This is useful if you want to e.g. order the groups by the value of their reduction.

reduce

r->table('posts')->map(sub { return 1; })->reduce(sub($$) {
  my ($left, $right) = @_;
  return $left->add($right);
})->run;

Produce a single value from a sequence through repeated application of a reduction function.

fold

r->table('words')->order_by('id')->fold(
  '',
  sub ($$) {
    my ( $acc, $word ) = @_;
    return $acc->add( r->branch( $acc->eq(''), '', ', ' )->add($word) );
  }
)->run;

r->table('tracker')->filter( { name => 'bob' } )->order_by('date')
  ->bracket('weight')->fold(
  [],
  sub ($$) {
    my ( $acc, $row ) = @_;
    return $acc->append($row)->limit(5);
  },
  sub ($$$) {
    my ( $acc, $row, $new_acc ) = @_;
    return r->branch( new_acc->size()->eq(5), [ new_acc->avg() ], [] );
  }
  )->run;

Apply a function to a sequence in order, maintaining state via an accumulator. The fold command returns either a single value or a new sequence.

count

r->table('marvel')->count->add(r->table('dc')->count->run

Count the number of elements in the sequence. With a single argument, count the number of elements equal to it. If the argument is a function, it is equivalent to calling filter before count.

sum

r->expr([3, 5, 7])->sum->run;

Sums all the elements of a sequence. If called with a field name, sums all the values of that field in the sequence, skipping elements of the sequence that lack that field. If called with a function, calls that function on every element of the sequence and sums the results, skipping elements of the sequence where that function returns null or a non-existence error.

avg

r->expr([3, 5, 7])->avg->run;

Averages all the elements of a sequence. If called with a field name, averages all the values of that field in the sequence, skipping elements of the sequence that lack that field. If called with a function, calls that function on every element of the sequence and averages the results, skipping elements of the sequence where that function returns null or a non-existence error.

min

r->expr([3, 5, 7])->min->run;

Finds the minimum of a sequence. If called with a field name, finds the element of that sequence with the smallest value in that field. If called with a function, calls that function on every element of the sequence and returns the element which produced the smallest value, ignoring any elements where the function returns null or produces a non-existence error.

max

r->expr([3, 5, 7])->max->run;

Finds the maximum of a sequence. If called with a field name, finds the element of that sequence with the largest value in that field. If called with a function, calls that function on every element of the sequence and returns the element which produced the largest value, ignoring any elements where the function returns null or produces a non-existence error.

distinct

r->table('marvel')->concat_map(sub {
  my $hero = shift;
  return $hero->attr('villainList')
})->distinct->run;

Remove duplicate elements from the sequence.

contains

r->table('marvel')->get('ironman')->
  attr('opponents')->contains('superman')->run;

Returns whether or not a sequence contains all the specified values, or if functions are provided instead, returns whether or not a sequence contains values matching all the specified functions.

pluck

r->table('marvel')->get('IronMan')->
  pluck('reactorState', 'reactorPower')->run;

Plucks out one or more attributes from either an object or a sequence of objects (projection).

without

r->table('marvel')->get('IronMan')->without('personalVictoriesList')->run;

The opposite of pluck; takes an object or a sequence of objects, and returns them with the specified paths removed.

merge

r->table('marvel')->get('IronMan')->merge(
  r->table('loadouts')->get('alienInvasionKit')
)->run;

Merge two objects together to construct a new object with properties from both. Gives preference to attributes from other when there is a conflict.

append

r->table('marvel')->get('IronMan')->
  attr('equipment')->append('newBoots')->run;

Append a value to an array.

prepend

r->table('marvel')->get('IronMan')->
  attr('equipment')->prepend('newBoots')->run;

Prepend a value to an array.

difference

r->table('marvel')->get('IronMan')->
  attr('equipment')->difference(['Boots'])->run;

Remove the elements of one array from another array.

set_insert

r->table('marvel')->get('IronMan')->
  attr('equipment')->set_insert('newBoots')->run;

Add a value to an array and return it as a set (an array with distinct values).

set_union

r->table('marvel')->get('IronMan')->
  attr('equipment')->set_union(['newBoots', 'arc_reactor'])->run;

Add a several values to an array and return it as a set (an array with distinct values).

set_intersection

r->table('marvel')->get('IronMan')->attr('equipment')->
  set_intersection(['newBoots', 'arc_reactor'])->run;

Intersect two arrays returning values that occur in both of them as a set (an array with distinct values).

set_difference

r->table('marvel')->get('IronMan')->attr('equipment')->
  set_difference(['newBoots', 'arc_reactor'])->run;

Remove the elements of one array from another and return them as a set (an array with distinct values).

get_field

r->table('marvel')->get('IronMan')->get_field('firstAppearance')->run;

Get a single field from an object. If called on a sequence, gets that field from every object in the sequence, skipping objects that lack it.

bracket

r->table('marvel')->get('IronMan')->bracket('firstAppearance')->run;
r->expr([10, 20, 30, 40, 50])->bracket(3)->run;

Get a single field from an object or a single element from a sequence.

attr

r->table('marvel')->get('IronMan')->attr('firstAppearance')->run;
r->expr([10, 20, 30, 40, 50])->attr(3)->run;

Get a single field from an object or a single element from a sequence.

DEPERCATED: This method has been renamed to "bracket", but "attr" will remain for a number of releases for backwards compatibility.

has_fields

r->table('players')->has_fields('games_won')->run;

Test if an object has one or more fields. An object has a field if it has that key and the key has a non-null value. For instance, the object {'a' => 1, 'b' => 2, 'c' => null} has the fields a and b.

insert_at

r->expr(['Iron Man', 'Spider-Man'])->insert_at(1, 'Hulk')->run;

Insert a value in to an array at a given index. Returns the modified array.

splice_at

r->expr(['Iron Man', 'Spider-Man'])->splice_at(1, ['Hulk', 'Thor'])->run;

Insert several values in to an array at a given index. Returns the modified array.

delete_at

r->expr(['a','b','c','d','e','f'])->delete_at(1)->run;

Remove one or more elements from an array at a given index. Returns the modified array.

change_at

r->expr(['Iron Man', 'Bruce', 'Spider-Man'])->change_at(1, 'Hulk')->run;

Change a value in an array at a given index. Returns the modified array.

keys

r->table('marvel')->get('ironman')->keys->run;

Return an array containing all of the object's keys.

values

r->table('marvel')->get('ironman')->values->run;

Return an array containing all of an object’s values. values guarantees the values will come out in the same order as keys.

match

r->table('users')->filter(sub {
  my $doc = shift;
  return $doc->attr('name')->match('^A')
})->run;

Matches against a regular expression. If there is a match, returns an object with the fields:

split

r->expr('foo  bar bax')->split->run;
r->expr('foo,bar,bax')->split(",")->run;
r->expr('foo,bar,bax')->split(",", 1)->run;

Splits a string into substrings. Splits on whitespace when called with no arguments. When called with a separator, splits on that separator. When called with a separator and a maximum number of splits, splits on that separator at most max_splits times. (Can be called with undef as the separator if you want to split on whitespace while still specifying max_splits.)

Mimics the behavior of Python's string.split in edge cases, except for splitting on the empty string, which instead produces an array of single-character strings.

upcase

r->expr('Sentence about LaTeX.')->upcase->run;

Uppercases a string.

downcase

r->expr('Sentence about LaTeX.')->downcase->run;

Lowercases a string.

add

r->expr(2)->add(2)->run;

Sum two numbers, concatenate two strings, or concatenate 2 arrays.

sub

r->expr(2)->sub(2)->run;

Subtract two numbers.

mul

r->expr(2)->mul(2)->run;

Multiply two numbers, or make a periodic array.

div

r->expr(2)->div(2)->run;

Divide two numbers.

mod

r->expr(2)->mod(2)->run;

Find the remainder when dividing two numbers.

and

r->expr(r->true)->and(r->false)->run;

Compute the logical and of two or more values.

or

r->expr(r->true)->or(r->false)->run;

Compute the logical or of two or more values.

eq

r->expr(2)->eq(2)->run;

Test if two values are equal.

ne

r->expr(2)->ne(2)->run;

Test if two values are not equal.

gt

r->expr(2)->gt(2)->run;

Test if the first value is greater than other.

ge

r->expr(2)->ge(2)->run;

Test if the first value is greater than or equal to other.

lt

r->expr(2)->lt(2)->run;

Test if the first value is less than other.

le

r->expr(2)->le(2)->run;

Test if the first value is less than or equal to other.

not

r->expr(r->true)->not->run;

Compute the logical inverse (not) of an expression.

in_timezone

r->now->in_timezone('-08:00')->hours->run;

Return a new time object with a different timezone. While the time stays the same, the results returned by methods such as "hours" will change since they take the timezone into account. The timezone argument has to be of the ISO 8601 format.

timezone

r->table('users')->filter(sub {
  my $user = shift;
  return $user->attr('subscriptionDate')->timezone->eql('-07:00');
})->run;

Return the timezone of the time object.

during

r->table('posts')->filter(
  r->row->attr('date')->during(
    r->time(2013, 12, 1, 'Z'),
    r->time(2013, 12, 10, 'Z')
  )
)->run;

Return if a time is between two other times (by default, inclusive for the start, exclusive for the end).

date

r->table('users')->filter(sub {
  my $user = shift;
  return user->attr('birthdate')->date->eql(r->now->date);
})->run;

Return a new time object only based on the day, month and year (ie. the same day at 00:00).

time_of_day

r->table('posts')->filter(
  r->row->attr('date')->time_of_day->le(12*60*60)
)->run;

Return the number of seconds elapsed since the beginning of the day stored in the time object.

year

r->table('users')->filter(sub {
  my $user = shift;
  return user->attr('birthdate')->year->eql(1986);
})->run;

Return the year of a time object.

month

r->table('users')->filter(
  r->row->attr('birthdate')->month->eql(11)
)->run;

Return the month of a time object as a number between 1 and 12. For your convenience, the terms r->january, r->february etc. are defined and map to the appropriate integer.

day

r->table('users')->filter(
  r->row->attr('birthdate')->day->eql(24)
)->run;

Return the day of a time object as a number between 1 and 31.

day_of_week

r->now->day_of_week->run;

Return the day of week of a time object as a number between 1 and 7 (following ISO 8601 standard). For your convenience, the terms r.monday, r.tuesday etc. are defined and map to the appropriate integer.

day_of_year

r->now->day_of_year->run;

Return the day of the year of a time object as a number between 1 and 366 (following ISO 8601 standard).

hours

r->table('posts')->filter(sub {
  my $post = shift;
  return $post->attr('date')->hours->lt(4);
})->run;

Return the hour in a time object as a number between 0 and 23.

minutes

r->table('posts')->filter(sub {
  my $post = shift;
  return $post->attr('date')->minutes->lt(10);
})->run;

Return the minute in a time object as a number between 0 and 59.

seconds

r->table('posts')->filter(sub {
  my $post = shift;
  return $post->attr('date')->seconds->lt(30);
})->run;

Return the seconds in a time object as a number between 0 and 59.999 (double precision).

to_iso8601

r->now->to_iso8601->run;

Convert a time object to its ISO 8601 format.

to_epoch_time

r->now->to_epoch_time->run;

Convert a time object to its epoch time.

do

r->table('players')->get('86be93eb-a112-48f5-a829-15b2cb49de1d')->do(sub {
  my $player = shift;
  return $player->attr('gross_score')->sub($player->attr('course_handicap'));
})->run

Evaluate an expression and pass its values as arguments to a function or to an expression.

for_each

r->table('marvel')->for_each(sub {
  my $hero = shift;
  r->table('villains')->get($hero->attr('villainDefeated'))->delete;
})->run;

Loop over a sequence, evaluating the given write query for each element.

default

r->table('posts')->map(sub {
  my $post = shift;
  return {
    title => $post->attr('title'),
    author => $post->attr('author')->default('Anonymous')
  };
})->run

Handle non-existence errors. Tries to evaluate and return its first argument. If an error related to the absence of a value is thrown in the process, or if its first argument returns null, returns its second argument. (Alternatively, the second argument may be a function which will be called with either the text of the non-existence error or null.)

coerce_to

r->table('posts')->map(sub {
  my $post = shift;
  return $post->merge({
    'comments' => r->table('comments')->get_all(
      $post->attr('id'), { index => 'post_id' })->coerce_to('array')
  });
)->run

Convert a value of one type into another.

type_of

r->expr('foo')->type_of->run;

Gets the type of a value.

info

r->table('marvel')->info->run;

Get information about a ReQL value.

fill

r->table('geo')->insert(
  {
    'id'        => 201,
    'rectangle' => r->line(
      [ -122.423246, 37.779388 ],
      [ -122.423246, 37.329898 ],
      [ -121.886420, 37.329898 ],
      [ -121.886420, 37.779388 ]
    )
  }
)->run;

r->table('geo')->get(201)
  ->update( { 'rectangle' => r->row->bracket('rectangle')->fill },
  { non_atomic => r->true } )->run;

Convert a Line object into a Polygon object. If the last point does not specify the same coordinates as the first point, polygon will close the polygon by connecting them.

includes

r->circle( r->point( -117.220406, 32.719464 ), 2000 )
  ->includes( r->point( -117.206201, 32.725186 ) )->run($conn);

Tests whether a geometry object is completely contained within another. When applied to a sequence of geometry objects, "includes" acts as a "filter", returning a sequence of objects from the sequence that include the argument.

intersects

r->circle( r->point( -117.220406, 32.719464 ), 2000 )
  ->intersects( r->point( -117.206201, 32.725186 ) )->run($conn);

Tests whether two geometry objects intersect with one another. When applied to a sequence of geometry objects, "intersects" acts as a "filter", returning a sequence of objects from the sequence that intersect with the argument.

polygon_sub

r->polygon(
  [ -122.4, 37.7 ],
  [ -122.4, 37.3 ],
  [ -121.8, 37.3 ],
  [ -121.8, 37.7 ]
  )->polygon_sub(
  r->polygon(
    [ -122.3, 37.4 ],
    [ -122.3, 37.6 ],
    [ -122.0, 37.6 ],
    [ -122.0, 37.4 ]
  )
  )->run($conn);

Use polygon2 to "punch out" a hole in polygon1. polygon2 must be completely contained within polygon1 and must have no holes itself (it must not be the output of "polygon_sub" itself).

to_geojson

r->table('geo')->get('sfo')->bracket('location')->to_geojson->run;

Convert a ReQL geometry object to a GeoJSON object.

round

r->expr(-12.567)->round->run($conn);

Rounds the given value to the nearest whole integer. For example, values of 1.0 up to but not including 1.5 will return 1.0, similar to "floor"; values of 1.5 up to 2.0 will return 2.0, similar to "ceil".

ceil

r->expr(-12.567)->ceil->run($conn);

Rounds the given value up, returning the smallest integer value greater than or equal to the given value (the value's ceiling).

floor

r->expr(-12.567)->floor->run($conn);

Rounds the given value down, returning the largest integer value less than or equal to the given value (the value's floor).

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)