Skip to content
Newer
Older
100644 210 lines (176 sloc) 7.52 KB
b446d3a @SergejJurecko first commit
authored
1 = Info
2
6564909 @SergejJurecko mochijson compatible encoding for saves, thanks to Groshev Dmitry
authored
3 Erlmongo is a pretty complete Erlang driver for mongodb.
b446d3a @SergejJurecko first commit
authored
4
5 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.
6
3397cde @SergejJurecko mongoapi:recinfo/2 dynamic loading of records if not declared in the hrl
authored
7 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.
8
154c121 @SergejJurecko some more info about records
authored
9 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.
10 For instance:
11 % -record(mydoc {name, i}).
12 % This will work
13 Mong:findOne(#mydoc{i = 10}, [#mydoc.name, #mydoc.i]).
14 % This will NOT work
15 Mong:findOne(#mydoc{i = 10}, [#mydoc.i, #mydoc.name]).
910ff60 @SergejJurecko bugfixes and another way to call find
authored
16
5903920 @SergejJurecko bad function name
authored
17 WARNING: If you use modifier updates with {set,Value} ($set), do not use records if that value is a string that changes size (it should work for integers for instance). Mongo changes the document element sequence and this messes up record serialization.
7d426e7 @SergejJurecko {struct,Obj} for mochijson compatibility
authored
18
5903920 @SergejJurecko bad function name
authored
19 Connections are always single to the master:
feed899 @SergejJurecko much better connection handling. Connections are no longer blocking o…
authored
20 - master/slave - read and write from master
21 - master/master - pick a master at random and use it for everything
5903920 @SergejJurecko bad function name
authored
22 - replica pairs/sets - find out which is master and connect to it
b1b2c30 @SergejJurecko readme formatting
authored
23 If your usage pattern is read heavy and want to use slaves for reading, connect to them with singleServer call. Don't write to slave connections or bad things will happen.
24
6564909 @SergejJurecko mochijson compatible encoding for saves, thanks to Groshev Dmitry
authored
25 Always use an atom for naming connections. The connection process will register itself on that name.
7d426e7 @SergejJurecko {struct,Obj} for mochijson compatibility
authored
26 Runtime connection API:
1b66e5f @SergejJurecko replica sets
authored
27 mongodb:singleServer/1,2
7d426e7 @SergejJurecko {struct,Obj} for mochijson compatibility
authored
28 mongodb:replicaPairs/3
1b66e5f @SergejJurecko replica sets
authored
29 mongodb:replicaSets/2
7d426e7 @SergejJurecko {struct,Obj} for mochijson compatibility
authored
30 mongodb:masterSlave/3
31 mongodb:connect/1
2f5b223 @SergejJurecko mongodb:sharded/2 add multiple or just one mongos, will connect to ra…
authored
32 mongodb:sharded/2
b1b2c30 @SergejJurecko readme formatting
authored
33
0a146b8 @SergejJurecko readme update
authored
34 Connection info is saved in an application variable (erlmongo,connections) and updated with every call to: singleServer, masterSlave, replicaPairs, masterMaster, replicaSets, sharded and deleteConnection. If mongodb process crashes for some reason, connections will be restarted. Also if the application itself is stopped and started. You can add a connections variable to erlmongo.app file:
feed899 @SergejJurecko much better connection handling. Connections are no longer blocking o…
authored
35 % def is name of connection, types can be: masterSlave,masterMaster or replicaPairs. This is how singleServer info is saved:
36 {env, [{def,{masterSlave,{"localhost",27017},{"localhost",27017}}}]},
b446d3a @SergejJurecko first commit
authored
37
1b66e5f @SergejJurecko replica sets
authored
38 = Replica sets
6564909 @SergejJurecko mochijson compatible encoding for saves, thanks to Groshev Dmitry
authored
39 % List of servers does not have to be the entire list of the replica set.
1b66e5f @SergejJurecko replica sets
authored
40 % Erlmongo will read the primary server from them and connect to it (even if not in the list).
41 mongodb:replicaSets(repl,["127.0.0.1:30000","127.0.0.1:30001"]).
42 mongodb:connect(repl).
6564909 @SergejJurecko mochijson compatible encoding for saves, thanks to Groshev Dmitry
authored
43
b446d3a @SergejJurecko first commit
authored
44 = Examples
d8a7b54 @SergejJurecko since erlmongo uses now() for date format: mongodb:datetime_to_now/1
authored
45 make
46 erl
b446d3a @SergejJurecko first commit
authored
47 rr("erlmongo.hrl").
29d75e9 @SergejJurecko just a bit of cleanup
authored
48 application:start(erlmongo).
5e897ad @SergejJurecko connection pools, breaks api
authored
49 % Set mongodb server info. singleServer(PoolName) is the same as singleServer(PoolName,"localhost:27017")
50 mongodb:singleServer(def).
51 mongodb:connect(def).
b446d3a @SergejJurecko first commit
authored
52 % Create an interface for test database (it has to be a binary)
5e897ad @SergejJurecko connection pools, breaks api
authored
53 Mong = mongoapi:new(def,<<"test">>).
6564909 @SergejJurecko mochijson compatible encoding for saves, thanks to Groshev Dmitry
authored
54
b446d3a @SergejJurecko first commit
authored
55 % Save a new document
56 Mong:save(#mydoc{name = "MyDocument", i = 10}).
57 % Return the document, but only the "i" field (+ _id which always gets returned)
71648ab @SergejJurecko bugfixes and some more examples
authored
58 Mong:findOne(#mydoc{i = 10}, [#mydoc.name]).
6564909 @SergejJurecko mochijson compatible encoding for saves, thanks to Groshev Dmitry
authored
59
71648ab @SergejJurecko bugfixes and some more examples
authored
60 % With proplists
61 Mong:save("mydoc", [{"name", "MyDocument"}, {"i", 10}]).
62 Mong:findOne("mydoc", [{"i", 10}], [{"name", 1}]).
b446d3a @SergejJurecko first commit
authored
63
6564909 @SergejJurecko mochijson compatible encoding for saves, thanks to Groshev Dmitry
authored
64 % Switch to mochijson's style proplists (string = binary, array = list, no list-coded strings)
65 Mong:set_encode_style(mochijson),
66 Mong:save("mydoc", [{<<"name">>, <<"2-dim array">>}, {<<"data">>, [[1.1, 2.2], [3.3, 4.4]]}]).
67
68
69 % Set Index. First parameter is so that the driver knows what collection
b446d3a @SergejJurecko first commit
authored
70 % we mean. If you have an already constructed record laying around use that.
71 % No need to construct a new record just so the driver can read the name.
72 % Second parameter the index we wish to create. 1 = ascending, -1 = descending.
73 Mong:ensureIndex(#mydoc{}, [{#mydoc.i, 1}, {#mydoc.name, -1}])
74
71648ab @SergejJurecko bugfixes and some more examples
authored
75 % Find examples:
76
5537a9a @SergejJurecko Nicer or syntax: M:find(mydoc,[{'or',[{a,1},{i,11}]}],undefined,0,100).
authored
77 % Or
78 M:find("mydoc",[{'or',[{"a",1},{"i",11}]}],undefined,0,100).
79
71648ab @SergejJurecko bugfixes and some more examples
authored
80 % Parameters: Search criteria, field selector, docs to skip, docs to return
81 Mong:find(#mydoc{i = 4}, [#mydoc.name], 0, 0).
82 % Same thing but with #search record that provides default parameters
83 Mong:find(#search{criteria = #mydoc{i = 4}, field_selector = [#mydoc.name]}).
6564909 @SergejJurecko mochijson compatible encoding for saves, thanks to Groshev Dmitry
authored
84
71648ab @SergejJurecko bugfixes and some more examples
authored
85 % Find with options
86 Mong:findOpt(#mydoc{i = 4}, undefined, [explain], 0, 0).
87 % Same thing as above
88 Mong:findOpt(#search{criteria = #mydoc{i = 4}}, [explain]).
89 % Also the same, with proplists
90 Mong:findOpt("mydoc", #search{criteria = [{"i", 4}]}, [explain]).
91
30adc7f @SergejJurecko embedded records/documents
authored
92 % Embedded records
93 Mong:save(#mydoc{name = "zembedom", i = 10, address = #address{city = "ny", street = "some", country = "us"}}).
94 Mong:find(#mydoc{address = #address{city = "la"}}, undefined, 0, 0).
95
45b7d92 @SergejJurecko advanced queries
authored
96 % Advanced queries (supported: gt, lt, gte, lte, ne, in, nin, all, size, exists):
97 % Documents with even i
98 Mong:find(#mydoc{i = {mod, 2, 0}}, undefined, 0,0).
99 % Documents with i larger than 2:
100 Mong:find(#mydoc{i = {gt, 2}}, undefined, 0,0).
6564909 @SergejJurecko mochijson compatible encoding for saves, thanks to Groshev Dmitry
authored
101 % Documents with i between 2 and 5:
45b7d92 @SergejJurecko advanced queries
authored
102 Mong:find(#mydoc{i = {in, {gt, 2}, {lt, 5}}}, undefined, 0,0).
6564909 @SergejJurecko mochijson compatible encoding for saves, thanks to Groshev Dmitry
authored
103 % in example:
45b7d92 @SergejJurecko advanced queries
authored
104 Mong:find(#mydoc{tags = {in, [2,3,4]}}, undefined, 0,0).
6564909 @SergejJurecko mochijson compatible encoding for saves, thanks to Groshev Dmitry
authored
105 % exists example:
45b7d92 @SergejJurecko advanced queries
authored
106 Mong:find(#mydoc{tags = {exists, false}}, undefined, 0,0).
107
822490d @SergejJurecko findandmodify example in readme
authored
108 % findandmodify command
109 Mong:runCmd([{"findandmodify", "collectionname"},{"query", [{"fn","onmeta.flv"},{"ch","somechan"}]},{"remove",1}]).
110
cc4629e @SergejJurecko bugfixes,optimizations and gridfs
authored
111 % GridFS
117dd11 @SergejJurecko readme update for gfsIndexes/0,1
authored
112 % Always run this on collection before writing the first file
113 Mong:gfsIndexes().
cc4629e @SergejJurecko bugfixes,optimizations and gridfs
authored
114 {ok, Bin} = file:read_file("SomeFile").
115 % To open file for writing, use gfsNew
116 PID = Mong:gfsNew("myfile").
117 % You can set parameters: mime, meta (embedded document), aliases (array of names), chunk size (default 256k)
118 % flushLimit (at which buffer size data gets flushed to mongodb, def. 1MB)
119 % PID = Mong:gfsNew("myfile", [{chunkSize, 100}]).
120 % You can also set collection name (default is fd)
121 % PID = Mong:gfsNew("myfilecol", "myfile", []).
122 Mong:gfsWrite(PID,Bin).
123 Mong:gfsClose(PID).
124 % Reading
125 PID = Mong:gfsOpen(#gfs_file{filename = "myfile"}).
126 Res = Mong:gfsRead(PID,100000).
127 Mong:gfsClose(PID).
128
822490d @SergejJurecko findandmodify example in readme
authored
129 = Supported Data types and modifiers
6564909 @SergejJurecko mochijson compatible encoding for saves, thanks to Groshev Dmitry
authored
130 Look at mongodb:encode_element/1
131
132 = Switching to mochijson's style proplists
133 Mochijson library has a different string/list encoding convention:
134 string = binary
135 array = list
136 You can choose a preferred way to encode with mongoapi:set_encode_style/1.
137 Selected style is set to a selected server and table and not for mongoapi module instance.
138 An example:
139 ...
140 12> Mong:set_encode_style(default).
141 ok
142 13> Mong:save("foobar", [{<<"data">>, [[1.1, 2.2], [3.3, 4.4]]}]).
143 ** exception error: bad argument
144 in function unicode:characters_to_binary/1
145 called as unicode:characters_to_binary([[1.1,2.2],[3.3,4.4]])
146 in call from mongodb:encode_cstring/1
147 in call from mongodb:encode_element/1
148 in call from mongodb:'-encode/2-fun-0-'/3
149 in call from lists:foldl/3
150 in call from mongodb:encode/2
151 in call from mongoapi:save/3
152 14> Mong:set_encode_style(mochijson).
153 ok
154 15> Mong:save("foobar", [{<<"data">>, [[1.1, 2.2], [3.3, 4.4]]}]).
155 {oid,<<"000af08b902dee723e000006">>}
156
822490d @SergejJurecko findandmodify example in readme
authored
157
83c3f9b @SergejJurecko op list to readme
authored
158 == Supported operation list
3bab6cc @SergejJurecko op list to readme
authored
159 Collections
811550c @SergejJurecko op list to readme
authored
160 * remove
161 * save
162 * insert
163 * update
164 * batchInsert
165 * ensureIndex
166 * deleteIndex
167 * deleteIndexes
168 * count
169 * dropCollection
170 * createCollection
5e897ad @SergejJurecko connection pools, breaks api
authored
171 * group
811550c @SergejJurecko op list to readme
authored
172
3bab6cc @SergejJurecko op list to readme
authored
173 Search
811550c @SergejJurecko op list to readme
authored
174 * find
6564909 @SergejJurecko mochijson compatible encoding for saves, thanks to Groshev Dmitry
authored
175 * findopt
811550c @SergejJurecko op list to readme
authored
176 * cursor - getMore - closeCursor
177 * findOne
178
3bab6cc @SergejJurecko op list to readme
authored
179 DB
5e897ad @SergejJurecko connection pools, breaks api
authored
180 * eval
181 * stats
811550c @SergejJurecko op list to readme
authored
182 * runCmd
183 * repairDatabase
184 * cloneDatabase
185 * dropDatabase
186 * addUser
187 * setProfilingLevel
188 * getProfilingLevel
189
cc4629e @SergejJurecko bugfixes,optimizations and gridfs
authored
190 GridFS
117dd11 @SergejJurecko readme update for gfsIndexes/0,1
authored
191 * gdsIndexes
cc4629e @SergejJurecko bugfixes,optimizations and gridfs
authored
192 * gfsNew
193 * gfsWrite
194 * gfsOpen
195 * gfsRead
196 * gfsDelete
197 * gfsFlush
198 * gfsClose
199
c055556 @SergejJurecko autotools and erlmongo.spec for rpm thanks to sipXecs
authored
200 == Building
6564909 @SergejJurecko mochijson compatible encoding for saves, thanks to Groshev Dmitry
authored
201 erl -make
c055556 @SergejJurecko autotools and erlmongo.spec for rpm thanks to sipXecs
authored
202
203 or with autotools
204 ./configure
205 make
206 make install
207
3bab6cc @SergejJurecko op list to readme
authored
208 == Author
41073da @SergejJurecko added author
authored
209 Sergej Jurečko
Something went wrong with that request. Please try again.