Documentation Source Text: Artifact Content

Artifact 887445dcd19c18f0dbf6f73bd7f97298c73a28f55f018dcd30c08adcc5816e87:

File pages/completion.in — part of check-in [6043714558] at 2017-07-14 03:53:46 on branch trunk — Improvements to the COMPLETION table documentation. (user: drh size: 2704)
<title>The COMPLETION() Table-Valued Function</title>
<tcl>hd_keywords COMPLETION {COMPLETION extension} \
 {COMPLETION table-valued function}</tcl>
<fancy_format>

<h1>Overview</h1>

<p>The COMPLETION extension implements a [table-valued function] named
"completion" that can be used to suggest completions of partially entered
words during interactive SQL input.  The completion table can be
used to help implement tab-completion, for example.

<h1>Details</h1>

<p>The designed query interface is:

<codeblock>
SELECT DISTINCT candidate COLLATE nocase
  FROM completion($prefix, $wholeline)
 ORDER BY 1;
</codeblock>

<p>The query above will return suggestions for the whole input word that
begins with $prefix.  The $wholeline parameter is all text from the beginning
of the line up to the insertion point.  The $wholeline parameter is used
for context.

<p>The $prefix parameter may be NULL, in which case the prefix is deduced
from $wholeline.  Or, the $wholeline parameter may be NULL or omitted if 
context information is unavailable or if context-aware completion is not
desired.

<p>The completion table might return the same candidate more than once, and
it will return candidates in an arbitrary order.  The DISTINCT keyword and
the ORDER BY in the sample query above are added to make the answers unique
and in lexicographical order.

<h2>Example Usage</h2>

<p>The completion table is used to implement tab-completion in the
[command-line shell] in conjunction with either the readline or linenoise
input line editing packages for unix.  See the
[https://sqlite.org/src/file/src/shell.c.in] source file for example
code.  Search for "FROM completion" to find the relevant code sections.

<p>Because the completion table is built into the command-line shell in order
to provide for tab-completions, you can run test queries against the
completion table directly in the command-line shell.  Simply type a
query such as the example shown above, filling in appropriate values
for $prefix and $wholeline, and observe the output.

<h1>Limitations</h1>

<p>The completion table is designed for interactive use.  It will return
answers at a speed appropriate for human typing.  No effort is made to
be unusually efficient, so long as the response time is nearly instantaneous
in a user interface.

<p>As of this writing (2017-07-13), the completion virtual table only
looks for SQL keywords, and schema, table, and column names.  The
context contained in $wholeline is completely ignored.  Future enhancements
will try to return new completions taken from function and pragma names
and other sources, as well as consider more context.  The completion
table should be considered a work-in-progress.