Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 262 lines (175 sloc) 10.234 kB
e605373 @vmx To restore the full history, clone the geocouch_history repository an…
vmx authored
1 Welcome to the world of GeoCouch
2 ================================
3
685db4d @vmx Include information about branches.
vmx authored
4 GeoCouch is a spatial extension for Apache CouchDB and Couchbase.
e605373 @vmx To restore the full history, clone the geocouch_history repository an…
vmx authored
5
6 Prerequisites
7 -------------
8
a976dc3 @vmx Updated README.
vmx authored
9 A working installation of CouchDB with corresponding source
685db4d @vmx Include information about branches.
vmx authored
10 code. GeoCouch works best with Couchbase and the latest stable releases of
11 CouchDB (should be >= 1.1.0).
e605373 @vmx To restore the full history, clone the geocouch_history repository an…
vmx authored
12
685db4d @vmx Include information about branches.
vmx authored
13 ### Understanding the branches:
14
15 This repository contains several branches, please make sure you use
16 the correct one:
17
18 - master: works with the CouchDB master branch from Couchbase's repo
19 (https://github.com/couchbase/couchdb)
20 - couchdb1.1.x: works with Apache CouchDB 1.1.x
4f16bb8 @vmx GeoCouch now works with Apache CouchDB 1.2.x
vmx authored
21 - couchdb1.2.x: works with Apache CouchDB 1.2.x
22 - there is currently no branch for Apache CouchDB 1.3.x
e605373 @vmx To restore the full history, clone the geocouch_history repository an…
vmx authored
23
a976dc3 @vmx Updated README.
vmx authored
24 Installation
25 ------------
e605373 @vmx To restore the full history, clone the geocouch_history repository an…
vmx authored
26
a976dc3 @vmx Updated README.
vmx authored
27 ### Get GeoCouch:
e605373 @vmx To restore the full history, clone the geocouch_history repository an…
vmx authored
28
83b6b1f @pgiraud There seem to be a typo in the README file.
pgiraud authored
29 git clone https://github.com/couchbase/geocouch.git
a976dc3 @vmx Updated README.
vmx authored
30 cd geocouch
e605373 @vmx To restore the full history, clone the geocouch_history repository an…
vmx authored
31
a976dc3 @vmx Updated README.
vmx authored
32 ### Compilation
33
34 Note: Always replace `<vanilla-couch>` with the path to your CouchDB
35 source and `<geocouch>` with the location of the GeoCouch source.
36
37 Set the `COUCH_SRC` environment to the directory that contains the
38 CouchDB core source (`<vanilla-couch>/src/couchdb/`).
39
40 export COUCH_SRC=<vanilla-couch>/src/couchdb
41
42 Run "make" in your <geocouch> directory
43
44 make
45
46 Copy the configuration file for GeoCouch from
b044b53 @vmx Move GeoCouch config file.
vmx authored
47 `<geocouch>/etc/couchdb/default.d/` to
48 `<vanilla-couch>/etc/couchdb/default.d/`
a976dc3 @vmx Updated README.
vmx authored
49
b044b53 @vmx Move GeoCouch config file.
vmx authored
50 cp <geocouch>/etc/couchdb/default.d/geocouch.ini <vanilla-couch>/etc/couchdb/default.d/
a976dc3 @vmx Updated README.
vmx authored
51
52 ### Futon tests
53
54 To make sure your installation is working also copy the Futon tests
55 over (from `<geocouch>/share/www/script/test` to
56 `<vanilla-couch>/share/www/script/test`):
57
58 cp <geocouch>/share/www/script/test/* <vanilla-couch>/share/www/script/test/
59
e360933 @pgiraud Wrong path to the couch_tests.js file
pgiraud authored
60 Add the test to `<vanilla-couch>/share/www/script/couch_tests.js`
a976dc3 @vmx Updated README.
vmx authored
61
62 loadTest("spatial.js");
a515322 @vmx Better ETag support for spatial indexes. Hack (therefore undocumented…
vmx authored
63 loadTest("list_spatial.js");
64 loadTest("etags_spatial.js");
8c0df31 @vmx Typo in listing of tests.
vmx authored
65 loadTest("multiple_spatial_rows.js");
2f7d61f @vmx Added new tests to README.
vmx authored
66 loadTest("spatial_compaction.js");
40b149b @vmx Index creation on empty indexes was triggered by stale=ok, _spatial/_…
vmx authored
67 loadTest("spatial_design_docs.js");
f32800f @vmx Don't lose documents from the spatial index after restart. GC-1
vmx authored
68 loadTest("spatial_bugfixes.js");
3222222 @fdmanana Adapt spatial merger to recent couch_index_merger changes
fdmanana authored
69 loadTest("spatial_merging.js");
890c418 @vmx Add skip and limit to GeoCouch
vmx authored
70 loadTest("spatial_offsets.js");
a976dc3 @vmx Updated README.
vmx authored
71
72 ### Run CouchDB with GeoCouch
73
74 The compiled beam files from GeoCouch need to be in Erlang's path,
75 which can be set with the `ERL_FLAGS` environment variable:
76
18531c1 @vmx Use rebar for building GeoCouch
vmx authored
77 export ERL_FLAGS="-pa <geocouch>/ebin"
a976dc3 @vmx Updated README.
vmx authored
78
79 If you run a dev instance with CouchDB's `./utils/run` you can also
80 define it on startup:
81
18531c1 @vmx Use rebar for building GeoCouch
vmx authored
82 ERL_FLAGS="-pa <geocouch>/ebin" <vanilla-couch>/utils/run
e605373 @vmx To restore the full history, clone the geocouch_history repository an…
vmx authored
83
84
85 Using GeoCouch
86 --------------
87
88 Create a database:
89
90 curl -X PUT http://127.0.0.1:5984/places
91
92 Add a Design Document with a spatial function:
93
94 curl -X PUT -d '{"spatial":{"points":"function(doc) {\n if (doc.loc) {\n emit({\n type: \"Point\",\n coordinates: [doc.loc[0], doc.loc[1]]\n }, [doc._id, doc.loc]);\n }};"}}' http://127.0.0.1:5984/places/_design/main
95
96 Put some data into it:
97
98 curl -X PUT -d '{"loc": [-122.270833, 37.804444]}' http://127.0.0.1:5984/places/oakland
99 curl -X PUT -d '{"loc": [10.898333, 48.371667]}' http://127.0.0.1:5984/places/augsburg
100
101 Make a bounding box request:
102
103 curl -X GET 'http://localhost:5984/places/_design/main/_spatial/points?bbox=0,0,180,90'
104
105 It should return:
106
107 {"update_seq":3,"rows":[
a5b4c28 @vmx Update README to reflect current output.
vmx authored
108 {"id":"augsburg","bbox":[10.898333,48.371667,10.898333,48.371667],"geometry":{"type":"Point","coordinates":[10.898333,48.371667]},"value":["augsburg",[10.898333,48.371667]]}
e605373 @vmx To restore the full history, clone the geocouch_history repository an…
vmx authored
109 ]}
110
111 The Design Document Function
112 ----------------------------
113
114 function(doc) {
115 if (doc.loc) {
116 emit({
117 type: "Point",
118 coordinates: [doc.loc[0], doc.loc[1]]
119 }, [doc._id, doc.loc]);
120 }};"
121
122 It uses the emit() from normal views. The key is a
123 [GeoJSON](http://geojson.org) geometry, the value is any arbitrary JSON. All
124 geometry types (even GemetryCollections) are supported.
125
126 If the GeoJSON geometry contains a `bbox` property it will be used instead
127 of calculating it from the geometry (even if it's wrong, i.e. is not
128 the actual bounding box).
129
130
131 Bounding box search and the date line
132 -------------------------------------
133
134 A common problem when performing bounding box searches is the date
135 line/poles. As the bounding box follows the GeoJSON specification,
136 where the first two numbers are the lower left coordinate, the last
137 two numbers the upper right coordinate, it is easy to map it over the
138 date line/poles. The lower coordinate would have a higher value than
139 the upper one. Such a bounding box has a seems invalid at first
140 glance, but isn't. For example a bounding box like `110,-60,-30,15`
141 would include Australia and South America, but not Africa.
142
e6b6e06 @vmx Updated README to match the new plane_bounds parameter.
vmx authored
143 GeoCouch operates on a plane and doesn't perform spherical
144 calculations. Therefore the bounds of the plane needs to be set
145 explicitly with the `plane_bounds` parameter. If bounding boxes are
146 flipped, a search across those bounds will be performed
147 automatically. Give it a try (with the same Design Document as
e605373 @vmx To restore the full history, clone the geocouch_history repository an…
vmx authored
148 above). Insert some Documents:
149
150 curl -X PUT -d '{"loc": [17.15, -22.566667]}' http://127.0.0.1:5984/places/namibia
151 curl -X PUT -d '{"loc": [135, -25]}' http://127.0.0.1:5984/places/australia
152 curl -X PUT -d '{"loc": [-52.95, -10.65]}' http://127.0.0.1:5984/places/brasilia
153
154 And request only Australia and Brasilia:
155
e6b6e06 @vmx Updated README to match the new plane_bounds parameter.
vmx authored
156 curl -X GET 'http://localhost:5984/places/_design/main/_spatial/points?bbox=110,-60,-30,15&plane_bounds=-180,-90,180,90'
e605373 @vmx To restore the full history, clone the geocouch_history repository an…
vmx authored
157
158 The result is as expected:
159
160 {"update_seq":6,"rows":[
a5b4c28 @vmx Update README to reflect current output.
vmx authored
161 {"id":"australia","bbox":[135,-25,135,-25],"geometry":{"type":"Point","coordinates":[135,-25]},"value":["australia",[135,-25]]},
162 {"id":"brasilia","bbox":[-52.95,-10.65,-52.95,-10.65],"geometry":{"type":"Point","coordinates":[-52.95,-10.65]},"value":["brasilia",[-52.95,-10.65]]}
e605373 @vmx To restore the full history, clone the geocouch_history repository an…
vmx authored
163 ]}
164
165 The bounding with the same numbers, but different order
166 (`-30,-60,110,15`) would only return Namibia:
167
e6b6e06 @vmx Updated README to match the new plane_bounds parameter.
vmx authored
168 curl -X GET 'http://localhost:5984/places/_design/main/_spatial/points?bbox=-30,-60,110,15&plane_bounds=-180,-90,180,90'
e605373 @vmx To restore the full history, clone the geocouch_history repository an…
vmx authored
169
170 {"update_seq":6,"rows":[
a5b4c28 @vmx Update README to reflect current output.
vmx authored
171 {"id":"namibia","bbox":[17.15,-22.566667,17.15,-22.566667],"geometry":{"type":"Point","coordinates":[17.15,-22.566667]},"value":["namibia",[17.15,-22.566667]]}
e605373 @vmx To restore the full history, clone the geocouch_history repository an…
vmx authored
172 ]}
173
174 List function support
175 ---------------------
176
177 GeoCouch supports List functions just as CouchDB does for Views. This way
178 you can output any arbitrary format, e.g. GeoRSS.
179
180 As an example we output the points as WKT. Add a new Design Document
181 with an additional List function (the rest is the same as above). Make
182 sure you use the right `_rev`:
183
a5b4c28 @vmx Update README to reflect current output.
vmx authored
184 curl -X PUT -d '{"_rev": "1-121efc747b00743b8c7621ffccf1ac40", "lists": {"wkt": "function(head, req) {\n var row;\n while (row = getRow()) {\n send(\"POINT(\" + row.geometry.coordinates.join(\" \") + \")\\n\");\n }\n};"}, "spatial":{"points":"function(doc) {\n if (doc.loc) {\n emit({\n type: \"Point\",\n coordinates: [doc.loc[0], doc.loc[1]]\n }, [doc._id, doc.loc]);\n }};"}}' http://127.0.0.1:5984/places/_design/main
e605373 @vmx To restore the full history, clone the geocouch_history repository an…
vmx authored
185
186 Now you can request this List function as you would do for CouchDB,
b578806 @vmx Updated README to the new spatial _list end point.
vmx authored
187 though with a different Design handler (`_spatial/_list` instead of
e605373 @vmx To restore the full history, clone the geocouch_history repository an…
vmx authored
188 `_list` ):
189
b578806 @vmx Updated README to the new spatial _list end point.
vmx authored
190 curl -X GET 'http://localhost:5984/places/_design/main/_spatial/_list/wkt/points?bbox=-180,-90,180,90'
e605373 @vmx To restore the full history, clone the geocouch_history repository an…
vmx authored
191
192 The result is:
193
194 POINT(10.898333 48.371667)
a5b4c28 @vmx Update README to reflect current output.
vmx authored
195 POINT(-122.270833 37.804444)
e605373 @vmx To restore the full history, clone the geocouch_history repository an…
vmx authored
196 POINT(17.15 -22.566667)
197 POINT(135 -25)
198 POINT(-52.95 -10.65)
199
200 Using List functions from Design Documents other than the one containing the
201 Spatial functions is supported as well. This time we add the Document
202 ID in parenthesis:
203
a5b4c28 @vmx Update README to reflect current output.
vmx authored
204 curl -X PUT -d '{"lists": {"wkt": "function(head, req) {\n var row;\n while (row = getRow()) {\n send(\"POINT(\" + row.geometry.coordinates.join(\" \") + \") (\" + row.id + \")\\n\");\n }\n};"}}' http://127.0.0.1:5984/places/_design/listfunonly
e605373 @vmx To restore the full history, clone the geocouch_history repository an…
vmx authored
205
b578806 @vmx Updated README to the new spatial _list end point.
vmx authored
206 curl -X GET 'http://localhost:5984/places/_design/listfunonly/_spatial/_list/wkt/main/points?bbox=-180,-90,180,90'
e605373 @vmx To restore the full history, clone the geocouch_history repository an…
vmx authored
207
208
209 Other supported query arguments
210 -------------------------------
211
212 ### stale ###
d06a19f @vmx Fixed typos in the README.
vmx authored
213 `stale=ok` is supported. The spatial index won't be rebuilt even if
e605373 @vmx To restore the full history, clone the geocouch_history repository an…
vmx authored
214 new Documents were added. It works for normal spatial queries as well
215 as for the spatial List functions.
216
217 ### count ###
218 `count` is a boolean. `count=true` will only return the number of geometries
219 the query will return, not the geometry themselves.
220
a5b4c28 @vmx Update README to reflect current output.
vmx authored
221 curl -X GET 'http://localhost:5984/places/_design/main/_spatial/points?bbox=0,0,180,90&count=true'
e605373 @vmx To restore the full history, clone the geocouch_history repository an…
vmx authored
222
223 {"count":1}
6e66848 @vmx Updated README with new _compact, _spatial_cleanup and _info handlers.
vmx authored
224
890c418 @vmx Add skip and limit to GeoCouch
vmx authored
225 ### limit ###
226 With `limit` you can limit the number of rows that should be returned.
227
228 curl -X GET 'http://localhost:5984/places/_design/main/_spatial/points?bbox=-180,-90,180,90&limit=2'
229
230 {"update_seq":8,"rows":[
231 {"id":"augsburg","bbox":[10.898333,48.371667,10.898333,48.371667],"geometry":{"type":"Point","coordinates":[10.898333,48.371667]},"value":["augsburg",[10.898333,48.371667]]},
232 {"id":"oakland","bbox":[-122.270833,37.804444,-122.270833,37.804444],"geometry":{"type":"Point","coordinates":[-122.270833,37.804444]},"value":["oakland",[-122.270833,37.804444]]}
233 ]}
234
235 ### skip ###
236 With `skip` you start to return the results at a certain offset.
237
238 curl -X GET 'http://localhost:5984/places/_design/main/_spatial/points?bbox=-180,-90,180,90&skip=3'
239
240 {"update_seq":8,"rows":[
241 {"id":"australia","bbox":[135,-25,135,-25],"geometry":{"type":"Point","coordinates":[135,-25]},"value":["australia",[135,-25]]},
242 {"id":"brasilia","bbox":[-52.95,-10.65,-52.95,-10.65],"geometry":{"type":"Point","coordinates":[-52.95,-10.65]},"value":["brasilia",[-52.95,-10.65]]}
243 ]}
244
6e66848 @vmx Updated README with new _compact, _spatial_cleanup and _info handlers.
vmx authored
245
246 Compaction, cleanup and info
247 ----------------------------
248
249 The API of GeoCouch's spatial indexes is similar to the one for the
250 Views. Compaction of spatial indexes is per Design Document, thus:
251
252 curl -X POST 'http://localhost:5984/places/_design/main/_spatial/_compact' -H 'Content-Type: application/json'
253
d06a19f @vmx Fixed typos in the README.
vmx authored
254 To cleanup spatial indexes that are no longer in use (this is per database):
6e66848 @vmx Updated README with new _compact, _spatial_cleanup and _info handlers.
vmx authored
255
256 curl -X POST 'http://localhost:5984/places/_spatial_cleanup' -H 'Content-Type: application/json'
257
258 To get information about the spatial indexes of a certain Design
259 Document use the the `_info` handler:
260
261 curl -X GET 'http://localhost:5984/places/_design/main/_spatial/_info'
Something went wrong with that request. Please try again.