-- | Query and update documents{-# LANGUAGE OverloadedStrings, RecordWildCards, NamedFieldPuns, TupleSections, FlexibleContexts, FlexibleInstances, UndecidableInstances, MultiParamTypeClasses, GeneralizedNewtypeDeriving, StandaloneDeriving, TypeSynonymInstances, RankNTypes #-}moduleDatabase.MongoDB.Query(-- * Accessaccess,Access,Action,runAction,Failure(..),-- * DatabaseDatabase(..),allDatabases,DbAccess,use,thisDatabase,-- ** AuthenticationP.Username,P.Password,auth,-- * CollectionCollection,allCollections,-- ** SelectionSelection(..),Selector,whereJS,Select(select),-- * Write-- ** WriteModeWriteMode(..),safe,GetLastError,writeMode,-- ** Insertinsert,insert_,insertMany,insertMany_,-- ** Updatesave,replace,repsert,Modifier,modify,-- ** Deletedelete,deleteOne,-- * ReadreadMode,-- ** QueryQuery(..),QueryOption(..),Projector,Limit,Order,BatchSize,explain,find,findOne,count,distinct,-- *** CursorCursor,next,nextN,rest,closeCursor,isCursorClosed,-- ** GroupGroup(..),GroupKey(..),group,-- ** MapReduceMapReduce(..),MapFun,ReduceFun,FinalizeFun,mapReduce,runMR,runMR',-- * CommandCommand,runCommand,runCommand1,eval,)whereimportPreludeasXhiding(lookup)importControl.Applicative((<$>),Applicative(..))importControl.Arrow(first)importControl.Monad.ContextimportControl.Monad.ReaderimportControl.Monad.ErrorimportControl.Monad.ThrowimportControl.Monad.MVarimportqualifiedDatabase.MongoDB.Internal.ProtocolasPimportDatabase.MongoDB.Internal.Protocolhiding(Query,QueryOption(..),send,call)importDatabase.MongoDB.Connection(MasterOrSlaveOk(..),Service(..))importData.BsonimportData.WordimportData.IntimportData.Maybe(listToMaybe,catMaybes)importData.UStringasU(dropWhile,any,tail)importControl.Monad.Util(MonadIO',loop)importDatabase.MongoDB.Internal.Util((<.>),true1)mapErrorIO::(Throwem,MonadIOm)=>(e'->e)->ErrorTe'IOa->mamapErrorIOf=throwLeft'f.liftIO.runErrorT-- * Mongo Monadaccess::(Services,MonadIOm)=>WriteMode->MasterOrSlaveOk->ConnPools->Actionma->m(EitherFailurea)-- ^ Run action under given write and read mode against the server or replicaSet behind given connection pool. Return Left Failure if there is a connection failure or read/write error.accesswmospoolact=doePipe<-liftIO.runErrorT$getPipemospooleither(return.Left.ConnectionFailure)(runActionactwmos)ePipe-- | A monad with access to a 'Pipe', 'MasterOrSlaveOk', and 'WriteMode', and throws 'Failure' on read, write, or pipe failureclass(ContextPipem,ContextMasterOrSlaveOkm,ContextWriteModem,ThrowFailurem,MonadIO'm)=>Accessminstance(ContextPipem,ContextMasterOrSlaveOkm,ContextWriteModem,ThrowFailurem,MonadIO'm)=>AccessmwrapIO::(Accessm)=>(WriteMode->MasterOrSlaveOk->Pipe->IO(EitherFailurea))->ma-- ^ Lift IO with Access context and failure into Access monadwrapIOact=dowriteMod<-contextmos<-contextpipe<-contexte<-liftIO(actwriteModmospipe)eitherthrowreturnemodifyMVar'::(Accessm)=>MVara->(a->ActionIO(a,b))->mbmodifyMVar'varact=wrapIO$\wmp->modifyMVarvar$\a->doe<-runAction(acta)wmpreturn$either((a,).Left)(Right<$>)eaddMVarFinalizer'::(Accessm)=>MVara->ActionIO()->m()addMVarFinalizer'varact=wrapIO$\wmp->doaddMVarFinalizervar$runActionactwmp>>return()-- ignore any failurereturn(Right())newtypeActionma=Action(ErrorTFailure(ReaderTWriteMode(ReaderTMasterOrSlaveOk(ReaderTPipem)))a)deriving(ContextPipe,ContextMasterOrSlaveOk,ContextWriteMode,ThrowFailure,MonadIO,Monad,Applicative,Functor)-- ^ Monad with access to a 'Pipe', 'MasterOrSlaveOk', and 'WriteMode', and throws a 'Failure' on read, write or pipe failureinstanceMonadTransActionwherelift=Action.lift.lift.lift.liftrunAction::Actionma->WriteMode->MasterOrSlaveOk->Pipe->m(EitherFailurea)-- ^ Run action with given write mode and read mode (master or slave-ok) against given pipe (TCP connection). Return Left Failure if read/write error or connection failure.-- 'access' calls runAction. Use this directly if you want to use the same connection and not take from the pool again. However, the connection may still be used by other threads at the same time. For instance, the pool will still hand this connection out.runAction(Actionaction)wmos=runReaderT(runReaderT(runReaderT(runErrorTaction)w)mos)-- | A connection failure, or a read or write exception like cursor expired or inserting a duplicate key.-- Note, unexpected data from the server is not a Failure, rather it is a programming error (you should call 'error' in this case) because the client and server are incompatible and requires a programming change.dataFailure=ConnectionFailureIOError-- ^ TCP connection ('Pipe') failed. Make work if you try again on the same Mongo 'Connection' which will create a new Pipe.|CursorNotFoundFailureCursorId-- ^ Cursor expired because it wasn't accessed for over 10 minutes, or this cursor came from a different server that the one you are currently connected to (perhaps a fail over happen between servers in a replica set)|QueryFailureString-- ^ Query failed for some reason as described in the string|WriteFailureErrorCodeString-- ^ Error observed by getLastError after a write, error description is in stringderiving(Show,Eq)instanceErrorFailurewherestrMsg=error-- ^ 'fail' is treated the same as 'error'. In other words, don't use it.-- * DatabasenewtypeDatabase=Database{databaseName::UString}deriving(Eq,Ord)-- ^ Database nameinstanceShowDatabasewhereshow(Databasex)=unpackx-- | 'Access' monad with a particular 'Database' in contextclass(ContextDatabasem,Accessm)=>DbAccessminstance(ContextDatabasem,Accessm)=>DbAccessmallDatabases::(Accessm)=>m[Database]-- ^ List all databases residing on serverallDatabases=map(Database.at"name").at"databases"<$>use(Database"admin")(runCommand1"listDatabases")use::Database->ReaderTDatabasema->ma-- ^ Run action against given databaseuse=fliprunReaderTthisDatabase::(DbAccessm)=>mDatabase-- ^ Current database in usethisDatabase=context-- * Authenticationauth::(DbAccessm)=>Username->Password->mBool-- ^ Authenticate with the database (if server is running in secure mode). Return whether authentication was successful or not. Reauthentication is required for every new pipe.authusrpss=don<-at"nonce"<$>runCommand["getnonce"=:(1::Int)]true1"ok"<$>runCommand["authenticate"=:(1::Int),"user"=:usr,"nonce"=:n,"key"=:pwKeynusrpss]-- * CollectiontypeCollection=UString-- ^ Collection name (not prefixed with database)allCollections::(DbAccessm)=>m[Collection]-- ^ List all collections in this databaseallCollections=dodb<-thisDatabasedocs<-rest=<<find(query[]"system.namespaces"){sort=["name"=:(1::Int)]}return.filter(not.isSpecialdb).mapdropDbPrefix$map(at"name")docswheredropDbPrefix=U.tail.U.dropWhile(/='.')isSpecial(Databasedb)col=U.any(=='$')col&&db<.>col/="local.oplog.$main"-- * SelectiondataSelection=Select{selector::Selector,coll::Collection}deriving(Show,Eq)-- ^ Selects documents in collection that match selectortypeSelector=Document-- ^ Filter for a query, analogous to the where clause in SQL. @[]@ matches all documents in collection. @[x =: a, y =: b]@ is analogous to @where x = a and y = b@ in SQL. See <http://www.mongodb.org/display/DOCS/Querying> for full selector syntax.whereJS::Selector->Javascript->Selector-- ^ Add Javascript predicate to selector, in which case a document must match both selector and predicatewhereJSseljs=("$where"=:js):selclassSelectaQueryOrSelectionwhereselect::Selector->Collection->aQueryOrSelection-- ^ 'Query' or 'Selection' that selects documents in collection that match selector. The choice of type depends on use, for example, in @find (select sel col)@ it is a Query, and in @delete (select sel col)@ it is a Selection.instanceSelectSelectionwhereselect=SelectinstanceSelectQuerywhereselect=query-- * Write-- ** WriteMode-- | Default write-mode is 'Unsafe'dataWriteMode=Unsafe-- ^ Submit writes without receiving acknowledgments. Fast. Assumes writes succeed even though they may not.|SafeGetLastError-- ^ Receive an acknowledgment after every write, and raise exception if one says the write failed. This is acomplished by sending the getLastError command, with given 'GetLastError' parameters, after every write.deriving(Show,Eq)typeGetLastError=Document-- ^ Parameters for getLastError command. For example ["w" =: 2] tells the server to wait for the write to reach at least two servers in replica set before acknowledging. See "http://www.mongodb.org/display/DOCS/Last+Error+Commands" for more options.safe::WriteMode-- ^ Safe []safe=Safe[]writeMode::(Accessm)=>WriteMode->ma->ma-- ^ Run action with given 'WriteMode'writeMode=push.constwrite::(DbAccessm)=>Notice->m()-- ^ Send write to server, and if write-mode is 'Safe' then include getLastError request and raise 'WriteFailure' if it reports an error.writenotice=domode<-contextcasemodeofUnsafe->send[notice]Safeparams->dome<-getLastError[notice]paramsmaybe(return())(throw.uncurryWriteFailure)metypeErrorCode=Int-- ^ Error code from getLastErrorgetLastError::(DbAccessm)=>[Notice]->GetLastError->m(Maybe(ErrorCode,String))-- ^ Send notices (writes) then fetch what the last error was, Nothing means no errorgetLastErrorwritesparams=dor<-runCommand'writes$("getlasterror"=:(1::Int)):paramsreturn$(at"code"r,)<$>lookup"err"r{-resetLastError :: (DbConn m) => m ()
-- ^ Clear last error
resetLastError = runCommand1 "reseterror" >> return ()-}-- ** Insertinsert::(DbAccessm)=>Collection->Document->mValue-- ^ Insert document into collection and return its \"_id\" value, which is created automatically if not suppliedinsertcoldoc=head<$>insertManycol[doc]insert_::(DbAccessm)=>Collection->Document->m()-- ^ Same as 'insert' except don't return _idinsert_coldoc=insertcoldoc>>return()insertMany::(DbAccessm)=>Collection->[Document]->m[Value]-- ^ Insert documents into collection and return their \"_id\" values, which are created automatically if not suppliedinsertManycoldocs=doDatabasedb<-thisDatabasedocs'<-liftIO$mapMassignIddocswrite(Insert(db<.>col)docs')mapM(look"_id")docs'insertMany_::(DbAccessm)=>Collection->[Document]->m()-- ^ Same as 'insertMany' except don't return _idsinsertMany_coldocs=insertManycoldocs>>return()assignId::Document->IODocument-- ^ Assign a unique value to _id field if missingassignIddoc=ifX.any(("_id"==).label)docthenreturndocelse(\oid->("_id"=:oid):doc)<$>genObjectId-- ** Update save::(DbAccessm)=>Collection->Document->m()-- ^ Save document to collection, meaning insert it if its new (has no \"_id\" field) or update it if its not new (has \"_id\" field)savecoldoc=caselook"_id"docofNothing->insert_coldocJusti->repsert(Select["_id":=i]col)docreplace::(DbAccessm)=>Selection->Document->m()-- ^ Replace first document in selection with given documentreplace=update[]repsert::(DbAccessm)=>Selection->Document->m()-- ^ Replace first document in selection with given document, or insert document if selection is emptyrepsert=update[Upsert]typeModifier=Document-- ^ Update operations on fields in a document. See <http://www.mongodb.org/display/DOCS/Updating#Updating-ModifierOperations>modify::(DbAccessm)=>Selection->Modifier->m()-- ^ Update all documents in selection using given modifiermodify=update[MultiUpdate]update::(DbAccessm)=>[UpdateOption]->Selection->Document->m()-- ^ Update first document in selection using updater document, unless 'MultiUpdate' option is supplied then update all documents in selection. If 'Upsert' option is supplied then treat updater as document and insert it if selection is empty.updateopts(Selectselcol)up=doDatabasedb<-thisDatabasewrite(Update(db<.>col)optsselup)-- ** Deletedelete::(DbAccessm)=>Selection->m()-- ^ Delete all documents in selectiondelete=delete'[]deleteOne::(DbAccessm)=>Selection->m()-- ^ Delete first document in selectiondeleteOne=delete'[SingleRemove]delete'::(DbAccessm)=>[DeleteOption]->Selection->m()-- ^ Delete all documents in selection unless 'SingleRemove' option is given then only delete first document in selectiondelete'opts(Selectselcol)=doDatabasedb<-thisDatabasewrite(Delete(db<.>col)optssel)-- * Read-- ** MasterOrSlaveOkreadMode::(Accessm)=>MasterOrSlaveOk->ma->ma-- ^ Execute action using given read mode. Master = consistent reads, SlaveOk = eventually consistent reads.readMode=push.constmsOption::MasterOrSlaveOk->[P.QueryOption]msOptionMaster=[]msOptionSlaveOk=[P.SlaveOK]-- ** Query-- | Use 'select' to create a basic query with defaults, then modify if desired. For example, @(select sel col) {limit = 10}@dataQuery=Query{options::[QueryOption],-- ^ Default = []selection::Selection,project::Projector,-- ^ \[\] = all fields. Default = []skip::Word32,-- ^ Number of initial matching documents to skip. Default = 0limit::Limit,-- ^ Maximum number of documents to return, 0 = no limit. Default = 0sort::Order,-- ^ Sort results by this order, [] = no sort. Default = []snapshot::Bool,-- ^ If true assures no duplicates are returned, or objects missed, which were present at both the start and end of the query's execution (even if the object were updated). If an object is new during the query, or deleted during the query, it may or may not be returned, even with snapshot mode. Note that short query responses (less than 1MB) are always effectively snapshotted. Default = FalsebatchSize::BatchSize,-- ^ The number of document to return in each batch response from the server. 0 means use Mongo default. Default = 0hint::Order-- ^ Force MongoDB to use this index, [] = no hint. Default = []}deriving(Show,Eq)dataQueryOption=TailableCursor-- ^ Tailable means cursor is not closed when the last data is retrieved. Rather, the cursor marks the final object's position. You can resume using the cursor later, from where it was located, if more data were received. Like any "latent cursor", the cursor may become invalid at some point – for example if the final object it references were deleted. Thus, you should be prepared to requery on CursorNotFound exception.|NoCursorTimeout-- The server normally times out idle cursors after an inactivity period (10 minutes) to prevent excess memory use. Set this option to prevent that.|AwaitData-- ^ Use with TailableCursor. If we are at the end of the data, block for a while rather than returning no data. After a timeout period, we do return as normal.deriving(Show,Eq)pOption::QueryOption->P.QueryOption-- ^ Convert to protocol query optionpOptionTailableCursor=P.TailableCursorpOptionNoCursorTimeout=P.NoCursorTimeoutpOptionAwaitData=P.AwaitDatatypeProjector=Document-- ^ Fields to return, analogous to the select clause in SQL. @[]@ means return whole document (analogous to * in SQL). @[x =: 1, y =: 1]@ means return only @x@ and @y@ fields of each document. @[x =: 0]@ means return all fields except @x@.typeLimit=Word32-- ^ Maximum number of documents to return, i.e. cursor will close after iterating over this number of documents. 0 means no limit.typeOrder=Document-- ^ Fields to sort by. Each one is associated with 1 or -1. Eg. @[x =: 1, y =: -1]@ means sort by @x@ ascending then @y@ descendingtypeBatchSize=Word32-- ^ The number of document to return in each batch response from the server. 0 means use Mongo default.query::Selector->Collection->Query-- ^ Selects documents in collection that match selector. It uses no query options, projects all fields, does not skip any documents, does not limit result size, uses default batch size, does not sort, does not hint, and does not snapshot.queryselcol=Query[](Selectselcol)[]00[]False0[]batchSizeRemainingLimit::BatchSize->Limit->(Int32,Limit)-- ^ Given batchSize and limit return P.qBatchSize and remaining limitbatchSizeRemainingLimitbatchSizelimit=iflimit==0then(fromIntegralbatchSize',0)-- no limitelseif0<batchSize'&&batchSize'<limitthen(fromIntegralbatchSize',limit-batchSize')else(-fromIntegrallimit,1)wherebatchSize'=ifbatchSize==1then2elsebatchSize-- batchSize 1 is broken because server converts 1 to -1 meaning limit 1queryRequest::Bool->MasterOrSlaveOk->Query->Database->(Request,Limit)-- ^ Translate Query to Protocol.Query. If first arg is true then add special $explain attribute.queryRequestisExplainmosQuery{..}(Databasedb)=(P.Query{..},remainingLimit)whereqOptions=msOptionmos++mappOptionoptionsqFullCollection=db<.>collselectionqSkip=fromIntegralskip(qBatchSize,remainingLimit)=batchSizeRemainingLimitbatchSizelimitqProjector=projectmOrder=ifnullsortthenNothingelseJust("$orderby"=:sort)mSnapshot=ifsnapshotthenJust("$snapshot"=:True)elseNothingmHint=ifnullhintthenNothingelseJust("$hint"=:hint)mExplain=ifisExplainthenJust("$explain"=:True)elseNothingspecial=catMaybes[mOrder,mSnapshot,mHint,mExplain]qSelector=ifnullspecialthenselse("$query"=:s):specialwheres=selectorselectionrunQuery::(DbAccessm)=>Bool->[Notice]->Query->mDelayedCursorState-- ^ Send query request and return cursor staterunQueryisExplainnsq=dodb<-thisDatabaseslaveOK<-contextrequestns(queryRequestisExplainslaveOKqdb)find::(DbAccessm)=>Query->mCursor-- ^ Fetch documents satisfying queryfindq@Query{selection,batchSize}=dodb<-thisDatabasedcs<-runQueryFalse[]qnewCursordb(collselection)batchSizedcsfindOne'::(DbAccessm)=>[Notice]->Query->m(MaybeDocument)-- ^ Send notices and fetch first document satisfying query or Nothing if none satisfy itfindOne'nsq=doCS__docs<-mapErrorIOid=<<runQueryFalsensq{limit=1}return(listToMaybedocs)findOne::(DbAccessm)=>Query->m(MaybeDocument)-- ^ Fetch first document satisfying query or Nothing if none satisfy itfindOne=findOne'[]explain::(DbAccessm)=>Query->mDocument-- ^ Return performance stats of query executionexplainq=do-- same as findOne but with explain set to trueCS__docs<-mapErrorIOid=<<runQueryTrue[]q{limit=1}return$ifnulldocsthenerror("no explain: "++showq)elseheaddocscount::(DbAccessm)=>Query->mInt-- ^ Fetch number of documents satisfying query (including effect of skip and/or limit if present)countQuery{selection=Selectselcol,skip,limit}=at"n"<$>runCommand(["count"=:col,"query"=:sel,"skip"=:(fromIntegralskip::Int32)]++("limit"=?iflimit==0thenNothingelseJust(fromIntegrallimit::Int32)))distinct::(DbAccessm)=>Label->Selection->m[Value]-- ^ Fetch distinct values of field in selected documentsdistinctk(Selectselcol)=at"values"<$>runCommand["distinct"=:col,"key"=:k,"query"=:sel]-- *** CursordataCursor=CursorFullCollectionBatchSize(MVarDelayedCursorState)-- ^ Iterator over results of a query. Use 'next' to iterate or 'rest' to get all results. A cursor is closed when it is explicitly closed, all results have been read from it, garbage collected, or not used for over 10 minutes (unless 'NoCursorTimeout' option was specified in 'Query'). Reading from a closed cursor raises a 'CursorNotFoundFailure'. Note, a cursor is not closed when the pipe is closed, so you can open another pipe to the same server and continue using the cursor.getCursorState::(Accessm)=>Cursor->mCursorState-- ^ Extract current cursor statusgetCursorState(Cursor__var)=mapErrorIOid=<<readMVarvartypeDelayedCursorState=ErrorTFailureIOCursorState-- ^ A promised cursor state which may failrequest::(Accessm)=>[Notice]->(Request,Limit)->mDelayedCursorState-- ^ Send notices and request and return promised cursor staterequestns(req,remainingLimit)=dopromise<-callnsreqreturn$fromReplyremainingLimit=<<promisedataCursorState=CSLimitCursorId[Document]-- ^ CursorId = 0 means cursor is finished. Documents is remaining documents to serve in current batch. Limit is remaining limit for next fetch.fromReply::(ThrowFailurem)=>Limit->Reply->mCursorState-- ^ Convert Reply to CursorState or FailurefromReplylimitReply{..}=domapM_checkResponseFlagrResponseFlagsreturn(CSlimitrCursorIdrDocuments)where-- If response flag indicates failure then throw it, otherwise do nothingcheckResponseFlagflag=caseflagofAwaitCapable->return()CursorNotFound->throw(CursorNotFoundFailurerCursorId)QueryError->throw(QueryFailure$at"$err"$headrDocuments)newCursor::(Accessm)=>Database->Collection->BatchSize->DelayedCursorState->mCursor-- ^ Create new cursor. If you don't read all results then close it. Cursor will be closed automatically when all results are read from it or when eventually garbage collected.newCursor(Databasedb)colbatchcs=dovar<-newMVarcsletcursor=Cursor(db<.>col)batchvaraddMVarFinalizer'var(closeCursorcursor)returncursornext::(Accessm)=>Cursor->m(MaybeDocument)-- ^ Return next document in query result, or Nothing if finished.next(Cursorfcolbatchvar)=modifyMVar'varnextStatewhere-- Pre-fetch next batch promise from server when last one in current batch is returned.nextState::DelayedCursorState->ActionIO(DelayedCursorState,MaybeDocument)nextStatedcs=doCSlimitciddocs<-mapErrorIOiddcscasedocsofdoc:docs'->dodcs'<-ifnulldocs'&&cid/=0thennextBatchlimitcidelsereturn$return(CSlimitciddocs')return(dcs',Justdoc)[]->ifcid==0thenreturn(return$CS00[],Nothing)-- finishedelseerror$"server returned empty batch but says more results on server"nextBatchlimitcid=request[](GetMorefcolbatchSizecid,remLimit)where(batchSize,remLimit)=batchSizeRemainingLimitbatchlimitnextN::(Accessm)=>Int->Cursor->m[Document]-- ^ Return next N documents or less if end is reachednextNnc=catMaybes<$>replicateMn(nextc)rest::(Accessm)=>Cursor->m[Document]-- ^ Return remaining documents in query resultrestc=loop(nextc)closeCursor::(Accessm)=>Cursor->m()closeCursor(Cursor__var)=modifyMVar'varkill'wherekill'dcs=firstreturn<$>(kill=<<mapErrorIOiddcs)kill(CS_cid_)=(CS00[],)<$>ifcid==0thenreturn()elsesend[KillCursors[cid]]isCursorClosed::(Accessm)=>Cursor->mBoolisCursorClosedcursor=doCS_ciddocs<-getCursorStatecursorreturn(cid==0&&nulldocs)-- ** Group-- | Groups documents in collection by key then reduces (aggregates) each groupdataGroup=Group{gColl::Collection,gKey::GroupKey,-- ^ Fields to group bygReduce::Javascript,-- ^ @(doc, agg) -> ()@. The reduce function reduces (aggregates) the objects iterated. Typical operations of a reduce function include summing and counting. It takes two arguments, the current document being iterated over and the aggregation value, and updates the aggregate value.gInitial::Document,-- ^ @agg@. Initial aggregation value supplied to reducegCond::Selector,-- ^ Condition that must be true for a row to be considered. [] means always true.gFinalize::MaybeJavascript-- ^ @agg -> () | result@. 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).}deriving(Show,Eq)dataGroupKey=Key[Label]|KeyFJavascriptderiving(Show,Eq)-- ^ Fields to group by, or function (@doc -> key@) returning a "key object" to be used as the grouping key. Use KeyF instead of Key to specify a key that is not an existing member of the object (or, to access embedded members).groupDocument::Group->Document-- ^ Translate Group data into expected document formgroupDocumentGroup{..}=("finalize"=?gFinalize)++["ns"=:gColl,casegKeyofKeyk->"key"=:map(=:True)k;KeyFf->"$keyf"=:f,"$reduce"=:gReduce,"initial"=:gInitial,"cond"=:gCond]group::(DbAccessm)=>Group->m[Document]-- ^ Execute group query and return resulting aggregate value for each distinct keygroupg=at"retval"<$>runCommand["group"=:groupDocumentg]-- ** MapReduce-- | Maps every document in collection to a list of (key, value) pairs, then for each unique key reduces all its associated values to a single result. There are additional parameters that may be set to tweak this basic operation.dataMapReduce=MapReduce{rColl::Collection,rMap::MapFun,rReduce::ReduceFun,rSelect::Selector,-- ^ Operate on only those documents selected. Default is [] meaning all documents.rSort::Order,-- ^ Default is [] meaning no sortrLimit::Limit,-- ^ Default is 0 meaning no limitrOut::MaybeCollection,-- ^ Output to given permanent collection, otherwise output to a new temporary collection whose name is returned.rKeepTemp::Bool,-- ^ If True, the temporary output collection is made permanent. If False, the temporary output collection persists for the life of the current pipe only, however, other pipes may read from it while the original one is still alive. Note, reading from a temporary collection after its original pipe dies returns an empty result (not an error). The default for this attribute is False, unless 'rOut' is specified, then the collection permanent.rFinalize::MaybeFinalizeFun,-- ^ Function to apply to all the results when finished. Default is Nothing.rScope::Document,-- ^ Variables (environment) that can be accessed from map/reduce/finalize. Default is [].rVerbose::Bool-- ^ Provide statistics on job execution time. Default is False.}deriving(Show,Eq)typeMapFun=Javascript-- ^ @() -> void@. The map function references the variable @this@ to inspect the current object under consideration. The function must call @emit(key,value)@ at least once, but may be invoked any number of times, as may be appropriate.typeReduceFun=Javascript-- ^ @(key, [value]) -> value@. The reduce function receives a key and an array of values and returns an aggregate result value. The MapReduce engine may invoke reduce functions iteratively; thus, these functions must be idempotent. That is, the following must hold for your reduce function: @reduce(k, [reduce(k,vs)]) == reduce(k,vs)@. If you need to perform an operation only once, use a finalize function. The output of emit (the 2nd param) and reduce should be the same format to make iterative reduce possible.typeFinalizeFun=Javascript-- ^ @(key, value) -> final_value@. A finalize function may be run after reduction. Such a function is optional and is not necessary for many map/reduce cases. The finalize function takes a key and a value, and returns a finalized value.mrDocument::MapReduce->Document-- ^ Translate MapReduce data into expected document formmrDocumentMapReduce{..}=("mapreduce"=:rColl):("out"=?rOut)++("finalize"=?rFinalize)++["map"=:rMap,"reduce"=:rReduce,"query"=:rSelect,"sort"=:rSort,"limit"=:(fromIntegralrLimit::Int),"keeptemp"=:rKeepTemp,"scope"=:rScope,"verbose"=:rVerbose]mapReduce::Collection->MapFun->ReduceFun->MapReduce-- ^ MapReduce on collection with given map and reduce functions. Remaining attributes are set to their defaults, which are stated in their comments.mapReducecolmap'red=MapReducecolmap'red[][]0NothingFalseNothing[]FalserunMR::(DbAccessm)=>MapReduce->mCursor-- ^ Run MapReduce and return cursor of results. Error if map/reduce fails (because of bad Javascript)-- TODO: Delete temp result collection when cursor closes. Until then, it will be deleted by the server when pipe closes.runMRmr=find.query[]=<<(at"result"<$>runMR'mr)runMR'::(DbAccessm)=>MapReduce->mDocument-- ^ Run MapReduce and return a result document containing a "result" field holding the output Collection and additional statistic fields. Error if the map/reduce failed (because of bad Javascript).runMR'mr=dodoc<-runCommand(mrDocumentmr)return$iftrue1"ok"docthendocelseerror$"mapReduce error:\n"++showdoc++"\nin:\n"++showmr-- * CommandtypeCommand=Document-- ^ A command is a special query or action against the database. See <http://www.mongodb.org/display/DOCS/Commands> for details.runCommand'::(DbAccessm)=>[Notice]->Command->mDocument-- ^ Send notices then run command and return its resultrunCommand'nsc=maybeerrid<$>findOne'ns(queryc"$cmd")whereerr=error$"Nothing returned for command: "++showcrunCommand::(DbAccessm)=>Command->mDocument-- ^ Run command against the database and return its resultrunCommand=runCommand'[]runCommand1::(DbAccessm)=>UString->mDocument-- ^ @runCommand1 foo = runCommand [foo =: 1]@runCommand1c=runCommand[c=:(1::Int)]eval::(DbAccessm)=>Javascript->mDocument-- ^ Run code on serverevalcode=at"retval"<$>runCommand["$eval"=:code]-- * Primitivessend::(ContextPipem,ThrowFailurem,MonadIOm)=>[Notice]->m()-- ^ Send notices as a contiguous batch to server with no reply. Throw 'ConnectionFailure' if pipe fails.sendns=dopipe<-contextmapErrorIOConnectionFailure(P.sendpipens)call::(ContextPipem,ThrowFailurem,MonadIOm,ThrowFailuren,MonadIOn)=>[Notice]->Request->m(nReply)-- ^ Send notices and request as a contiguous batch to server and return reply promise, which will block when invoked until reply arrives. This call will throw 'ConnectionFailure' if pipe fails on send, and promise will throw 'ConnectionFailure' if pipe fails on receive.callnsr=dopipe<-contextpromise<-mapErrorIOConnectionFailure(P.callpipensr)return(mapErrorIOConnectionFailurepromise){- Authors: Tony Hannan <tony@10gen.com>
Copyright 2010 10gen Inc.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at: http://www.apache.org/licenses/LICENSE-2.0. Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -}