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