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