File Coverage

blib/lib/Rethinkdb/Query/Table.pm

Criterion	Covered	Total	%
statement	15	126	11.9
branch	0	20	0.0
condition	0	2	0.0
subroutine	5	27	18.5
pod	22	22	100.0
total	42	197	21.3

package Rethinkdb::Query::Table;
use Rethinkdb::Base 'Rethinkdb::Query';

use Carp qw'croak carp';
use Scalar::Util 'weaken';

use Rethinkdb::Protocol;
use Rethinkdb::Util;

has [qw{ _rdb name }];

# primary_key = None
# datacenter = None
# durability = hard|soft
# cache_size = '1024MB'
sub create {
  my $self = shift;
  my $optargs = ref $_[0] ? $_[0] : {@_};

  my $q = Rethinkdb::Query->new(
    _rdb    => $self->_rdb,
    _type   => $self->_termType->table_create,
    args    => $self->name,
    optargs => $optargs,
  );

  weaken $q->{_rdb};
  return $q;
}

sub drop {
  my $self = shift;

  my $q = Rethinkdb::Query->new(
    _rdb  => $self->_rdb,
    _type => $self->_termType->table_drop,
    args  => $self->name,
  );

  weaken $q->{_rdb};
  return $q;
}

sub index_create {
  my $self    = shift;
  my $args    = shift;
  my $optargs = ref $_[0] ? $_[0] : {@_};

  if ( ref $optargs ne 'HASH' ) {
    $args = [ $args, Rethinkdb::Util->_wrap_func($optargs) ];
    $optargs = undef;
  }
  elsif ( $optargs->{'$reql_type$'} ) {
    $args = [ $args, $optargs ];
    $optargs = undef;
  }

  my $q = Rethinkdb::Query->new(
    _parent => $self,
    _type   => $self->_termType->index_create,
    args    => $args,
    optargs => $optargs,
  );

  return $q;
}

sub index_drop {
  my $self  = shift;
  my $index = shift;

  my $q = Rethinkdb::Query->new(
    _parent => $self,
    _type   => $self->_termType->index_drop,
    args    => $index
  );

  return $q;
}

sub index_list {
  my $self = shift;

  my $q = Rethinkdb::Query->new(
    _parent => $self,
    _type   => $self->_termType->index_list,
  );

  return $q;
}

sub index_rename {
  my $self = shift;
  my $args = [@_];

  my $q = Rethinkdb::Query->new(
    _parent => $self,
    _type   => $self->_termType->index_rename,
    args    => $args
  );

  return $q;
}

sub index_status {
  my $self    = shift;
  my $indices = [@_];

  my $q = Rethinkdb::Query->new(
    _parent => $self,
    _type   => $self->_termType->index_status,
    args    => $indices,
  );

  return $q;
}

sub index_wait {
  my $self    = shift;
  my $indices = [@_];

  my $q = Rethinkdb::Query->new(
    _parent => $self,
    _type   => $self->_termType->index_wait,
    args    => $indices,
  );

  return $q;
}

sub changes {
  my $self   = shift;
  my $params = shift;

  my $q = Rethinkdb::Query->new(
    _parent => $self,
    _type   => $self->_termType->changes,
    optargs => $params,
  );

  return $q;
}

sub insert {
  my $self   = shift;
  my $args   = shift;
  my $params = shift;

  my $q = Rethinkdb::Query->new(
    _parent => $self,
    _type   => $self->_termType->insert,
    args    => Rethinkdb::Util->_expr_json($args),
    optargs => $params,
  );

  return $q;
}

sub sync {
  my $self = shift;

  my $q = Rethinkdb::Query->new(
    _parent => $self,
    _type   => $self->_termType->sync,
  );

  return $q;
}

# get a document by primary key
# TODO: key can be other things besides string
sub get {
  my $self = shift;
  my ($key) = @_;

  my $q = Rethinkdb::Query->new(
    _parent => $self,
    _type   => $self->_termType->get,
    args    => $key,
  );

  return $q;
}

