shizzard/erlmongo

Record based Erlang driver for MongoDB with gridfs support

Info¶ ↑

Erlmongo is a pretty complete Erlang driver for mongodb.

It supports records and proplists as datatypes. Strings can be lists or binaries, but strings received from mongodb (as a result of find) will be binaries. The only built in limitation is in regards to record field names. They need to start with [a-z] and be in ascii (because of records). Record values can of course be anything. It’s a stupid idea to use non ascii characters as field names anyway.

Because of the way records work in Erlang, you need to call mongoapi:recinfo/2 before using any record, or define each record in erlmongo.hrl.

When you’re using a selector (picking which fields in the document you wish to get from mongodb), they have to be in the same sequence as they were defined in the record. For instance:

% -record(mydoc {name, i}).
% This will work
Mong:findOne(#mydoc{i = 10}, [#mydoc.name, #mydoc.i]).
% This will NOT work
Mong:findOne(#mydoc{i = 10}, [#mydoc.i, #mydoc.name]).

I haven’t used erlmongo in production yet, so all the bugs might not be ironed out and there are a few inconsistencies with the api (I’ll fix them in the near future).

Examples¶ ↑

make
erl
rr("erlmongo.hrl").
application:start(erlmongo).
% Set mongodb server info. singleServer() is the same as singleServer("localhost:27017")
mongodb:singleServer().
mongodb:connect().
% Create an interface for test database (it has to be a binary)
Mong = mongoapi:new(<<"test">>).

% Save a new document
Mong:save(#mydoc{name = "MyDocument", i = 10}).
% Return the document, but only the "i" field (+ _id which always gets returned)
Mong:findOne(#mydoc{i = 10}, [#mydoc.name]).

% With proplists
Mong:save("mydoc", [{"name", "MyDocument"}, {"i", 10}]).
Mong:findOne("mydoc", [{"i", 10}], [{"name", 1}]).

% Set Index. First parameter is so that the driver knows what collection 
%  we mean. If you have an already constructed record laying around use that.
%  No need to construct a new record just so the driver can read the name.
% Second parameter the index we wish to create. 1 = ascending, -1 = descending.
Mong:ensureIndex(#mydoc{}, [{#mydoc.i, 1}, {#mydoc.name, -1}])

% Find examples:

% Parameters: Search criteria, field selector, docs to skip, docs to return
Mong:find(#mydoc{i = 4}, [#mydoc.name], 0, 0).
% Same thing but with #search record that provides default parameters
Mong:find(#search{criteria = #mydoc{i = 4}, field_selector = [#mydoc.name]}).

% Find with options
Mong:findOpt(#mydoc{i = 4}, undefined, [explain], 0, 0).
% Same thing as above
Mong:findOpt(#search{criteria = #mydoc{i = 4}}, [explain]).
% Also the same, with proplists
Mong:findOpt("mydoc", #search{criteria = [{"i",  4}]}, [explain]).

% Embedded records
Mong:save(#mydoc{name = "zembedom", i = 10, address = #address{city = "ny", street = "some", country = "us"}}).
Mong:find(#mydoc{address = #address{city = "la"}}, undefined, 0, 0).

% Advanced queries (supported: gt, lt, gte, lte, ne, in, nin, all, size, exists):
% Documents with even i
Mong:find(#mydoc{i = {mod, 2, 0}}, undefined, 0,0).
% Documents with i larger than 2:
Mong:find(#mydoc{i = {gt, 2}}, undefined, 0,0).
% Documents with i between 2 and 5: 
Mong:find(#mydoc{i = {in, {gt, 2}, {lt, 5}}}, undefined, 0,0).
% in example: 
Mong:find(#mydoc{tags = {in, [2,3,4]}}, undefined, 0,0).
% exists example: 
Mong:find(#mydoc{tags = {exists, false}}, undefined, 0,0).

% GridFS
{ok, Bin} = file:read_file("SomeFile").
% To open file for writing, use gfsNew
PID = Mong:gfsNew("myfile").
% You can set parameters: mime, meta (embedded document), aliases (array of names), chunk size (default 256k)
%                         flushLimit (at which buffer size data gets flushed to mongodb, def. 1MB)
% PID = Mong:gfsNew("myfile", [{chunkSize, 100}]).
% You can also set collection name (default is fd)
% PID = Mong:gfsNew("myfilecol", "myfile", []).
Mong:gfsWrite(PID,Bin).
Mong:gfsClose(PID).
% Reading
PID = Mong:gfsOpen(#gfs_file{filename = "myfile"}).
Res = Mong:gfsRead(PID,100000).
Mong:gfsClose(PID).

Supported operation list¶ ↑

Collections

• remove

• save

• insert

• update

• batchInsert

• ensureIndex

• deleteIndex

• deleteIndexes

• count

• dropCollection

• createCollection

Search

• find

• findopt

• cursor - getMore - closeCursor

• findOne

DB

• runCmd

• repairDatabase

• cloneDatabase

• dropDatabase

• addUser

• setProfilingLevel

• getProfilingLevel

GridFS

• gfsNew

• gfsWrite

• gfsOpen

• gfsRead

• gfsDelete

• gfsFlush

• gfsClose

Author¶ ↑

Sergej Jurečko