MongoDB  2.0.3
Classes | Public Types | Public Member Functions | Static Public Member Functions | Public Attributes | Static Public Attributes | Protected Member Functions
mongo::DBClientWithCommands Class Reference

DB "commands" Basically just invocations of connection. More...

#include <dbclient.h>

Inheritance diagram for mongo::DBClientWithCommands:
mongo::DBClientInterface mongo::DBClientBase mongo::DBClientConnection mongo::DBClientReplicaSet mongo::SyncClusterConnection

List of all members.

Classes

struct  MROutput
 This implicitly converts from char*, string, and BSONObj to be an argument to mapreduce You shouldn't need to explicitly construct this. More...

Public Types

enum  ProfilingLevel { ProfileOff = 0, ProfileSlow = 1, ProfileAll = 2 }
 The Mongo database provides built-in performance profiling capabilities. More...

Public Member Functions

bool simpleCommand (const string &dbname, BSONObj *info, const string &command)
 helper function.
virtual bool runCommand (const string &dbname, const BSONObj &cmd, BSONObj &info, int options=0)
 Run a database command.
virtual bool auth (const string &dbname, const string &username, const string &pwd, string &errmsg, bool digestPassword=true)
 Authorize access to a particular database.
virtual unsigned long long count (const string &ns, const BSONObj &query=BSONObj(), int options=0, int limit=0, int skip=0)
 count number of objects in collection ns that match the query criteria specified throws UserAssertion if database returns an error
string createPasswordDigest (const string &username, const string &clearTextPassword)
virtual bool isMaster (bool &isMaster, BSONObj *info=0)
 returns true in isMaster parm if this db is the current master of a replica pair.
bool createCollection (const string &ns, long long size=0, bool capped=false, int max=0, BSONObj *info=0)
 Create a new collection in the database.
string getLastError ()
 Get error result from the last write operation (insert/update/delete) on this connection.
virtual BSONObj getLastErrorDetailed ()
 Get error result from the last write operation (insert/update/delete) on this connection.
BSONObj getPrevError ()
 Return the last error which has occurred, even if not the very last operation.
bool resetError ()
 Reset the previous error state for this connection (accessed via getLastError and getPrevError).
virtual bool dropCollection (const string &ns)
 Delete the specified collection.
bool repairDatabase (const string &dbname, BSONObj *info=0)
 Perform a repair and compaction of the specified database.
bool copyDatabase (const string &fromdb, const string &todb, const string &fromhost="", BSONObj *info=0)
 Copy database from one server or name to another server or name.
bool setDbProfilingLevel (const string &dbname, ProfilingLevel level, BSONObj *info=0)
bool getDbProfilingLevel (const string &dbname, ProfilingLevel &level, BSONObj *info=0)
BSONObj mapreduce (const string &ns, const string &jsmapf, const string &jsreducef, BSONObj query=BSONObj(), MROutput output=MRInline)
 Run a map/reduce job on the server.
bool eval (const string &dbname, const string &jscode, BSONObj &info, BSONElement &retValue, BSONObj *args=0)
 Run javascript code on the database server.
bool validate (const string &ns, bool scandata=true)
 validate a collection, checking for errors and reporting back statistics.
bool eval (const string &dbname, const string &jscode)
template<class T >
bool eval (const string &dbname, const string &jscode, T parm1)
template<class T , class NumType >
bool eval (const string &dbname, const string &jscode, T parm1, NumType &ret)
 eval invocation with one parm to server and one numeric field (either int or double) returned
list< string > getDatabaseNames ()
 get a list of all the current databases uses the { listDatabases : 1 } command.
list< string > getCollectionNames (const string &db)
 get a list of all the current collections in db
bool exists (const string &ns)
virtual bool ensureIndex (const string &ns, BSONObj keys, bool unique=false, const string &name="", bool cache=true, bool background=false, int v=-1)
 Create an index if it does not already exist.
virtual void resetIndexCache ()
 clears the index cache, so the subsequent call to ensureIndex for any index will go to the server
virtual auto_ptr< DBClientCursorgetIndexes (const string &ns)
virtual void dropIndex (const string &ns, BSONObj keys)
virtual void dropIndex (const string &ns, const string &indexName)
virtual void dropIndexes (const string &ns)
 drops all indexes for the collection
virtual void reIndex (const string &ns)
string genIndexName (const BSONObj &keys)
virtual bool dropDatabase (const string &dbname, BSONObj *info=0)
 Erase / drop an entire database.
virtual string toString ()=0
string nsGetDB (const string &ns)
string nsGetCollection (const string &ns)

Static Public Member Functions

static string getLastErrorString (const BSONObj &res)
 Can be called with the returned value from getLastErrorDetailed to extract an error string.

Public Attributes

int _logLevel
 controls how chatty the client is about network errors & such.

Static Public Attributes

static MROutput MRInline

Protected Member Functions

bool isOk (const BSONObj &)
 if the result of a command is ok
bool isNotMasterErrorString (const BSONElement &e)
 if the element contains a not master error
BSONObj _countCmd (const string &ns, const BSONObj &query, int options, int limit, int skip)
enum QueryOptions availableOptions ()

Detailed Description

DB "commands" Basically just invocations of connection.

$cmd.findOne({...});


Member Enumeration Documentation

The Mongo database provides built-in performance profiling capabilities.

Uset setDbProfilingLevel() to enable. Profiling information is then written to the system.profiling collection, which one can then query.


Member Function Documentation

bool mongo::DBClientWithCommands::auth ( const string &  dbname,
const string &  username,
const string &  pwd,
string &  errmsg,
bool  digestPassword = true 
) [virtual]

Authorize access to a particular database.

Authentication is separate for each database on the server -- you may authenticate for any number of databases on a single connection. The "admin" database is special and once authenticated provides access to all databases on the server.

Parameters:
digestPasswordif password is plain text, set this to true. otherwise assumed to be pre-digested
Returns:
true if successful

Reimplemented in mongo::DBClientConnection, mongo::DBClientReplicaSet, and mongo::SyncClusterConnection.

bool mongo::DBClientWithCommands::copyDatabase ( const string &  fromdb,
const string &  todb,
const string &  fromhost = "",
BSONObj info = 0 
)

Copy database from one server or name to another server or name.

Generally, you should dropDatabase() first as otherwise the copied information will MERGE into whatever data is already present in this database.

For security reasons this function only works when you are authorized to access the "admin" db. However, if you have access to said db, you can copy any database from one place to another. TODO: this needs enhancement to be more flexible in terms of security.

This method provides a way to "rename" a database by copying it to a new db name and location. The copy is "repaired" and compacted.

fromdb database name from which to copy. todb database name to copy to. fromhost hostname of the database (and optionally, ":port") from which to copy the data. copies from self if "".

returns true if successful

bool mongo::DBClientWithCommands::createCollection ( const string &  ns,
long long  size = 0,
bool  capped = false,
int  max = 0,
BSONObj info = 0 
)

Create a new collection in the database.

Normally, collection creation is automatic. You would use this function if you wish to specify special options on creation.

If the collection already exists, no action occurs.

Parameters:
nsfully qualified collection name
sizedesired initial extent size for the collection. Must be <= 1000000000 for normal collections. For fixed size (capped) collections, this size is the total/max size of the collection.
cappedif true, this is a fixed size collection (where old data rolls out).
maxmaximum number of objects if capped (optional).

returns true if successful.

virtual bool mongo::DBClientWithCommands::dropCollection ( const string &  ns) [inline, virtual]

Delete the specified collection.

bool mongo::DBClientWithCommands::ensureIndex ( const string &  ns,
BSONObj  keys,
bool  unique = false,
const string &  name = "",
bool  cache = true,
bool  background = false,
int  v = -1 
) [virtual]

Create an index if it does not already exist.

ensureIndex calls are remembered so it is safe/fast to call this function many times in your code.

Parameters:
nscollection to be indexed
keysthe "key pattern" for the index. e.g., { name : 1 }
uniqueif true, indicates that key uniqueness should be enforced for this index
nameif not specified, it will be created from the keys automatically (which is recommended)
cacheif set to false, the index cache for the connection won't remember this call
backgroundbuild index in the background (see mongodb docs/wiki for details)
vindex version. leave at default value. (unit tests set this parameter.)
Returns:
whether or not sent message to db. should be true on first call, false on subsequent unless resetIndexCache was called
bool mongo::DBClientWithCommands::eval ( const string &  dbname,
const string &  jscode,
BSONObj info,
BSONElement retValue,
BSONObj args = 0 
)