# Get all documents where the given value matches the value of the requested index
sub get_all {
  my $self = shift;

  # extract values
  my $values = \@_;
  my $params = {};

  if ( ref $values->[0] eq 'ARRAY' ) {
    ( $values, $params ) = @{$values};
  }

  if ( ref $values->[ $#{$values} ] eq 'HASH' ) {
    $params = pop @{$values};
  }

  if ( !$params->{index} ) {
    $params->{index} = 'id';
  }

  my $q = Rethinkdb::Query->new(
    _parent => $self,
    _type   => $self->_termType->get_all,
    args    => $values,
    optargs => $params,
  );

  return $q;
}

sub between {
  my $self = shift;
  my ( $lower, $upper, $index, $left_bound, $right_bound ) = @_;

  my $optargs = {};
  if ( ref $index ) {
    $optargs = $index;
  }
  else {
    $optargs->{index} = $index || 'id';

    if ($left_bound) {
      $optargs->{left_bound} = $left_bound;
    }

    if ($right_bound) {
      $optargs->{right_bound} = $right_bound;
    }
  }

  my $q = Rethinkdb::Query->new(
    _parent => $self,
    _type   => $self->_termType->between,
    args    => [ $lower, $upper ],
    optargs => $optargs,
  );

  return $q;
}

sub get_intersecting {
  my $self    = shift;
  my $args    = shift;
  my $optargs = shift;

  my $q = Rethinkdb::Query->new(
    _parent => $self,
    _type   => $self->_termType->get_intersecting,
    args    => $args,
    optargs => $optargs,
  );

  return $q;
}

sub get_nearest {
  my $self    = shift;
  my $args    = shift;
  my $optargs = shift;

  my $q = Rethinkdb::Query->new(
    _parent => $self,
    _type   => $self->_termType->get_nearest,
    args    => $args,
    optargs => $optargs,
  );

  return $q;
}

sub grant {
  my $self  = shift;
  my $user  = shift;
  my $perms = shift;

  my $q = Rethinkdb::Query->new(
    _rdb  => $self->_rdb,
    _type => $self->_termType->grant,
    args  => [ $user, $perms ]
  );

  return $q;
}

sub config {
  my $self = shift;

  my $q = Rethinkdb::Query->new(
    _parent => $self,
    _type   => $self->_termType->config,
  );

  return $q;
}

sub rebalance {
  my $self = shift;

  my $q = Rethinkdb::Query->new(
    _parent => $self,
    _type   => $self->_termType->rebalance,
  );

  return $q;
}

sub reconfigure {
  my $self = shift;
  my $args = shift;

  my $q = Rethinkdb::Query->new(
    _parent => $self,
    _type   => $self->_termType->reconfigure,
    optargs => $args
  );

  return $q;
}

sub status {
  my $self = shift;

  my $q = Rethinkdb::Query->new(
    _parent => $self,
    _type   => $self->_termType->status,
  );

  return $q;
}

sub wait {
  my $self = shift;

  my $q = Rethinkdb::Query->new(
    _parent => $self,
    _type   => $self->_termType->wait,
  );

  return $q;
}

1;

=encoding utf8

=head1 NAME

Rethinkdb::Query::Table - RethinkDB Query Table

=head1 SYNOPSIS

=head1 DESCRIPTION

L is a type of query that represents a table in a
database. This classes contains methods to interact with said table.

=head1 ATTRIBUTES

L implements the following attributes.

=head2 name

  my $table = r->db('comics')->table('superheros');
  say $table->name;

The name of the table.

=head1 METHODS

L implements the following methods.

=head2 create

  r->db('test')->table('dc_universe')->create->run;

Create this table. A RethinkDB table is a collection of JSON documents.

If successful, the operation returns an object: C<< {created => 1} >>. If a
table with the same name already exists, the operation returns a
C.

B that you can only use alphanumeric characters and underscores for the
table name.

=head2 drop

  r->db('test')->table('dc_universe')->drop->run(conn)

Drop this table. The table and all its data will be deleted.

If successful, the operation returns an object: C<< {dropped => 1} >>. If the
specified table doesn't exist a C is returned.

=head2 index_create

  r->table('comments')->index_create('post_id')->run;

Create a new secondary index on a table.

=head2 index_drop

  r->table('dc')->index_drop('code_name')->run;

Delete a previously created secondary index of this table.

=head2 index_list

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

List all the secondary indexes of this table.

=head2 index_rename

  r->table('marvel')->index_rename('heroId', 'awesomeId')->run;

Rename an existing secondary index on a table. If the optional argument
C is specified as C, a previously existing index with the new
name will be deleted and the index will be renamed. If C is C
(the default) an error will be raised if the new index name already exists.

=head2 index_status

  r->table('test')->index_status->run;
  r->table('test')->index_status('timestamp')->run;

Get the status of the specified indexes on this table, or the status of all
indexes on this table if no indexes are specified.

=head2 index_wait

  r->table('test')->index_wait->run;
  r->table('test')->index_wait('timestamp')->run;

Wait for the specified indexes on this table to be ready, or for all indexes on
this table to be ready if no indexes are specified.

=head2 changes

  my $stream = r->table('games')->changes->run(sub {
    my ($response) = @_;
    say Dumper $response;
  });

Return an infinite stream of objects representing changes to a table. Whenever
an C, C, C or C is performed on the table, an
object of the form C<< {'old_val' => ..., 'new_val' => ...} >> will be appended
to the stream. For an C, C will be C, and for a
C, C will be C.

=head2 insert

  r->table('posts')->insert({
    id => 1,
    title => 'Lorem ipsum',
    content => 'Dolor sit amet'
  })->run;

Insert documents into a table. Accepts a single document or an array of
documents.

=head2 sync

L ensures that writes on a given table are written to permanent storage.
Queries that specify soft durability C<< {durability => 'soft'} >> do not give
such guarantees, so sync can be used to ensure the state of these queries. A
call to sync does not return until all previous writes to the table are
persisted.

=head2 get

  r->table('posts')->get('a9849eef-7176-4411-935b-79a6e3c56a74')->run;

Get a document by primary key.

If no document exists with that primary key, L will return C.

=head2 get_all

  r->table('marvel')->get_all('man_of_steel', { index => 'code_name' })->run;

Get all documents where the given value matches the value of the requested
index.

=head2 between

  r->table('marvel')->between(10, 20)->run;

Get all documents between two keys. Accepts three optional arguments: C,
C, and C. If C is set to the name of a
secondary index, L will return all documents where that index's value
is in the specified range (it uses the primary key by default). C
or C may be set to open or closed to indicate whether or not to
include that endpoint of the range (by default, C is closed and
C is open).

=head2 get_intersecting

  r->table('geo')
    ->get_intersecting(
    r->circle( [ -122.423246, 37.770378359 ], 10, { unit => 'mi' } ),
    { index => 'location' } )->run;

Get all documents where the given geometry object intersects the geometry
object of the requested geospatial index.

=head2 get_nearest

  r->table('geo')->get_nearest(
    r->point( -122.422876, 37.777128 ),
    { index => 'location', max_dist => 5000 }
  )->run;

Get all documents where the specified geospatial index is within a certain
distance of the specified point (default 100 kilometers).

=head2 grant

r->table('marvel')->grant( 'username', { read => r->true, write => r->false } )
  ->run;

Grant or deny access permissions for a user account on a table.

=head2 config

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

Query (read and/or update) the configurations for individual tables.

=head2 rebalance

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

Rebalances the shards of a table.

=head2 reconfigure

  r->table('marvel')->reconfigure({ shards => 2, replicas => 1 })->run;
  r->table('marvel')->reconfigure(
    {
      shards              => 2,
      replicas            => { wooster => 1, wayne => 1 },
      primary_replica_tag => 'wooster'
    }
  )->run;

Reconfigure a table's sharding and replication.

=head2 status

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

Return the status of a table. The return value is an object providing
information about the table's shards, replicas and replica readiness states

=head2 wait

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

Wait for a table to be ready. A table may be temporarily unavailable
after creation, rebalancing or reconfiguring. The L command
blocks until the given table is fully up to date.

=cut