Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 544 lines (429 sloc) 17.737 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, thoug...
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>
52 <tr><td>--local-host</td><td>The hostname of the couchdb server</td><td>localhost</td></tr>
53 <tr><td>--local-port</td><td>The port of the couchdb server</td><td>5984</td></tr>
54 </table>
b047e4a @rnewson update README.md to reflect (future) start/stop and config changes.
authored
55
cbfe065 @rnewson remove registry and indexkey, change output paths
authored
56 <h1>Configure couchdb-lucene</h1>
b047e4a @rnewson update README.md to reflect (future) start/stop and config changes.
authored
57
cbfe065 @rnewson remove registry and indexkey, change output paths
authored
58 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
59
60 <h1>Start couchdb-lucene</h1>
61
62 To start couchdb-lucene, run;
63 <pre>
2d6180b @rnewson include properties file in zip. still not available to run script, thoug...
authored
64 bin/run
b047e4a @rnewson update README.md to reflect (future) start/stop and config changes.
authored
65 </pre>
66
2d6180b @rnewson include properties file in zip. still not available to run script, thoug...
authored
67 To stop couchdb-lucene, simply kill the Java process.
b047e4a @rnewson update README.md to reflect (future) start/stop and config changes.
authored
68
b207965 @rnewson improve README readability.
authored
69 <h1>Indexing Strategy</h1>
70
4a60080 @rnewson use couchdb's content_type rather than auto-detect.
authored
71 <h2>Document Indexing</h2>
72
4c21806 @rnewson mention that you can return Document[] from an index function.
authored
73 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
74
437eae9 @rnewson s/view/fulltext in README.md
authored
75 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
76
5077366 @rnewson clarify design document and add matching query URL's.
authored
77 Here's an complete example of a design document with couchdb-lucene features:
a2e9024 @rnewson wip
authored
78
697884b @rnewson documentation of future features.
authored
79 <pre>
80 {
d1c9c80 @rnewson correct _id of first example.
authored
81 "_id":"_design/a_design_document_with_any_name_you_like",
5077366 @rnewson clarify design document and add matching query URL's.
authored
82 "fulltext": {
83 "by_subject": {
84 "index":"function(doc) { var ret=new Document(); ret.add(doc.subject); return ret }"
85 },
86 "by_content": {
87 "index":"function(doc) { var ret=new Document(); ret.add(doc.content); return ret }"
88 }
697884b @rnewson documentation of future features.
authored
89 }
90 }
91 </pre>
92
5077366 @rnewson clarify design document and add matching query URL's.
authored
93 Here are some example URL's for the given design document;
94
95 <pre>
96 http://localhost:5984/database/_fti/lucene/by_subject?q=hello
97 http://localhost:5984/database/_fti/lucene/by_content?q=hello
98 </pre>
99
697884b @rnewson documentation of future features.
authored
100 A fulltext object contains multiple index view declarations. An index view consists of;
101
102 <dl>
f420bf7 @rnewson support different Analyzer's at index and query time.
authored
103 <dt>analyzer</dt><dd>(optional) The analyzer to use</dd>
104 <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
105 <dt>index</dt><dd>The indexing function itself, documented below.</dd>
f420bf7 @rnewson support different Analyzer's at index and query time.
authored
106 </dl>
697884b @rnewson documentation of future features.
authored
107
108 <h3>The Defaults Object</h3>
109
110 The following indexing options can be defaulted;
111
112 <table>
113 <tr>
114 <th>name</th>
115 <th>description</th>
116 <th>available options</th>
117 <th>default</th>
118 </tr>
119 <tr>
a40523d @rnewson documentation of future features.
authored
120 <th>field</th>
121 <td>the field name to index under</td>
122 <td>user-defined</td>
123 <td>default</td>
d2e1e9e @rnewson add notes about typing.
authored
124 </tr>
125 <tr>
126 <th>type</th>
127 <td>the type of the field</td>
128 <td>date, double, float, integer, long, string</td>
129 <td>string</td>
130 </tr>
a40523d @rnewson documentation of future features.
authored
131 <tr>
697884b @rnewson documentation of future features.
authored
132 <th>store</th>
f16fc9c @rnewson docs
authored
133 <td>whether the data is stored. The value will be returned in the search result.</td>
697884b @rnewson documentation of future features.
authored
134 <td>yes, no</td>
135 <td>no</td>
d2e1e9e @rnewson add notes about typing.
authored
136 </tr>
697884b @rnewson documentation of future features.
authored
137 <tr>
138 <th>index</th>
139 <td>whether (and how) the data is indexed</td>
8328332 @rnewson typo
authored
140 <td>analyzed, analyzed_no_norms, no, not_analyzed, not_analyzed_no_norms</td>
697884b @rnewson documentation of future features.
authored
141 <td>analyzed</td>
d2e1e9e @rnewson add notes about typing.
authored
142 </tr>
697884b @rnewson documentation of future features.
authored
143 </table>
087dcec @rnewson update documentation.
authored
144
f420bf7 @rnewson support different Analyzer's at index and query time.
authored
145 <h3>The Analyzer Option</h3>
146
147 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;
148
149 <ul>
150 <li>brazilian</li>
151 <li>chinese</li>
152 <li>cjk</li>
153 <li>czech</li>
154 <li>dutch</li>
155 <li>english</li>
156 <li>french</li>
157 <li>german</li>
158 <li>keyword</li>
76d290d @rnewson add perfield analyzer support
authored
159 <li>perfield</li>
f420bf7 @rnewson support different Analyzer's at index and query time.
authored
160 <li>porter</li>
161 <li>russian</li>
162 <li>simple</li>
163 <li>standard</li>
164 <li>thai</li>
165 </ul>
166
76d290d @rnewson add perfield analyzer support
authored
167 The "perfield" option lets you use a different analyzer for different fields and is configured as follows;
168
169 <pre>
1325fd3 @rnewson more docs for perfield analyzer.
authored
170 ?analyzer=perfield:{field_name:"analyzer_name"}
76d290d @rnewson add perfield analyzer support
authored
171 </pre>
172
86569b1 @rnewson use 'default' consistently.
authored
173 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
174
175 <pre>
1325fd3 @rnewson more docs for perfield analyzer.
authored
176 ?analyzer=perfield:{default:"keyword"}
177 </pre>
178
179 You should also specify the analyzer in your ddoc too;
180
181 <pre>
182 "fulltext": {
183 "idx": {
184 "analyzer": "perfield:{default:\"keyword\"}"
185 }
186 }
76d290d @rnewson add perfield analyzer support
authored
187 </pre>
188
087dcec @rnewson update documentation.
authored
189 <h3>The Document class</h3>
190
191 You may construct a new Document instance with;
192
193 <pre>
194 var doc = new Document();
195 </pre>
196
a40523d @rnewson documentation of future features.
authored
197 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
198
199 <pre>
a40523d @rnewson documentation of future features.
authored
200 // Add with all the defaults.
201 doc.add("value");
202
d2e1e9e @rnewson add notes about typing.
authored
203 // Add a numeric field.
204 doc.add(35, {"type":"integer"});
205
4670582 @rnewson use NumericField. currently broken.
authored
206 // Add a date field.
207 doc.add(new Date("2009-01-01"), {"type":"date"});
208
d2e1e9e @rnewson add notes about typing.
authored
209 // Add a date field (object must be a Date object
210
a40523d @rnewson documentation of future features.
authored
211 // Add a subject field.
212 doc.add("this is the subject line.", {"field":"subject"});
9a71557 @rnewson formatting
authored
213
a40523d @rnewson documentation of future features.
authored
214 // Add but ensure it's stored.
215 doc.add("value", {"store":"yes"});
9a71557 @rnewson formatting
authored
216
a40523d @rnewson documentation of future features.
authored
217 // Add but don't analyze.
218 doc.add("don't analyze me", {"index":"not_analyzed"});
9a71557 @rnewson formatting
authored
219
220 // Extract text from the named attachment and index it (but not store it).
a40523d @rnewson documentation of future features.
authored
221 doc.attachment("attachment name", {"field":"attachments"});
087dcec @rnewson update documentation.
authored
222 </pre>
223
ccb81a8 @rnewson add example transforms section.
authored
224 <h3>Example Transforms</h3>
225
390858a @rnewson re-add Index Everything example.
authored
226 <h4>Index Everything</h4>
227
228 <pre>
229 function(doc) {
7bad7dc @rnewson correct syntax error in JS fun.
authored
230 var ret = new Document();
231
232 function idx(obj) {
233 for (var key in obj) {
234 switch (typeof obj[key]) {
235 case 'object':
236 idx(obj[key]);
237 break;
238 case 'function':
239 break;
240 default:
241 ret.add(obj[key]);
242 break;
243 }
244 }
245 };
246
247 idx(doc);
248
249 if (doc._attachments) {
250 for (var i in doc._attachments) {
251 ret.attachment("attachment", i);
252 }
390858a @rnewson re-add Index Everything example.
authored
253 }
d2e1e9e @rnewson add notes about typing.
authored
254
7bad7dc @rnewson correct syntax error in JS fun.
authored
255 return ret;
390858a @rnewson re-add Index Everything example.
authored
256 }
257 </pre>
258
ccb81a8 @rnewson add example transforms section.
authored
259 <h4>Index Nothing</h4>
260
261 <pre>
262 function(doc) {
263 return null;
264 }
265 </pre>
266
c207a60 @rnewson update README
authored
267 <h4>Index Select Fields</h4>
ccb81a8 @rnewson add example transforms section.
authored
268
269 <pre>
270 function(doc) {
c207a60 @rnewson update README
authored
271 var result = new Document();
c6356fd @rnewson update README.md and TODO to reflect progress.
authored
272 result.add(doc.subject, {"field":"subject", "store":"yes"});
273 result.add(doc.content, {"field":"subject"});
5cfa20c @rnewson fix error in example
authored
274 result.add(new Date(), {"field":"indexed_at"});
c207a60 @rnewson update README
authored
275 return result;
ccb81a8 @rnewson add example transforms section.
authored
276 }
277 </pre>
278
c207a60 @rnewson update README
authored
279 <h4>Index Attachments</h4>
ccb81a8 @rnewson add example transforms section.
authored
280
281 <pre>
282 function(doc) {
c207a60 @rnewson update README
authored
283 var result = new Document();
284 for(var a in doc._attachments) {
244df30 @rnewson fix mistake in README
authored
285 result.attachment(a, {"field":"attachment"});
ccb81a8 @rnewson add example transforms section.
authored
286 }
c207a60 @rnewson update README
authored
287 return result;
288 }
289 </pre>
290
291 <h4>A More Complex Example</h4>
292
293 <pre>
294 function(doc) {
295 var mk = function(name, value, group) {
c6356fd @rnewson update README.md and TODO to reflect progress.
authored
296 var ret = new Document();
2946c9a @rnewson fix example.
authored
297 ret.add(value, {"field": group, "store":"yes"});
c6356fd @rnewson update README.md and TODO to reflect progress.
authored
298 ret.add(group, {"field":"group", "store":"yes"});
c207a60 @rnewson update README
authored
299 return ret;
300 };
301 if(doc.type != "reference") return null;
a313b24 @rnewson lots of stuff.
authored
302 var ret = new Array();
c207a60 @rnewson update README
authored
303 for(var g in doc.groups) {
a313b24 @rnewson lots of stuff.
authored
304 ret.push(mk("library", doc.groups[g].library, g));
305 ret.push(mk("method", doc.groups[g].method, g));
306 ret.push(mk("target", doc.groups[g].target, g));
c207a60 @rnewson update README
authored
307 }
308 return ret;
309 }
310 </pre>
b207965 @rnewson improve README readability.
authored
311
4a60080 @rnewson use couchdb's content_type rather than auto-detect.
authored
312 <h2>Attachment Indexing</h2>
313
8059ce0 @rnewson s/couchdb/couchdb-lucene
authored
314 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
315
ec94e21 @rnewson updated README.md
authored
316 <h3>Supported Formats</h3>
317
4a60080 @rnewson use couchdb's content_type rather than auto-detect.
authored
318 <ul>
319 <li>Excel spreadsheets (application/vnd.ms-excel)
320 <li>HTML (text/html)
321 <li>Images (image/*)
322 <li>Java class files
323 <li>Java jar archives
324 <li>MP3 (audio/mp3)
325 <li>OpenDocument (application/vnd.oasis.opendocument.*)
f420bf7 @rnewson support different Analyzer's at index and query time.
authored
326 <li>Outlook (application/vnd.ms-outlook)
4a60080 @rnewson use couchdb's content_type rather than auto-detect.
authored
327 <li>PDF (application/pdf)
f420bf7 @rnewson support different Analyzer's at index and query time.
authored
328 <li>Plain text (text/plain)
329 <li>Powerpoint presentations (application/vnd.ms-powerpoint)
4a60080 @rnewson use couchdb's content_type rather than auto-detect.
authored
330 <li>RTF (application/rtf)
f420bf7 @rnewson support different Analyzer's at index and query time.
authored
331 <li>Visio (application/vnd.visio)
332 <li>Word documents (application/msword)
333 <li>XML (application/xml)
4a60080 @rnewson use couchdb's content_type rather than auto-detect.
authored
334 </ul>
335
b207965 @rnewson improve README readability.
authored
336 <h1>Searching with couchdb-lucene</h1>
337
2b14b76 @rnewson describ syntax for all forms of numeric range query
authored
338 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>.
339
340 <h2>Numeric range queries</h2>
341
342 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: integer, long, float, double and date. The type is automatically derived from the search terms used, as follows;
343
344 <table>
345 <tr><td>type</td><td>format</td><td>example</td></tr>
346 <tr><td>integer</td><td>[0-9]+</td><td>[0 TO 100]</td></tr>
347 <tr><td>long</td><td>[0-9]+L</td><td>[0L TO 100L]</td></tr>
348 <tr><td>float</td><td>[0-9]+.[0-9]+f</td><td>[0.0f TO 100.0f]</td></tr>
349 <tr><td>double</td><td>[0-9]+.[0-9]+</td><td>[0.0 TO 100.0]</td></tr>
350 <tr><td>date</td><td>yyyy-MM-dd or yyyy-MM-ddZZ or yyyy-MM-dd'T'HH:mm:ss or yyyy-MM-dd'T'HH:mm:ssZZ</td><td>2001-01-01 or 2001-01-01-0500 or 2000-01-01T00:00:00 or 2000-01-01T00:00:00-0500</td></tr>
351 </table>
352
353 Both the upper and lower bound must be of the same type to trigger numeric range searching. If they don't match, then a normal text-based range search is performed.
354
460f5c6 @rnewson add example spatial/geographical query
authored
355 An example numeric range query for spatial searching.
356
357 <pre>
358 ?q=pizza AND lat:[51.4707 TO 51.5224] AND long:[-0.6622 TO -0.5775]
359 </pre>
360
2b14b76 @rnewson describ syntax for all forms of numeric range query
authored
361 The following parameters can be passed for more sophisticated searches;
b207965 @rnewson improve README readability.
authored
362
363 <dl>
f420bf7 @rnewson support different Analyzer's at index and query time.
authored
364 <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
365 <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
366 <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
367 <dt>include_docs</dt><dd>whether to include the source docs</dd>
f9c61e3 @rnewson format README
authored
368 <dt>limit</dt><dd>the maximum number of results to return</dd>
766d874 @rnewson support multiple q parameters in one call.
authored
369 <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
370 <dt>skip</dt><dd>the number of results to skip</dd>
fa0e48f @rnewson add docs for numeric sorting too.
authored
371 <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 a : and the sort type as normal (e.g, 'sort=amount:float'). Supported types are 'float', 'double', 'int', 'long' and 'date'.</dd>
637279a @rnewson fix grammar in readme.
authored
372 <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
373 </dl>
b207965 @rnewson improve README readability.
authored
374
375 <i>All parameters except 'q' are optional.</i>
376
ec94e21 @rnewson updated README.md
authored
377 <h2>Special Fields</h2>
378
379 <dl>
087dcec @rnewson update documentation.
authored
380 <dt>_id</dt><dd>The _id of the document.</dd>
46a3a37 @rnewson include all DC attributes, if present.
authored
381 </dl>
382
383 <h2>Dublin Core</h2>
384
385 All Dublin Core attributes are indexed and stored if detected in the attachment. Descriptions of the fields come from the Tika javadocs.
386
387 <dl>
6e99faa @rnewson dc. to _dc.
authored
388 <dt>_dc.contributor</dt><dd> An entity responsible for making contributions to the content of the resource.</dd>
389 <dt>_dc.coverage</dt><dd>The extent or scope of the content of the resource.</dd>
390 <dt>_dc.creator</dt><dd>An entity primarily responsible for making the content of the resource.</dd>
391 <dt>_dc.date</dt><dd>A date associated with an event in the life cycle of the resource.</dd>
392 <dt>_dc.description</dt><dd>An account of the content of the resource.</dd>
393 <dt>_dc.format</dt><dd>Typically, Format may include the media-type or dimensions of the resource.</dd>
394 <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>
395 <dt>_dc.language</dt><dd>A language of the intellectual content of the resource.</dd>
396 <dt>_dc.modified</dt><dd>Date on which the resource was changed.</dd>
397 <dt>_dc.publisher</dt><dd>An entity responsible for making the resource available.</dd>
398 <dt>_dc.relation</dt><dd>A reference to a related resource.</dd>
399 <dt>_dc.rights</dt><dd>Information about rights held in and over the resource.</dd>
400 <dt>_dc.source</dt><dd>A reference to a resource from which the present resource is derived.</dd>
401 <dt>_dc.subject</dt><dd>The topic of the content of the resource.</dd>
402 <dt>_dc.title</dt><dd>A name given to the resource.</dd>
403 <dt>_dc.type</dt><dd>The nature or genre of the content of the resource.</dd>
ec94e21 @rnewson updated README.md
authored
404 </dl>
405
b207965 @rnewson improve README readability.
authored
406 <h2>Examples</h2>
407
408 <pre>
405e3a3 @rnewson update query urls' to reflect new syntax
authored
409 http://localhost:5984/dbname/_fti/design_doc/view_name?q=field_name:value
410 http://localhost:5984/dbname/_fti/design_doc/view_name?q=field_name:value&sort=other_field
411 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
412 </pre>
413
414 <h2>Search Results Format</h2>
415
0fcf578 @rnewson update docs.
authored
416 The search result contains a number of fields at the top level, in addition to your search results.
417
418 <dl>
419 <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>
420 <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
421 <dt>limit</dt><dd>The maximum number of results that can appear.</dd>
422 <dt>q</dt><dd>The query that was executed.</dd>
24591d9 @rnewson docs
authored
423 <dt>rows</dt><dd>The search results array, described below.</dd>
f420bf7 @rnewson support different Analyzer's at index and query time.
authored
424 <dt>search_duration</dt><dd>The number of milliseconds spent performing the search.</dd>
425 <dt>skip</dt><dd>The number of initial matches that was skipped.</dd>
426 <dt>total_rows</dt><dd>The total number of matches for this query.</dd>
0fcf578 @rnewson update docs.
authored
427 </dl>
428
24591d9 @rnewson docs
authored
429 <h2>The search results array</h2>
430
431 The search results arrays consists of zero, one or more objects with the following fields;
0fcf578 @rnewson update docs.
authored
432
433 <dl>
f420bf7 @rnewson support different Analyzer's at index and query time.
authored
434 <dt>doc</dt><dd>The original document from couch, if requested with include_docs=true</dd>
435 <dt>fields</dt><dd>All the fields that were stored with this match</dd>
0fcf578 @rnewson update docs.
authored
436 <dt>id</dt><dd>The unique identifier for this match.</dd>
437 <dt>score</dt><dd>The normalized score (0.0-1.0, inclusive) for this match</dd>
438 </dl>
439
fd16315 @rnewson update README.md
authored
440 Here's an example of a JSON response without sorting;
b207965 @rnewson improve README readability.
authored
441
118d28e @rnewson JSON example output.
authored
442 <pre>
443 {
c6356fd @rnewson update README.md and TODO to reflect progress.
authored
444 "q": "+content:enron",
fd16315 @rnewson update README.md
authored
445 "skip": 0,
446 "limit": 2,
447 "total_rows": 176852,
448 "search_duration": 518,
449 "fetch_duration": 4,
450 "rows": [
451 {
0fcf578 @rnewson update docs.
authored
452 "id": "hain-m-all_documents-257.",
fd16315 @rnewson update README.md
authored
453 "score": 1.601625680923462
454 },
455 {
0fcf578 @rnewson update docs.
authored
456 "id": "hain-m-notes_inbox-257.",
fd16315 @rnewson update README.md
authored
457 "score": 1.601625680923462
458 }
118d28e @rnewson JSON example output.
authored
459 ]
460 }
461 </pre>
462
fd16315 @rnewson update README.md
authored
463 And the same with sorting;
464
118d28e @rnewson JSON example output.
authored
465 <pre>
466 {
0fcf578 @rnewson update docs.
authored
467 "q": "+content:enron",
fd16315 @rnewson update README.md
authored
468 "skip": 0,
469 "limit": 3,
470 "total_rows": 176852,
471 "search_duration": 660,
472 "fetch_duration": 4,
473 "sort_order": [
474 {
475 "field": "source",
476 "reverse": false,
477 "type": "string"
478 },
479 {
480 "reverse": false,
481 "type": "doc"
482 }
118d28e @rnewson JSON example output.
authored
483 ],
fd16315 @rnewson update README.md
authored
484 "rows": [
485 {
0fcf578 @rnewson update docs.
authored
486 "id": "shankman-j-inbox-105.",
fd16315 @rnewson update README.md
authored
487 "score": 0.6131107211112976,
488 "sort_order": [
489 "enron",
490 6
491 ]
492 },
493 {
0fcf578 @rnewson update docs.
authored
494 "id": "shankman-j-inbox-8.",
fd16315 @rnewson update README.md
authored
495 "score": 0.7492915391921997,
496 "sort_order": [
497 "enron",
498 7
499 ]
500 },
501 {
0fcf578 @rnewson update docs.
authored
502 "id": "shankman-j-inbox-30.",
fd16315 @rnewson update README.md
authored
503 "score": 0.507369875907898,
504 "sort_order": [
505 "enron",
506 8
507 ]
508 }
118d28e @rnewson JSON example output.
authored
509 ]
510 }
511 </pre>
512
a4aa4e1 @rnewson document Content-Type response negotiation
authored
513 <h3>Content-Type of response</h3>
514
d2e1e9e @rnewson add notes about typing.
authored
515 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
516
139a78c @rnewson add info retrieval.
authored
517 <h1>Fetching information about the index</h1>
518
7a12058 @rnewson docs
authored
519 Calling couchdb-lucene without arguments returns a JSON object with information about the <i>whole</i> index.
139a78c @rnewson add info retrieval.
authored
520
521 <pre>
522 http://127.0.0.1:5984/enron/_fti
523 </pre>
524
525 returns;
526
527 <pre>
528 {"doc_count":517350,"doc_del_count":1,"disk_size":318543045}
529 </pre>
8203af6 @rnewson support _optimize and _expunge calls.
authored
530
531 <h1>Index Maintenance</h1>
532
533 For optimal query speed you can optimize your indexes. This causes the index to be rewritten into a single segment.
534
535 <pre>
536 curl -X POST http://localhost:5984/<db>/_fti/<ddoc>/<index>/_optimize
537 </pre>
538
539 If you just want to expunge pending deletes, then call;
540
541 <pre>
542 curl -X POST http://localhost:5984/<db>/_fti/<ddoc>/<index>/_expunge
543 </pre>
Something went wrong with that request. Please try again.