Run javascript code on the database server.

dbname database SavedContext in which the code runs. The javascript variable 'db' will be assigned to this database when the function is invoked. jscode source code for a javascript function. info the command object which contains any information on the invocation result including the return value and other information. If an error occurs running the jscode, error information will be in info. (try "out() << info.toString()") retValue return value from the jscode function. args args to pass to the jscode function. when invoked, the 'args' variable will be defined for use by the jscode.

returns true if runs ok.

See testDbEval() in dbclient.cpp for an example of usage.

get a list of all the current databases uses the { listDatabases : 1 } command.

throws on error

Get error result from the last write operation (insert/update/delete) on this connection.

Returns:
error message text, or empty string if no error.

Get error result from the last write operation (insert/update/delete) on this connection.

Returns:
full error object.

Reimplemented in mongo::SyncClusterConnection.

string mongo::DBClientWithCommands::getLastErrorString ( const BSONObj res) [static]

Can be called with the returned value from getLastErrorDetailed to extract an error string.

If all you need is the string, just call getLastError() instead.

Return the last error which has occurred, even if not the very last operation.

Returns:
{ err : <error message>="">, nPrev : <how_many_ops_back_occurred>, ok : 1 }

result.err will be null if no error has occurred.

bool mongo::DBClientWithCommands::isMaster ( bool &  isMaster,
BSONObj info = 0 
) [virtual]

returns true in isMaster parm if this db is the current master of a replica pair.

pass in info for more details e.g.: { "ismaster" : 1.0 , "msg" : "not paired" , "ok" : 1.0 }

returns true if command invoked successfully.

BSONObj mongo::DBClientWithCommands::mapreduce ( const string &  ns,
const string &  jsmapf,
const string &  jsreducef,
BSONObj  query = BSONObj(),
MROutput  output = MRInline 
)

Run a map/reduce job on the server.

See http://www.mongodb.org/display/DOCS/MapReduce

ns namespace (db+collection name) of input data jsmapf javascript map function code jsreducef javascript reduce function code. query optional query filter for the input output either a string collection name or an object representing output type if not specified uses inline output type

returns a result object which contains: { result : <collection_name>, numObjects : <number_of_objects_scanned>, timeMillis : <job_time>, ok : <1_if_ok>, [, err : <errmsg_if_error>] }

For example one might call: result.getField("ok").trueValue() on the result to check if ok.

string mongo::DBClientWithCommands::nsGetCollection ( const string &  ns) [inline]
Returns:
the collection name portion of an ns string
string mongo::DBClientWithCommands::nsGetDB ( const string &  ns) [inline]
Returns:
the database name portion of an ns string
bool mongo::DBClientWithCommands::repairDatabase ( const string &  dbname,
BSONObj info = 0 
) [inline]

Perform a repair and compaction of the specified database.

May take a long time to run. Disk space must be available equal to the size of the database while repairing.

Reset the previous error state for this connection (accessed via getLastError and getPrevError).

Useful when performing several operations at once and then checking for an error after attempting all operations.

bool mongo::DBClientWithCommands::runCommand ( const string &  dbname,
const BSONObj cmd,
BSONObj info,
int  options = 0 
) [inline, virtual]

Run a database command.

Database commands are represented as BSON objects. Common database commands have prebuilt helper functions -- see below. If a helper is not available you can directly call runCommand.

Parameters:
dbnamedatabase name. Use "admin" for global administrative commands.
cmdthe command object to execute. For example, { ismaster : 1 }
infothe result object the database returns. Typically has { ok : ..., errmsg : ... } fields set.
optionssee enum QueryOptions - normally not needed to run a command
Returns:
true if the command returned "ok".

Reimplemented in mongo::DBClientConnection.

bool mongo::DBClientWithCommands::simpleCommand ( const string &  dbname,
BSONObj info,
const string &  command 
)

helper function.

run a simple command where the command expression is simply { command : 1 }

Parameters:
info-- where to put result object. may be null if caller doesn't need that info
command-- command name
Returns:
true if the command returned "ok".
bool mongo::DBClientWithCommands::validate ( const string &  ns,
bool  scandata = true 
) [inline]

validate a collection, checking for errors and reporting back statistics.

this operation is slow and blocking.


Member Data Documentation

controls how chatty the client is about network errors & such.

See log.h


The documentation for this class was generated from the following files: