Name Date Size

..19-Aug-20204 KiB

etc/couchdb/default.d/H19-Aug-20204 KiB

include/H19-Aug-20204 KiB

README.mdH A D19-Aug-20206.5 KiB

rebar.config.scriptH A D19-Aug-2020911

share/www/script/test/H19-Aug-20204 KiB

src/H19-Aug-20204 KiB

utils/H19-Aug-20204 KiB

README.md

1Welcome to the world of GeoCouch
2================================
3
4GeoCouch is a spatial extension for Apache CouchDB and Couchbase.
5
6Prerequisites
7-------------
8
9A working installation of CouchDB with corresponding source
10code. GeoCouch works best with Couchbase and the latest stable releases of
11CouchDB (should be >= 1.1.0).
12
13### Understanding the branches:
14
15This repository contains several branches, please make sure you use
16the correct one:
17
18 - master: works with Apache CouchDB 1.6.x and supports multidimensional indexing
19 - couchdb1.1.x: works with Apache CouchDB 1.1.x
20 - couchdb1.2.x: works with Apache CouchDB 1.2.x
21 - couchdb1.3.x: works with Apache CouchDB 1.3.x - 1.6.x
22
23
24Installation
25------------
26
27See the [main README](../README.md) for installtion instructions.
28
29
30Using GeoCouch
31--------------
32
33The following instruction refer to the newest version of GeoCouch which supports multidimensional indexing.
34
35Create a database:
36
37    curl -X PUT http://127.0.0.1:5984/places
38
39Add a Design Document with a spatial function:
40
41    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
42
43Put some data into it:
44
45    curl -X PUT -d '{"loc": [-122.270833, 37.804444]}' http://127.0.0.1:5984/places/oakland
46    curl -X PUT -d '{"loc": [10.898333, 48.371667]}' http://127.0.0.1:5984/places/augsburg
47
48Make a bounding box request:
49
50    curl -X GET --globoff 'http://localhost:5984/places/_design/main/_spatial/points?start_range=[0,0]&end_range=[180,90]'
51
52It should return:
53
54    {"id":"augsburg","key":[[10.89833299999999916,10.89833299999999916],[48.37166700000000219,48.37166700000000219]],"geometry":{"type":"Point","coordinates":[10.89833299999999916,48.37166700000000219]},"value":["augsburg",[10.89833299999999916,48.37166700000000219]]}
55
56
57The Design Document Function
58----------------------------
59
60function(doc) {
61    if (doc.loc) {
62        emit([{
63            type: "Point",
64            coordinates: [doc.loc[0], doc.loc[1]]
65        }], [doc._id, doc.loc]);
66    }};"
67
68It uses the emit() from normal views. The key is a
69[GeoJSON](http://geojson.org) geometry, the value is any arbitrary JSON. All
70geometry types (even GemetryCollections) are supported.
71
72If the GeoJSON geometry contains a `bbox` property it will be used instead
73of calculating it from the geometry (even if it's wrong, i.e. is not
74the actual bounding box).
75
76
77List function support
78---------------------
79
80GeoCouch supports List functions just as CouchDB does for Views. This way
81you can output any arbitrary format, e.g. GeoRSS.
82
83As an example we output the points as WKT. Add a new Design Document
84with an additional List function (the rest is the same as above). Make
85sure you use the right `_rev`:
86
87    curl -X PUT -d '{"_rev": "1-2a1d0e8c2d4ba3e64b9f6a9552d3d60f", "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
88
89Now you can request this List function as you would do for CouchDB,
90though with a different Design handler (`_spatial/_list` instead of
91`_list` ):
92
93    curl -X GET --globoff 'http://localhost:5984/places/_design/main/_spatial/_list/wkt/points?start_range=[-180,-90]&end_range=[180,90]'
94
95The result is:
96
97    POINT(10.898333 48.371667)
98    POINT(-122.270833 37.804444
99
100Using List functions from Design Documents other than the one containing the
101Spatial functions is supported as well. This time we add the Document
102ID in parenthesis:
103
104    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
105
106    curl -X GET --globoff 'http://localhost:5984/places/_design/listfunonly/_spatial/_list/wkt/main/points?start_range=[-180,-90]&end_range=[180,90]'
107
108The result is:
109
110    POINT(10.898333 48.371667) (augsburg)
111    POINT(-122.270833 37.804444) (oakland)
112
113
114Other supported query arguments
115-------------------------------
116
117### stale ###
118`stale=ok` is supported. The spatial index won't be rebuilt even if
119new Documents were added. It works for normal spatial queries as well
120as for the spatial List functions.
121
122### count ###
123`count` is a boolean. `count=true` will only return the number of geometries
124the query will return, not the geometry themselves.
125
126    curl -X GET --globoff 'http://localhost:5984/places/_design/main/_spatial/points?start_range=[0,0]&end_range=[180,90]&count=true'
127
128    {"count":1}
129
130### limit ###
131With `limit` you can limit the number of rows that should be returned.
132
133    curl -X GET --globoff 'http://localhost:5984/places/_design/main/_spatial/points?start_range=[-180,-90]&end_range=[180,90]&limit=1'
134
135    {"update_seq":3,"rows":[
136    {"id":"augsburg","key":[[10.89833299999999916,10.89833299999999916],[48.37166700000000219,48.37166700000000219]],"geometry":{"type":"Point","coordinates":[10.89833299999999916,48.37166700000000219]},"value":["augsburg",[10.89833299999999916,48.37166700000000219]]}
137    ]}
138
139### skip ###
140With `skip` you start to return the results at a certain offset.
141
142    curl -X GET --globoff 'http://localhost:5984/places/_design/main/_spatial/points?start_range=[-180,-90]&end_range=[180,90]&skip=1'
143
144    {"update_seq":3,"rows":[
145    {"id":"oakland","key":[[-122.2708329999999961,-122.2708329999999961],[37.804443999999996606,37.804443999999996606]],"geometry":{"type":"Point","coordinates":[-122.2708329999999961,37.804443999999996606]},"value":["oakland",[-122.2708329999999961,37.804443999999996606]]}
146    ]}
147
148
149Compaction, cleanup and info
150----------------------------
151
152The API of GeoCouch's spatial indexes is similar to the one for the
153Views. Compaction of spatial indexes is per Design Document, thus:
154
155    curl -X POST 'http://localhost:5984/places/_design/main/_spatial/_compact' -H 'Content-Type: application/json'
156
157To cleanup spatial indexes that are no longer in use (this is per database):
158
159    curl -X POST 'http://localhost:5984/places/_spatial_cleanup' -H 'Content-Type: application/json'
160
161To get information about the spatial indexes of a certain Design
162Document use the the `_info` handler:
163
164    curl -X GET 'http://localhost:5984/places/_design/main/_spatial/_info'
165