Documentation Source Text

value of the parameter specified as part of the 'merge' command. The size of
each page is as configured by the [FTS5 pgsz option].

<p> If the parameter is a postive value, B-tree structures are only eligible
for merging if one of the following is true:

<ul>
  <li> There are U or more such b-trees on a
       single level (see the documentation for the [FTS5 automerge option]
       for an explanation of b-tree levels), where U is the value assigned
       to the [FTS5 usermerge option] option.
  <li> A merge has already been started (perhaps by a 'merge' command that
       specified a negative parameter).
</ul>

<p> It is possible to tell whether or not the 'merge' command found any 
b-trees to merge together by checking the value returned by the
[sqlite3_total_changes()] API before and after the command is executed. If
the difference between the two values is 2 or greater, then work was performed.
If the difference is less than 2, then the 'merge' command was a no-op. In this
case there is no reason to execute the same 'merge' command again, at least
until after the FTS table is next updated.

<p> If the parameter is negative, and there are B-tree structures on more than
one level within the FTS index, all B-tree structures are assigned to the same
level before the merge operation is commenced. Additionally, if the parameter
is negative, the value of the usermerge configuration option is not 
respected - as few as two b-trees from the same level may be merged together.

<p>Refer to the documentation for the [FTS5 automerge option] for more details
regarding the relationship between the full-text index and its component
b-trees.

<codeblock>
  INSERT INTO ft(ft) VALUES('optimize');
</codeblock>

<p>Because it reorganizes the entire FTS index, the optimize command can 
take a long time to run. The [FTS5 merge command] can be used to divide
the work of optimizing the FTS index into multiple steps. To do this:

<ul>
  <li> Invoke the 'merge' command once with the parameter set to -N, then
  <li> Invoke the 'merge' command zero or more times with the parameter set to N.
</ul>

<p>where N is the number of pages of data to merge within each invocation of
the merge command. The application should stop invoking merge when the
difference in the value returned by the sqlite3_total_changes() function before
and after the merge command drops to below two. The merge commands may be
issued as part of the same or separate transactions, and by the same or
different database clients. Refer to the documentation for the [FTS5 merge
command | merge command] for further details.

<h2 tags="FTS5 pgsz option">The 'pgsz' Configuration Option</h2>

<p> This command is used to set the persistent "pgsz" option.

<p> The full-text index maintained by FTS5 is stored as a series of fixed-size
blobs in a database table. It is not strictly necessary for all blobs that make