]> Sergey Matveev's repositories - public-inbox.git/blob - Documentation/public-inbox-index.pod
over: recent: remove expensive COUNT query
[public-inbox.git] / Documentation / public-inbox-index.pod
1 =head1 NAME
2
3 public-inbox-index - create and update search indices
4
5 =head1 SYNOPSIS
6
7 public-inbox-index [OPTIONS] INBOX_DIR...
8
9 public-inbox-index [OPTIONS] --all
10
11 =head1 DESCRIPTION
12
13 public-inbox-index creates and updates the search, overview and
14 NNTP article number database used by the read-only public-inbox
15 HTTP and NNTP interfaces.  Currently, this requires
16 L<DBD::SQLite> and L<DBI> Perl modules.  L<Search::Xapian>
17 is optional, only to support the PSGI search interface.
18
19 Once the initial indices are created by public-inbox-index,
20 L<public-inbox-mda(1)> and L<public-inbox-watch(1)> will
21 automatically maintain them.
22
23 Running this manually to update indices is only required if
24 relying on L<git-fetch(1)> to mirror an existing public-inbox;
25 or if upgrading to a new version of public-inbox using
26 the C<--reindex> option.
27
28 Having the overview and article number database is essential to
29 running the NNTP interface, and strongly recommended for the
30 HTTP interface as it provides thread grouping in addition to
31 normal search functionality.
32
33 =head1 OPTIONS
34
35 =over
36
37 =item --jobs=JOBS, -j
38
39 Influences the number of Xapian indexing shards in a
40 (L<public-inbox-v2-format(5)>) inbox.
41
42 See L<public-inbox-init(1)/--jobs> for a full description
43 of sharding.
44
45 C<--jobs=0> is accepted as of public-inbox 1.6.0 (PENDING)
46 to disable parallel indexing regardless of the number of
47 pre-existing shards.
48
49 If the inbox has not been indexed or initialized, C<JOBS - 1>
50 shards will be created (one job is always needed for indexing
51 the overview and article number mapping).
52
53 Default: the number of existing Xapian shards
54
55 =item --compact / -c
56
57 Compacts the Xapian DBs after indexing.  This is recommended
58 when using C<--reindex> to avoid running out of disk space
59 while indexing multiple inboxes.
60
61 While option takes a negligible amount of time compared to
62 C<--reindex>, it requires temporarily duplicating the entire
63 contents of the Xapian DB.
64
65 This switch may be specified twice, in which case compaction
66 happens both before and after indexing to minimize the temporal
67 footprint of the (re)indexing operation.
68
69 Available since public-inbox 1.4.0.
70
71 =item --reindex
72
73 Forces a re-index of all messages in the inbox.
74 This can be used for in-place upgrades and bugfixes while
75 NNTP/HTTP server processes are utilizing the index.  Keep in
76 mind this roughly doubles the size of the already-large
77 Xapian database.  Using this with C<--compact> or running
78 L<public-inbox-compact(1)> afterwards is recommended to
79 release free space.
80
81 public-inbox protects writes to various indices with
82 L<flock(2)>, so it is safe to reindex (and rethread) while
83 L<public-inbox-watch(1)>, L<public-inbox-mda(1)> or
84 L<public-inbox-learn(1)> run.
85
86 This does not touch the NNTP article number database.
87 It does not affect threading unless C<--rethread> is
88 used.
89
90 =item --all
91
92 Index all inboxes configured in ~/.public-inbox/config.
93 This is an alternative to specifying individual inboxes directories
94 on the command-line.
95
96 =item --rethread
97
98 Regenerate internal THREADID and message thread associations
99 when reindexing.
100
101 This fixes some bugs in older versions of public-inbox.  While
102 it is possible to use this without C<--reindex>, it makes little
103 sense to do so.
104
105 Available in public-inbox 1.6.0 (PENDING).
106
107 =item --prune
108
109 Run L<git-gc(1)> to prune and expire reflogs if discontiguous history
110 is detected.  This is intended to be used in mirrors after running
111 L<public-inbox-edit(1)> or L<public-inbox-purge(1)> to ensure data
112 is expunged from mirrors.
113
114 Available since public-inbox 1.2.0.
115
116 =item --max-size SIZE
117
118 Sets or overrides L</publicinbox.indexMaxSize> on a
119 per-invocation basis.  See L</publicinbox.indexMaxSize>
120 below.
121
122 Available since public-inbox 1.5.0.
123
124 =item --batch-size SIZE
125
126 Sets or overrides L</publicinbox.indexBatchSize> on a
127 per-invocation basis.  See L</publicinbox.indexBatchSize>
128 below.
129
130 When using rotational storage but abundant RAM, using a large
131 value (e.g. C<500m>) with C<--sequential-shard> can
132 significantly speed up the initial index and full C<--reindex>
133 invocations (but not incremental updates).
134
135 Available in public-inbox 1.6.0 (PENDING).
136
137 =item --no-fsync
138
139 Disables L<fsync(2)> and L<fdatasync(2)> operations on SQLite
140 and Xapian.  This is only effective with Xapian 1.4+.  This is
141 primarily intended for systems with low RAM and the small
142 (default) C<--batch-size=1m>.  Users of large C<--batch-size>
143 may even find disabling L<fdatasync(2)> causes too much dirty
144 data to accumulate, resulting on latency spikes from writeback.
145
146 Available in public-inbox 1.6.0 (PENDING).
147
148 =item --sequential-shard
149
150 Sets or overrides L</publicinbox.indexSequentialShard> on a
151 per-invocation basis.  See L</publicinbox.indexSequentialShard>
152 below.
153
154 Available in public-inbox 1.6.0 (PENDING).
155
156 =item --skip-docdata
157
158 Stop storing document data in Xapian on an existing inbox.
159
160 See L<public-inbox-init(1)/--skip-docdata> for description and caveats.
161
162 Available in public-inbox 1.6.0 (PENDING).
163
164 =back
165
166 =head1 FILES
167
168 For v1 (ssoma) repositories described in L<public-inbox-v1-format(5)>.
169 All public-inbox-specific files are contained within the
170 C<$GIT_DIR/public-inbox/> directory.
171
172 v2 inboxes are described in L<public-inbox-v2-format(5)>.
173
174 =head1 CONFIGURATION
175
176 =over 8
177
178 =item publicinbox.indexMaxSize
179
180 Prevents indexing of messages larger than the specified size
181 value.  A single suffix modifier of C<k>, C<m> or C<g> is
182 supported, thus the value of C<1m> to prevents indexing of
183 messages larger than one megabyte.
184
185 This is useful for avoiding memory exhaustion in mirrors
186 via git.  It does not prevent L<public-inbox-mda(1)> or
187 L<public-inbox-watch(1)> from importing (and indexing)
188 a message.
189
190 This option is only available in public-inbox 1.5 or later.
191
192 Default: none
193
194 =item publicinbox.indexBatchSize
195
196 Flushes changes to the filesystem and releases locks after
197 indexing the given number of bytes.  The default value of C<1m>
198 (one megabyte) is low to minimize memory use and reduce
199 contention with parallel invocations of L<public-inbox-mda(1)>,
200 L<public-inbox-learn(1)>, and L<public-inbox-watch(1)>.
201
202 Increase this value on powerful systems to improve throughput at
203 the expense of memory use.  The reduction of lock granularity
204 may not be noticeable on fast systems.  With SSDs, values above
205 C<4m> have little benefit.
206
207 For L<public-inbox-v2-format(5)> inboxes, this value is
208 multiplied by the number of Xapian shards.  Thus a typical v2
209 inbox with 3 shards will flush every 3 megabytes by default
210 unless parallelism is disabled via C<--sequential-shard>
211 or C<--jobs=0>.
212
213 This influences memory usage of Xapian, but it is not exact.
214 The actual memory used by Xapian and Perl has been observed
215 in excess of 10x this value.
216
217 This option is available in public-inbox 1.6 or later.
218 public-inbox 1.5 and earlier used the current default, C<1m>.
219
220 Default: 1m (one megabyte)
221
222 =item publicinbox.indexSequentialShard
223
224 For L<public-inbox-v2-format(5)> inboxes, setting this to C<true>
225 allows indexing Xapian shards in multiple passes.  This speeds up
226 indexing on rotational storage with high seek latency by allowing
227 individual shards to fit into the kernel page cache.
228
229 Using a higher-than-normal number of C<--jobs> with
230 L<public-inbox-init(1)> may be required to ensure individual
231 shards are small enough to fit into cache.
232
233 Warning: interrupting C<public-inbox-index(1)> while this option
234 is in use may leave the search indices out-of-date with respect
235 to SQLite databases.  WWW and IMAP users may notice incomplete
236 search results, but it is otherwise non-fatal.  Using C<--reindex>
237 will bring everything back up-to-date.
238
239 Available in public-inbox 1.6.0 (PENDING).
240
241 This is ignored on L<public-inbox-v1-format(5)> inboxes.
242
243 Default: false, shards are indexed in parallel
244
245 =item publicinbox.<name>.indexSequentialShard
246
247 Identical to L</publicinbox.indexSequentialShard>,
248 but only affect the inbox matching E<lt>nameE<gt>.
249
250 =back
251
252 =head1 ENVIRONMENT
253
254 =over 8
255
256 =item PI_CONFIG
257
258 Used to override the default "~/.public-inbox/config" value.
259
260 =item XAPIAN_FLUSH_THRESHOLD
261
262 The number of documents to update before committing changes to
263 disk.  This environment is handled directly by Xapian, refer to
264 Xapian API documentation for more details.
265
266 For public-inbox 1.6 and later, use C<publicinbox.indexBatchSize>
267 instead.
268
269 Setting C<XAPIAN_FLUSH_THRESHOLD> or
270 C<publicinbox.indexBatchSize> for a large C<--reindex> may cause
271 L<public-inbox-mda(1)>, L<public-inbox-learn(1)> and
272 L<public-inbox-watch(1)> tasks to wait long and unpredictable
273 periods of time during C<--reindex>.
274
275 Default: none, uses C<publicinbox.indexBatchSize>
276
277 =back
278
279 =head1 UPGRADING
280
281 Occasionally, public-inbox will update it's schema version and
282 require a full index by running this command.
283
284 =head1 CONTACT
285
286 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
287
288 The mail archives are hosted at L<https://public-inbox.org/meta/>
289 and L<http://hjrcffqmbrq6wope.onion/meta/>
290
291 =head1 COPYRIGHT
292
293 Copyright 2016-2020 all contributors L<mailto:meta@public-inbox.org>
294
295 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
296
297 =head1 SEE ALSO
298
299 L<Search::Xapian>, L<DBD::SQLite>