Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 549 lines (433 sloc) 17.801 kB
b9ba5b0 @rnewson warn against using 0.5 for now.
authored
1 <h1>WARNING</h1>
90790ae @rnewson add recommendation for 0.4 for now.
authored
2
ef3d4be @rnewson tentatively recommend 0.5 over 0.4
authored
3 0.5 is not yet released and may contain bugs and regressions. However, it is shaping up nicely so I recommend you try it first. 0.4 remains available if you hit insurmountable problems; but please take time to file a ticket at github if you do.
90790ae @rnewson add recommendation for 0.4 for now.
authored
4
6d1c074 @rnewson add notes about version compatibility.
authored
5 <h1>Version Compatibility</h1>
6
7 <table>
8 <tr><th>CouchDB</th><th>couchdb-lucene</th></tr>
9 <tr><td>0.9.1, 0.10</td><td>0.4</td></tr>
d90560d @rnewson update docs.
authored
10 <tr><td>0.11 (not yet released)</td><td>0.4-maint (0.4 with patch for trunk compatibility)</td></tr>
fc8e42c @rnewson add support for 0.10.x
authored
11 <tr><td>0.10+</td><td>0.5 (not yet released)</td></tr>
6d1c074 @rnewson add notes about version compatibility.
authored
12 </table>
13
c6356fd @rnewson update README.md and TODO to reflect progress.
authored
14 <h1>Issue Tracking</h1>
a785480 @rnewson lighthouse sucks at formatting anything, abandon ship.
authored
15
7a0d1d3 @rnewson lighthouse sucks at formatting anything, abandon ship.
authored
16 Issue tracking at <a href="http://github.com/rnewson/couchdb-lucene/issues">github</a>.
5d4e56a @rnewson update readme.
authored
17
7dc5bac @rnewson reorg begins.
authored
18 <h1>Minimum System Requirements</h1>
ef3f787 @rnewson add sysreq for Sun JDK.
authored
19
796a42b @rnewson jdk 5 compatibility for readme.
authored
20 Java 1.5 (or above) is required; the Sun version is recommended as it's regularly tested against.
ef3f787 @rnewson add sysreq for Sun JDK.
authored
21
5220b65 @rnewson tweak README.md
authored
22 <h1>Build couchdb-lucene</h1>
b207965 @rnewson improve README readability.
authored
23
24 <ol>
25 <li>Install Maven 2.
26 <li>checkout repository
27 <li>type 'mvn'
28 <li>configure couchdb (see below)
29 </ol>
30
2d6180b @rnewson include properties file in zip. still not available to run script, th…
authored
31 You will now have a zip file in the target/ directory. This contains all the couchdb-lucene code, dependencies, startup scripts and configuration files to run couchdb-lucene.
32
b207965 @rnewson improve README readability.
authored
33 <h1>Configure CouchDB</h1>
34
35 <pre>
0563120 @rnewson fixes.
authored
36 [couchdb]
37 os_process_timeout=60000 ; increase the timeout from 5 seconds.
38
b207965 @rnewson improve README readability.
authored
39 [external]
5675f7a @rnewson fix path
authored
40 fti=/path/to/python /path/to/couchdb-lucene/tools/couchdb-external-hook.py
b207965 @rnewson improve README readability.
authored
41
42 [httpd_db_handlers]
43 _fti = {couch_httpd_external, handle_external_req, <<"fti">>}
44 </pre>
45
cbfe065 @rnewson remove registry and indexkey, change output paths
authored
46 <h2>Hook options</h2>
47
48 <table>
49 <tr><th>Option</th><th>Meaning</th><th>Default Value</th></tr>
50 <tr><td>--remote-host</td><td>The hostname of the couchdb-lucene server</td><td>localhost</td></tr>
51 <tr><td>--remote-port</td><td>The port of the couchdb-lucene server</td><td>5985</td></tr>
c47c494 @rnewson updated README to reflect latest Python scripts settings
authored
52 <tr><td>--local-key</td><td>The key for the local couchdb instance as known to the couchdb-lucene server</td><td>local</td></tr>
cbfe065 @rnewson remove registry and indexkey, change output paths
authored
53 </table>
b047e4a @rnewson update README.md to reflect (future) start/stop and config changes.
authored
54
cbfe065 @rnewson remove registry and indexkey, change output paths
authored
55 <h1>Configure couchdb-lucene</h1>
b047e4a @rnewson update README.md to reflect (future) start/stop and config changes.
authored
56
cbfe065 @rnewson remove registry and indexkey, change output paths
authored
57 couchdb-lucene runs in a single, standalone JVM. As such, you can choose to locate your couchdb-lucene server on a different machine to couchdb if you wish, or keep it on the same machine, it's your call.
b047e4a @rnewson update README.md to reflect (future) start/stop and config changes.
authored
58
59 <h1>Start couchdb-lucene</h1>
60
61 To start couchdb-lucene, run;
62 <pre>
2d6180b @rnewson include properties file in zip. still not available to run script, th…
authored
63 bin/run
b047e4a @rnewson update README.md to reflect (future) start/stop and config changes.
authored
64 </pre>
65
2d6180b @rnewson include properties file in zip. still not available to run script, th…
authored
66 To stop couchdb-lucene, simply kill the Java process.
b047e4a @rnewson update README.md to reflect (future) start/stop and config changes.
authored
67
b207965 @rnewson improve README readability.
authored
68 <h1>Indexing Strategy</h1>
69
4a60080 @rnewson use couchdb's content_type rather than auto-detect.
authored
70 <h2>Document Indexing</h2>
71
4c21806 @rnewson mention that you can return Document[] from an index function.
authored
72 You must supply a index function in order to enable couchdb-lucene as, by default, nothing will be indexed. To suppress a document from the index, return null. It's more typical to return a single Document object which contains everything you'd like to query and retrieve. You may also return an array of Document objects if you wish.
a2e9024 @rnewson wip
authored
73
437eae9 @rnewson s/view/fulltext in README.md
authored
74 You may add any number of index views in any number of design documents. All searches will be constrained to documents emitted by the index functions.
c207a60 @rnewson update README
authored
75
5077366 @rnewson clarify design document and add matching query URL's.
authored
76 Here's an complete example of a design document with couchdb-lucene features:
a2e9024 @rnewson wip
authored
77
697884b @rnewson documentation of future features.
authored
78 <pre>
79 {
d1c9c80 @rnewson correct _id of first example.
authored
80 "_id":"_design/a_design_document_with_any_name_you_like",
5077366 @rnewson clarify design document and add matching query URL's.
authored
81 "fulltext": {
82 "by_subject": {
83 "index":"function(doc) { var ret=new Document(); ret.add(doc.subject); return ret }"
84 },
85 "by_content": {
86 "index":"function(doc) { var ret=new Document(); ret.add(doc.content); return ret }"
87 }
697884b @rnewson documentation of future features.
authored
88 }
89 }
90 </pre>
91
5077366 @rnewson clarify design document and add matching query URL's.
authored
92 Here are some example URL's for the given design document;
93
94 <pre>
95 http://localhost:5984/database/_fti/lucene/by_subject?q=hello
96 http://localhost:5984/database/_fti/lucene/by_content?q=hello
97 </pre>
98
697884b @rnewson documentation of future features.
authored
99 A fulltext object contains multiple index view declarations. An index view consists of;
100
101 <dl>
f420bf7 @rnewson support different Analyzer's at index and query time.
authored
102 <dt>analyzer</dt><dd>(optional) The analyzer to use</dd>
103 <dt>defaults</dt><dd>(optional) The default for numerous indexing options can be overridden here. A full list of options follows.</dd>
697884b @rnewson documentation of future features.
authored
104 <dt>index</dt><dd>The indexing function itself, documented below.</dd>
f420bf7 @rnewson support different Analyzer's at index and query time.
authored
105 </dl>
697884b @rnewson documentation of future features.
authored
106
107 <h3>The Defaults Object</h3>
108
109 The following indexing options can be defaulted;
110
111 <table>
112 <tr>
113 <th>name</th>
114 <th>description</th>
115 <th>available options</th>
116 <th>default</th>
117 </tr>
118 <tr>
a40523d @rnewson documentation of future features.
authored
119 <th>field</th>
120 <td>the field name to index under</td>
121 <td>user-defined</td>
122 <td>default</td>
d2e1e9e @rnewson add notes about typing.
authored
123 </tr>
124 <tr>
125 <th>type</th>
126 <td>the type of the field</td>
127 <td>date, double, float, integer, long, string</td>
128 <td>string</td>
129 </tr>
a40523d @rnewson documentation of future features.
authored
130 <tr>
697884b @rnewson documentation of future features.
authored
131 <th>store</th>
f16fc9c @rnewson docs
authored
132 <td>whether the data is stored. The value will be returned in the search result.</td>
697884b @rnewson documentation of future features.
authored
133 <td>yes, no</td>
134 <td>no</td>
d2e1e9e @rnewson add notes about typing.
authored
135 </tr>
697884b @rnewson documentation of future features.
authored
136 <tr>
137 <th>index</th>
138 <td>whether (and how) the data is indexed</td>
8328332 @rnewson typo
authored
139 <td>analyzed, analyzed_no_norms, no, not_analyzed, not_analyzed_no_norms</td>
697884b @rnewson documentation of future features.
authored
140 <td>analyzed</td>
d2e1e9e @rnewson add notes about typing.
authored
141 </tr>
697884b @rnewson documentation of future features.
authored
142 </table>
087dcec @rnewson update documentation.
authored
143
f420bf7 @rnewson support different Analyzer's at index and query time.
authored
144 <h3>The Analyzer Option</h3>
145
146 Lucene has numerous ways of converting free-form text into tokens, these classes are called Analyzer's. By default, the StandardAnalyzer is used which lower-cases all text, drops common English words ("the", "and", and so on), among other things. This processing might not always suit you, so you can choose from several others by setting the "analyzer" field to one of the following values;
147
148 <ul>
149 <li>brazilian</li>
150 <li>chinese</li>
151 <li>cjk</li>
152 <li>czech</li>
153 <li>dutch</li>
154 <li>english</li>
155 <li>french</li>
156 <li>german</li>
157 <li>keyword</li>
76d290d @rnewson add perfield analyzer support
authored
158 <li>perfield</li>
f420bf7 @rnewson support different Analyzer's at index and query time.
authored
159 <li>porter</li>
160 <li>russian</li>
161 <li>simple</li>
162 <li>standard</li>
163 <li>thai</li>
164 </ul>
165
76d290d @rnewson add perfield analyzer support
authored
166 The "perfield" option lets you use a different analyzer for different fields and is configured as follows;
167
168 <pre>
1325fd3 @rnewson more docs for perfield analyzer.
authored
169 ?analyzer=perfield:{field_name:"analyzer_name"}
76d290d @rnewson add perfield analyzer support
authored
170 </pre>
171
86569b1 @rnewson use 'default' consistently.
authored
172 Unless overridden, any field name not specified will be handled by the standard analyzer. To change the default, use the special default field name;
76d290d @rnewson add perfield analyzer support
authored
173
174 <pre>
1325fd3 @rnewson more docs for perfield analyzer.
authored
175 ?analyzer=perfield:{default:"keyword"}
176 </pre>
177
178 You should also specify the analyzer in your ddoc too;
179
180 <pre>
181 "fulltext": {
182 "idx": {
183 "analyzer": "perfield:{default:\"keyword\"}"
184 }
185 }
76d290d @rnewson add perfield analyzer support
authored
186 </pre>
187
087dcec @rnewson update documentation.
authored
188 <h3>The Document class</h3>
189
190 You may construct a new Document instance with;
191
192 <pre>
193 var doc = new Document();
194 </pre>
195
a40523d @rnewson documentation of future features.
authored
196 Data may be added to this document with the add method which takes an optional second object argument that can override any of the above default values.
087dcec @rnewson update documentation.
authored
197
198 <pre>
a40523d @rnewson documentation of future features.
authored
199 // Add with all the defaults.
200 doc.add("value");
201
d2e1e9e @rnewson add notes about typing.
authored
202 // Add a numeric field.
203 doc.add(35, {"type":"integer"});
204
4670582 @rnewson use NumericField. currently broken.
authored
205 // Add a date field.
206 doc.add(new Date("2009-01-01"), {"type":"date"});
207
d2e1e9e @rnewson add notes about typing.
authored
208 // Add a date field (object must be a Date object
209
a40523d @rnewson documentation of future features.
authored
210 // Add a subject field.
211 doc.add("this is the subject line.", {"field":"subject"});
9a71557 @rnewson formatting
authored
212
a40523d @rnewson documentation of future features.
authored
213 // Add but ensure it's stored.
214 doc.add("value", {"store":"yes"});
9a71557 @rnewson formatting
authored
215
a40523d @rnewson documentation of future features.
authored
216 // Add but don't analyze.
217 doc.add("don't analyze me", {"index":"not_analyzed"});
9a71557 @rnewson formatting
authored
218
219 // Extract text from the named attachment and index it (but not store it).
a40523d @rnewson documentation of future features.
authored
220 doc.attachment("attachment name", {"field":"attachments"});
087dcec @rnewson update documentation.
authored
221 </pre>
222
ccb81a8 @rnewson add example transforms section.
authored
223 <h3>Example Transforms</h3>
224
390858a @rnewson re-add Index Everything example.
authored
225 <h4>Index Everything</h4>
226
227 <pre>
228 function(doc) {
7bad7dc @rnewson correct syntax error in JS fun.
authored
229 var ret = new Document();
230
231 function idx(obj) {
232 for (var key in obj) {
233 switch (typeof obj[key]) {
234 case 'object':
235 idx(obj[key]);
236 break;
237 case 'function':
238 break;
239 default:
240 ret.add(obj[key]);
241 break;
242 }
243 }
244 };
245
246 idx(doc);
247
248 if (doc._attachments) {
249 for (var i in doc._attachments) {
250 ret.attachment("attachment", i);
251 }
390858a @rnewson re-add Index Everything example.
authored
252 }
d2e1e9e @rnewson add notes about typing.
authored
253
7bad7dc @rnewson correct syntax error in JS fun.
authored
254 return ret;
390858a @rnewson re-add Index Everything example.
authored
255 }
256 </pre>
257
ccb81a8 @rnewson add example transforms section.
authored
258 <h4>Index Nothing</h4>
259
260 <pre>
261 function(doc) {
262 return null;
263 }
264 </pre>
265
c207a60 @rnewson update README
authored
266 <h4>Index Select Fields</h4>
ccb81a8 @rnewson add example transforms section.
authored
267
268 <pre>
269 function(doc) {
c207a60 @rnewson update README
authored
270 var result = new Document();
c6356fd @rnewson update README.md and TODO to reflect progress.
authored
271 result.add(doc.subject, {"field":"subject", "store":"yes"});
272 result.add(doc.content, {"field":"subject"});
5cfa20c @rnewson fix error in example
authored
273 result.add(new Date(), {"field":"indexed_at"});
c207a60 @rnewson update README
authored
274 return result;
ccb81a8 @rnewson add example transforms section.
authored
275 }
276 </pre>
277
c207a60 @rnewson update README
authored
278 <h4>Index Attachments</h4>
ccb81a8 @rnewson add example transforms section.
authored
279
280 <pre>
281 function(doc) {
c207a60 @rnewson update README
authored
282 var result = new Document();
283 for(var a in doc._attachments) {
244df30 @rnewson fix mistake in README
authored
284 result.attachment(a, {"field":"attachment"});
ccb81a8 @rnewson add example transforms section.
authored
285 }
c207a60 @rnewson update README
authored
286 return result;
287 }
288 </pre>
289
290 <h4>A More Complex Example</h4>
291
292 <pre>
293 function(doc) {
294 var mk = function(name, value, group) {
c6356fd @rnewson update README.md and TODO to reflect progress.
authored
295 var ret = new Document();
2946c9a @rnewson fix example.
authored
296 ret.add(value, {"field": group, "store":"yes"});
c6356fd @rnewson update README.md and TODO to reflect progress.
authored
297 ret.add(group, {"field":"group", "store":"yes"});
c207a60 @rnewson update README
authored
298 return ret;
299 };
300 if(doc.type != "reference") return null;
a313b24 @rnewson lots of stuff.
authored
301 var ret = new Array();
c207a60 @rnewson update README
authored
302 for(var g in doc.groups) {
a313b24 @rnewson lots of stuff.
authored
303 ret.push(mk("library", doc.groups[g].library, g));
304 ret.push(mk("method", doc.groups[g].method, g));
305 ret.push(mk("target", doc.groups[g].target, g));
c207a60 @rnewson update README
authored
306 }
307 return ret;
308 }
309 </pre>
b207965 @rnewson improve README readability.
authored
310
4a60080 @rnewson use couchdb's content_type rather than auto-detect.
authored
311 <h2>Attachment Indexing</h2>
312
8059ce0 @rnewson s/couchdb/couchdb-lucene
authored
313 Couchdb-lucene uses <a href="http://lucene.apache.org/tika/">Apache Tika</a> to index attachments of the following types, assuming the correct content_type is set in couchdb;
4a60080 @rnewson use couchdb's content_type rather than auto-detect.
authored
314
ec94e21 @rnewson updated README.md
authored
315 <h3>Supported Formats</h3>
316
4a60080 @rnewson use couchdb's content_type rather than auto-detect.
authored
317 <ul>
318 <li>Excel spreadsheets (application/vnd.ms-excel)
319 <li>HTML (text/html)
320 <li>Images (image/*)
321 <li>Java class files
322 <li>Java jar archives
323 <li>MP3 (audio/mp3)
324 <li>OpenDocument (application/vnd.oasis.opendocument.*)
f420bf7 @rnewson support different Analyzer's at index and query time.
authored
325 <li>Outlook (application/vnd.ms-outlook)
4a60080 @rnewson use couchdb's content_type rather than auto-detect.
authored
326 <li>PDF (application/pdf)
f420bf7 @rnewson support different Analyzer's at index and query time.
authored
327 <li>Plain text (text/plain)
328 <li>Powerpoint presentations (application/vnd.ms-powerpoint)
4a60080 @rnewson use couchdb's content_type rather than auto-detect.
authored
329 <li>RTF (application/rtf)
f420bf7 @rnewson support different Analyzer's at index and query time.
authored
330 <li>Visio (application/vnd.visio)
331 <li>Word documents (application/msword)
332 <li>XML (application/xml)
4a60080 @rnewson use couchdb's content_type rather than auto-detect.
authored
333 </ul>
334
b207965 @rnewson improve README readability.
authored
335 <h1>Searching with couchdb-lucene</h1>
336
2b14b76 @rnewson describ syntax for all forms of numeric range query
authored
337 You can perform all types of queries using Lucene's default <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">query syntax</a>.
338
339 <h2>Numeric range queries</h2>
340
bf989bc @rnewson make type of range query explicit.
authored
341 In addition to normal text-based range searches (using the "field:[lower TO upper]" syntax), couchdb-lucene all supports numeric range searches for the following types: int, long, float, double and date. The type is specified after the field name, as follows;
2b14b76 @rnewson describ syntax for all forms of numeric range query
authored
342
343 <table>
bf989bc @rnewson make type of range query explicit.
authored
344 <tr><td>type</td><td>example</td></tr>
20c9be3 @rnewson update docs on numeric range queries
authored
345 <tr><td>integer</td><td>field&lt;int>:[0 TO 100]</td></tr>
346 <tr><td>long</td><td>field&lt;long>:[0 TO 100]</td></tr>
347 <tr><td>float</td><td>field&lt;float>:[0.0 TO 100.0]</td></tr>
348 <tr><td>double</td><td>field&lt;double>:[0.0 TO 100.0]</td></tr>
349 <tr><td>date</td><td>field&lt;date>:[2001-01-01 TO 2010-01-01] or field&lt;date>:[2000-01-01T00:00:00-0500 TO 2010-01-01T00:00:00-0500]</td></tr>
2b14b76 @rnewson describ syntax for all forms of numeric range query
authored
350 </table>
351
460f5c6 @rnewson add example spatial/geographical query
authored
352 An example numeric range query for spatial searching.
353
354 <pre>
1217f9f @rnewson update docs on numeric range queries
authored
355 ?q=pizza AND lat&lt;double>:[51.4707 TO 51.5224] AND long&lt;double>:[-0.6622 TO -0.5775]
460f5c6 @rnewson add example spatial/geographical query
authored
356 </pre>
357
2b14b76 @rnewson describ syntax for all forms of numeric range query
authored
358 The following parameters can be passed for more sophisticated searches;
b207965 @rnewson improve README readability.
authored
359
360 <dl>
f420bf7 @rnewson support different Analyzer's at index and query time.
authored
361 <dt>callback</dt><dd>Specify a JSONP callback wrapper. The full JSON result will be prepended with this parameter and also placed with parentheses."
71cbc0b @rnewson correct description of debug setting.
authored
362 <dt>debug</dt><dd>Setting this to true disables response caching (the query is executed every time) and indents the JSON response for readability.</dd>
ea19e55 @rnewson add force_json=true to force 'application/json' response type.
authored
363 <dt>force_json<dt><dd>Usually couchdb-lucene determines the Content-Type of its response based on the presence of the Accept header. If Accept contains "application/json", you get "application/json" in the response, otherwise you get "text/plain;charset=utf8". Some tools, like JSONView for FireFox, do not send the Accept header but do render "application/json" responses if received. Setting force_json=true forces all response to "application/json" regardless of the Accept header.</dd>
f420bf7 @rnewson support different Analyzer's at index and query time.
authored
364 <dt>include_docs</dt><dd>whether to include the source docs</dd>
f9c61e3 @rnewson format README
authored
365 <dt>limit</dt><dd>the maximum number of results to return</dd>
766d874 @rnewson support multiple q parameters in one call.
authored
366 <dt>q</dt><dd>the query to run (e.g, subject:hello). If not specified, the default field is searched. Multiple q parameters are permitted, the resulting JSON will be an array of responses.</dd>
f9c61e3 @rnewson format README
authored
367 <dt>skip</dt><dd>the number of results to skip</dd>
8f30f2d @rnewson make typed sort the same syntax as typed range search.
authored
368 <dt>sort</dt><dd>the comma-separated fields to sort on. Prefix with / for ascending order and \ for descending order (ascending is the default if not specified). Type-specific sorting is also available by appending the type between angle brackets (e.g, 'sort=amount<float>'). Supported types are 'float', 'double', 'int', 'long' and 'date'.</dd>
637279a @rnewson fix grammar in readme.
authored
369 <dt>stale=ok</dt><dd>If you set the <i>stale</i> option to <i>ok</i>, couchdb-lucene may not perform any refreshing on the index. Searches may be faster as Lucene caches important data (especially for sorting). A query without stale=ok will use the latest data committed to the index.</dd>
ad9096f @rnewson tweak README.md
authored
370 </dl>
b207965 @rnewson improve README readability.
authored
371
372 <i>All parameters except 'q' are optional.</i>
373
ec94e21 @rnewson updated README.md
authored
374 <h2>Special Fields</h2>
375
376 <dl>
087dcec @rnewson update documentation.
authored
377 <dt>_id</dt><dd>The _id of the document.</dd>
46a3a37 @rnewson include all DC attributes, if present.
authored
378 </dl>
379
380 <h2>Dublin Core</h2>
381
382 All Dublin Core attributes are indexed and stored if detected in the attachment. Descriptions of the fields come from the Tika javadocs.
383
384 <dl>
6e99faa @rnewson dc. to _dc.
authored
385 <dt>_dc.contributor</dt><dd> An entity responsible for making contributions to the content of the resource.</dd>
386 <dt>_dc.coverage</dt><dd>The extent or scope of the content of the resource.</dd>
387 <dt>_dc.creator</dt><dd>An entity primarily responsible for making the content of the resource.</dd>
388 <dt>_dc.date</dt><dd>A date associated with an event in the life cycle of the resource.</dd>
389 <dt>_dc.description</dt><dd>An account of the content of the resource.</dd>
390 <dt>_dc.format</dt><dd>Typically, Format may include the media-type or dimensions of the resource.</dd>
391 <dt>_dc.identifier</dt><dd>Recommended best practice is to identify the resource by means of a string or number conforming to a formal identification system.</dd>
392 <dt>_dc.language</dt><dd>A language of the intellectual content of the resource.</dd>
393 <dt>_dc.modified</dt><dd>Date on which the resource was changed.</dd>
394 <dt>_dc.publisher</dt><dd>An entity responsible for making the resource available.</dd>
395 <dt>_dc.relation</dt><dd>A reference to a related resource.</dd>
396 <dt>_dc.rights</dt><dd>Information about rights held in and over the resource.</dd>
397 <dt>_dc.source</dt><dd>A reference to a resource from which the present resource is derived.</dd>
398 <dt>_dc.subject</dt><dd>The topic of the content of the resource.</dd>
399 <dt>_dc.title</dt><dd>A name given to the resource.</dd>
400 <dt>_dc.type</dt><dd>The nature or genre of the content of the resource.</dd>
ec94e21 @rnewson updated README.md
authored
401 </dl>
402
b207965 @rnewson improve README readability.
authored
403 <h2>Examples</h2>
404
405 <pre>
405e3a3 @rnewson update query urls' to reflect new syntax
authored
406 http://localhost:5984/dbname/_fti/design_doc/view_name?q=field_name:value
407 http://localhost:5984/dbname/_fti/design_doc/view_name?q=field_name:value&sort=other_field
408 http://localhost:5984/dbname/_fti/design_doc/view_name?debug=true&sort=billing_size&q=body:document AND customer:[A TO C]
b207965 @rnewson improve README readability.
authored
409 </pre>
410
411 <h2>Search Results Format</h2>
412
0fcf578 @rnewson update docs.
authored
413 The search result contains a number of fields at the top level, in addition to your search results.
414
415 <dl>
416 <dt>etag</dt><dd>An opaque token that reflects the current version of the index. This value is also returned in an ETag header to facilitate HTTP caching.</dd>
417 <dt>fetch_duration</dt><dd>The number of milliseconds spent retrieving the documents.</dd>
f420bf7 @rnewson support different Analyzer's at index and query time.
authored
418 <dt>limit</dt><dd>The maximum number of results that can appear.</dd>
419 <dt>q</dt><dd>The query that was executed.</dd>
24591d9 @rnewson docs
authored
420 <dt>rows</dt><dd>The search results array, described below.</dd>
f420bf7 @rnewson support different Analyzer's at index and query time.
authored
421 <dt>search_duration</dt><dd>The number of milliseconds spent performing the search.</dd>
422 <dt>skip</dt><dd>The number of initial matches that was skipped.</dd>
423 <dt>total_rows</dt><dd>The total number of matches for this query.</dd>
0fcf578 @rnewson update docs.
authored
424 </dl>
425
24591d9 @rnewson docs
authored
426 <h2>The search results array</h2>
427
428 The search results arrays consists of zero, one or more objects with the following fields;
0fcf578 @rnewson update docs.
authored
429
430 <dl>
f420bf7 @rnewson support different Analyzer's at index and query time.
authored
431 <dt>doc</dt><dd>The original document from couch, if requested with include_docs=true</dd>
432 <dt>fields</dt><dd>All the fields that were stored with this match</dd>
0fcf578 @rnewson update docs.
authored
433 <dt>id</dt><dd>The unique identifier for this match.</dd>
434 <dt>score</dt><dd>The normalized score (0.0-1.0, inclusive) for this match</dd>
435 </dl>
436
fd16315 @rnewson update README.md
authored
437 Here's an example of a JSON response without sorting;
b207965 @rnewson improve README readability.
authored
438
118d28e @rnewson JSON example output.
authored
439 <pre>
440 {
c6356fd @rnewson update README.md and TODO to reflect progress.
authored
441 "q": "+content:enron",
fd16315 @rnewson update README.md
authored
442 "skip": 0,
443 "limit": 2,
444 "total_rows": 176852,
445 "search_duration": 518,
446 "fetch_duration": 4,
447 "rows": [
448 {
0fcf578 @rnewson update docs.
authored
449 "id": "hain-m-all_documents-257.",
fd16315 @rnewson update README.md
authored
450 "score": 1.601625680923462
451 },
452 {
0fcf578 @rnewson update docs.
authored
453 "id": "hain-m-notes_inbox-257.",
fd16315 @rnewson update README.md
authored
454 "score": 1.601625680923462
455 }
118d28e @rnewson JSON example output.
authored
456 ]
457 }
458 </pre>
459
fd16315 @rnewson update README.md
authored
460 And the same with sorting;
461
118d28e @rnewson JSON example output.
authored
462 <pre>
463 {
0fcf578 @rnewson update docs.
authored
464 "q": "+content:enron",
fd16315 @rnewson update README.md
authored
465 "skip": 0,
466 "limit": 3,
467 "total_rows": 176852,
468 "search_duration": 660,
469 "fetch_duration": 4,
470 "sort_order": [
471 {
472 "field": "source",
473 "reverse": false,
474 "type": "string"
475 },
476 {
477 "reverse": false,
478 "type": "doc"
479 }
118d28e @rnewson JSON example output.
authored
480 ],
fd16315 @rnewson update README.md
authored
481 "rows": [
482 {
0fcf578 @rnewson update docs.
authored
483 "id": "shankman-j-inbox-105.",
fd16315 @rnewson update README.md
authored
484 "score": 0.6131107211112976,
485 "sort_order": [
486 "enron",
487 6
488 ]
489 },
490 {
0fcf578 @rnewson update docs.
authored
491 "id": "shankman-j-inbox-8.",
fd16315 @rnewson update README.md
authored
492 "score": 0.7492915391921997,
493 "sort_order": [
494 "enron",
495 7
496 ]
497 },
498 {
0fcf578 @rnewson update docs.
authored
499 "id": "shankman-j-inbox-30.",
fd16315 @rnewson update README.md
authored
500 "score": 0.507369875907898,
501 "sort_order": [
502 "enron",
503 8
504 ]
505 }
118d28e @rnewson JSON example output.
authored
506 ]
507 }
508 </pre>
509
a4aa4e1 @rnewson document Content-Type response negotiation
authored
510 <h3>Content-Type of response</h3>
511
d2e1e9e @rnewson add notes about typing.
authored
512 The Content-Type of the response is negotiated via the Accept request header like CouchDB itself. If the Accept header includes "application/json" then that is also the Content-Type of the response. If not, "text/plain;charset=utf-8" is used.
a4aa4e1 @rnewson document Content-Type response negotiation
authored
513
139a78c @rnewson add info retrieval.
authored
514 <h1>Fetching information about the index</h1>
515
0cf4941 @rnewson correct info urls.
authored
516 Calling couchdb-lucene without arguments returns a JSON object with information about the index.
139a78c @rnewson add info retrieval.
authored
517
518 <pre>
0cf4941 @rnewson correct info urls.
authored
519 http://127.0.0.1:5984/&lt;db>/_fti/&lt;ddoc>/&lt;index
139a78c @rnewson add info retrieval.
authored
520 </pre>
521
522 returns;
523
524 <pre>
f6ac048 @rnewson line breaks
authored
525 {"current":true,"disk_size":110674,"doc_count":397,"doc_del_count":0,
526 "fields":["default","number"],"last_modified":"1263066382000",
527 "optimized":true,"ref_count":2}
139a78c @rnewson add info retrieval.
authored
528 </pre>
8203af6 @rnewson support _optimize and _expunge calls.
authored
529
530 <h1>Index Maintenance</h1>
531
532 For optimal query speed you can optimize your indexes. This causes the index to be rewritten into a single segment.
533
534 <pre>
b4616fb @rnewson support _optimize and _expunge calls. (fix documentation)
authored
535 curl -X POST http://localhost:5984/&lt;db>/_fti/&lt;ddoc>/&lt;index>/_optimize
8203af6 @rnewson support _optimize and _expunge calls.
authored
536 </pre>
537
538 If you just want to expunge pending deletes, then call;
539
540 <pre>
b4616fb @rnewson support _optimize and _expunge calls. (fix documentation)
authored
541 curl -X POST http://localhost:5984/&lt;db>/_fti/&lt;ddoc>/&lt;index>/_expunge
8203af6 @rnewson support _optimize and _expunge calls.
authored
542 </pre>
6e66766 @rnewson most of index cleanup work
authored
543
544 If you recreate databases or frequently change your fulltext functions, you will probably have old indexes lying around on disk. To remove all of them, call;
545
546 <pre>
547 curl -X POST http://localhost:5984/&lt;db>/_fti/_cleanup
548 </pre>
Something went wrong with that request. Please try again.