README.markdown

The goal of emongo is to be stable, fast and easy to use.

Build

make

Start emongo

application:start(emongo).

Connecting to mongodb

Option 1 - Config file

example.config:

[{emongo, [
	{pools, [
		{pool1, [
			{size, 1},
			{host, "localhost"},
			{port, 27017},
			{database, "testdatabase"}
		]}
	]}
]}].

specify the config file path when starting Erlang

erl -config priv/example

start the application

application:start(emongo).

Option 2 - Add pool

start the app and then add as many pools as you like

application:start(emongo).
emongo:add_pool(pool1, "localhost", 27017, "testdatabase", 1).

API Type Reference

PoolId = atom()
Host = string()
Port = integer()
Database = string()
PoolSize = integer()
CollectionName = string()
Selector = Document
Document = [{Key, Val}]
Key = string() | atom() | binary() | integer()
Val = float() | string() | binary() | Document | {array, [term()]} | {binary, BinSubType, binary()} | {oid, binary()} | {oid, string()} | bool() | now() | datetime() | undefined | {regexp, string(), string()} | integer()
BinSubType = integer() http://www.mongodb.org/display/DOCS/BSON#BSON-noteondatabinary

Add Pool

emongo:add_pool(PoolId, Host, Port, Database, PoolSize) -> ok

Insert

PoolId = atom()
CollectionName = string()
Document = [{Key, Val}]
Documents = [Document]

emongo:insert(PoolId, CollectionName, Document) -> ok
emongo:insert(PoolId, CollectionName, Documents) -> ok

Examples

%% insert a single document with two fields into the "collection" collection
emongo:insert(test, "collection", [{"field1", "value1"}, {"field2", "value2"}]).

%% insert two documents, each with a single field into the "collection" collection
emongo:insert(test, "collection", [[{"document1_field1", "value1"}], [{"document2_field1", "value1"}]]).	

Update

PoolId = atom()
CollectionName = string()
Selector = Document
Document = [{Key, Val}]
Upsert = true | false (insert a new document if the selector does not match an existing document)

%% by default upsert == false
emongo:update(PoolId, CollectionName, Selector, Document) -> ok
emongo:update(PoolId, CollectionName, Selector, Document, Upsert) -> ok

Examples

%% update the document that matches "field1" == "value1"
emongo:update(test, "collection", [{"field1", "value1"}], [{"field1", "value1"}, {"field2", "value2"}]).

Delete

PoolId = atom()
CollectionName = string()
Selector = Document

%% delete all documents in a collection
emongo:delete(PoolId, CollectionName) -> ok

%% delete all documents in a collection that match a selector
emongo:delete(PoolId, CollectionName, Selector) -> ok

Find

Options = {timeout, Timeout} | {limit, Limit} | {offset, Offset} | {orderby, Orderby} | {fields, Fields} | response_options
Timeout = integer (timeout in milliseconds)
Limit = integer
Offset = integer
Orderby = [{Key, Direction}]
Direction = 1 (Asc) | -1 (Desc)
Fields = [Key] = specifies a list of fields to return in the result set
response_options = return #response{header, response_flag, cursor_id, offset, limit, documents}
Result = [Document] | response()

emongo:find(PoolId, CollectionName) -> Result
emongo:find(PoolId, CollectionName, Selector) -> Result
emongo:find(PoolId, CollectionName, Selector, Options) -> Result

Examples

limit, offset, timeout, orderby, fields

%% find documents from 'collection' where field1 equals 1 and abort the query if it takes more than 5 seconds
%% limit the number of results to 100 and offset the first document 10 documents from the beginning
%% return documents in ascending order, sorted by the value of field1
%% limit the fields in the return documents to field1 (the _id field is always included in the results)
emongo:find(test, "collection", [{"field1", 1}], [{limit, 100}, {offset, 10}, {timeout, 5000}, {orderby, [{"field1", asc}]}, {fields, ["field1"]}]).

great than, less than, great than or equal, less than or equal

%% find documents where field1 is greater than 5 and less than 10
emongo:find(test, "collection", [{"field1", [{gt, 5}, {lt, 10}]}]).
  
%% find documents where field1 is greater than or equal to 5 and less than or equal to 10
emongo:find(test, "collection", [{"field1", [{gte, 5}, {lte, 10}]}]).
  
%% find documents where field1 is greater than 5 and less than 10
emongo:find(test, "collection", [{"field1", [{'>', 5}, {'<', 10}]}]).
  
%% find documents where field1 is greater than or equal to 5 and less than or equal to 10
emongo:find(test, "collection", [{"field1", [{'>=', 5}, {'=<', 10}]}]).

not equal

%% find documents where field1 is not equal to 5 or 10
emongo:find(test, "collection", [{"field1", [{ne, 5}, {ne, 10}]}]).
  
%% find documents where field1 is not equal to 5
emongo:find(test, "collection", [{"field1", [{'=/=', 5}]}]).
  
%% find documents where field1 is not equal to 5
emongo:find(test, "collection", [{"field1", [{'/=', 5}]}]).

in

%% find documents where the value of field1 is one of the values in the list [1,2,3,4,5]
emongo:find(test, "collection", [{"field1", [{in, [1,2,3,4,5]}]}]).

not in

%% find documents where the value of field1 is NOT one of the values in the list [1,2,3,4,5]
emongo:find(test, "collection", [{"field1", [{nin, [1,2,3,4,5]}]}]).

all

%% find documents where the value of field1 is an array and contains all of the values in the list [1,2,3,4,5]
emongo:find(test, "collection", [{"field1", [{all, [1,2,3,4,5]}]}]).

size

%% find documents where the value of field1 is an array of size 10
emongo:find(test, "collection", [{"field1", [{size, 10}]}]).

exists

%% find documents where field1 exists
emongo:find(test, "collection", [{"field1", [{exists, true}]}]).

where

%% find documents where the value of field1 is greater than 10
emongo:find(test, "collection", [{where, "this.field1 > 10"}]).

nested queries

%% find documents with an address field containing a sub-document 
%% with street equal to "Maple Drive".
%% ie: [{"address", [{"street", "Maple Drive"}, {"zip", 94114}]
emongo:find(test, "people", [{"address.street", "Maple Drive"}]).