/ 
MongoX-0.05
River stage zero No dependents
/ MongoX::Helper

NAME

MongoX::Helper - Helper to invoke MongoDB commands handy.

VERSION

version 0.05

SYNOPSIS

# default import common db_* helpers
use MongoX::Helper;

# or admin only command
use MongoX::Helper ':admin';

# explicit some command
use MongoX::Helper qw(db_count,db_find,admin_unlock,admin_shutdown_server);

# or all commands
use MongoX::Helper ':all';

DESCRIPTION

METHODS

admin_fsync_lock

my $ok = admin_fsync_lock;

call fsync_lock on current server.

admin_unlock

my $ok = admin_unlock;

call unlock on current server.

admin_server_status

my $result = admin_server_status;
print 'server uptime:',$result->{uptime};

Return current mongoDB server status.

admin_shutdown_server

admin_shutdown_server;

Shutdown current mongodb server.

admin_sharding_state

$result = admin_sharding_state;

Get sharding state.

admin_diag_logging

$result = admin_diag_logging;
print 'logging level:',$result->{was},"\n";

Get diag logging level.

db_stats

my $stats_info = db_stats;

Return current database stats information;

db_is_master

$ok = db_is_master;

Return if current server is master.

db_eval($code,$args?)

my $result = db_eval 'function(x) { return "hello, "+x; }', ["world"];

Evaluate a JavaScript expression on the Mongo server.

db_current_op

my $op = db_current_op;

Return current operation in the db.

db_filemd5($file_id)

$md5_hex = db_filemd5 $file_id;

return md5 hex value of the file.

db_re_index($collection_name?)

$ok = db_re_index;

rebuild the collection indexes (default collection is context_collection).

db_distinct

$result = db_distinct;

Performance a distinct query.

db_group

$result = db_group {
    reduce => 'function(doc,prev){ prev[doc.name]++; }',
    key => { key1 => 1,key2 => 1 },
    initial => { counter => 0.0 }
};

# or
$result = db_group {
    reduce => 'function(doc,prev){ prev[doc.name]++; }',
    keyf => 'function(doc) { return {"x" : doc.x};',
    initial => {counter => 0.0}
};

Returns an array of grouped items of current context collection. options:

reduce

The reduce function aggregates (reduces) the objects iterated. Typical operations of a reduce function include summing and counting. reduce takes two arguments: the current document being iterated over and the aggregation counter object. In the example above, these arguments are named obj and prev.

key

Fields to group by.

keyf?

An optional function returning a "key object" to be used as the grouping key. Use this instead of key to specify a key that is not an existing member of the object (or, to access embedded members). Set in lieu of key.

initial?

initial value of the aggregation counter object.

initial => { counter => 0.0 }

WARNING: As a known bug, in initial, if you assign a zero numberic value to some attribute, you must defined zero as float format, meant must be 0.0 but not 0, cause 0 will passed as boolean value, then you will got 'nan' value in retval.

finalize?

An optional function to be run on each item in the result set just before the item is returned. Can either modify the item (e.g., add an average field given a count and a total) or return a replacement object (returning a new object with just _id and average fields).

more about group, see: http://www.mongodb.org/display/DOCS/Aggregation#Aggregation-Group.

db_map_reduce

$result = db_map_reduce { map => 'javascript function',reduce => 'javascript function' };

map, reduce, and finalize functions are written in JavaScript.

valid options are:

map => mapfunction
reduce => reducefunction
query => query filter object
sort => sort the query. useful for optimization
limit => number of objects to return from collection
out => output-collection name
keeptemp => boolean
finalize => finalizefunction
scope => object where fields go into javascript global scope
verbose => boolean

more about map/reduce, see: http://www.mongodb.org/display/DOCS/MapReduce.

db_run_command

my $result = db_run_command {dbstats:1};

Run the command on current database. shortcut of "run_command" in MongoDB::Database.

db_list_commands

my $command_list = db_list_commands;
foreach my $cmd (keys %{$command_list}) {
    say 'Command name:',$cmd,"\n";
    say 'adminOnly:' => $cmd->{adminOnly};
    say 'help:' => $cmd->{help};
    say 'lockType:' => $cmd->{lockType};
    say 'slaveOk:' => $cmd->{slaveOk};
}

Get a hash reference of all db commands.

db_add_user($username,$password,$readonly?)

$ok = db_add_user('foo','12345');

Add user into current database.

db_remove_user($username)

$ok = db_remove_user $username;

Remove given user from current database.

db_find_and_modify($options)

my $next_val = db_find_and_modify {
    query => { _id => 'foo'},
    update => { '$inc' => { value => 1 } }
}

# simply remove the object to be returned
my $obj = db_find_and_modify({
    query => { _id => 10 },
    remove => 1
});

MongoDB 1.3+ supports a "find, modify, and return" command. This command can be used to atomically modify a document (at most one) and return it. Note:that the document returned will not include the modifications made on the update. The options can include 'sort' option which is useful when storing queue-like data.

option parameters

At least one of the update or remove parameters is required; the other arguments are optional.

query

A query selector document for matching the desired document. default is {}.

sort

if multiple docs match, choose the first one in the specified sort order as the object to manipulate. default is {}.

remove = boolean>

set to a true to remove the object before returning. default is false.

update

a modifier object. default is undef.

new = boolean>

set to true if you want to return the modified object rather than the original. Ignored for remove. default is false.

db_repair_database

my $result = db_repair_database;
print 'ok:'.$result->{ok};

Repair current database.

db_auth($username,$password,$is_digest)

$ok = db_auth 'pp', 'plain-text';

Attempts to authenticate for use of the current database with $username and $password. Shortcut of "authenticate" in MongoDB::Connection.

db_convert_to_capped($collection_name,$size)

db_convert_to_capped 'common_collection1',1024*1024*10;

Convert a normal collection to capped collection.

db_create_collection($name,$options?)

$result = db_create_collection 'foo',{ capped => 1 };

Explicit create a special (capped) collection.

db_insert(\%obj)

db_insert {name => 'ns',workhard => 'mongox' };

Implicit call context_collection-insert>.

db_find($query?,$options?)

$cursor = db_find {name => 'foo'};

Implicit call context_collection-find>.

db_find_all($query?,$options?)

@result = db_find_all {age => 30},{limit => 20};

Short of db_find()-all>.

db_count($query?)

$total = db_count { name => 'foo' };

Implicit call context_collection-count>.

db_increment($query,$increment_values,$options)

db_increment {name => 2},{ counter => 1, money => 10 },{upsert => 1};

Shortcut of '$inc' command.

db_update_set(\%criteria,\%set_object,\%options)

db_update_set {name => 'foo'},{new_location => 'Beijing'},{ upsert => 0 };

Shortcut for '$set' command.

db_update(\%criteria,\%new_object,\%options?)

db_update {_id => 5},{name => 'foo'};

Shortcut of "update" in MongoDB::Collection.

db_remove(\%criteria?,\%options?)

db_remove;

Shortcut of "remove" in MongoDB::Collection.

db_find_one(\%query?,\%options?)

$result = db_find_one {_id => 5};

Shortcut of "find_one" in MongoDB::Collection.

db_ensure_index(\%keys,\%options?)

$result = db_ensure_index { foo => 1, name => 1};

Shortcut of "ensure_index" in MongoDB::Collection.

db_drop_index($index_name)

db_drop_index { 'name_1' };

Shortcut of "drop_index" in MongoDB::Collection.

db_drop_indexes

db_drop_indexes;

Shortcut of "drop_indexes" in MongoDB::Collection.

db_get_indexes

db_get_indexes;

Shortcut of "get_indexes" in MongoDB::Collection.

db_find_by_id

my $row = db_find_by_id $oid_or_id_string

Quick find_one by _id.

db_remove_by_id

db_remove_by_id $oid_or_id_string

Quick remove by _id.

SEE ALSO

MongoDB Commands docs: http://www.mongodb.org/display/DOCS/Commands

AUTHOR

Pan Fan(nightsailer) <nightsailer at gmail dot com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2010 by Pan Fan(nightsailer).

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