Using the luceneSupport optional tool

The luceneSupport plugin is an optional tool that lets you use Apache Lucene to perform full-text indexing and searching of the contents of Derby text columns.

The mainline API documentation for Apache Lucene at https://builds.apache.org/job/Lucene-Artifacts-trunk/javadoc/ is a useful starting point for understanding Lucene's capabilities.

Note: The luceneSupport plugin can be used only after a database has been fully upgraded to Derby Release 10.11 or higher. (See "Upgrading a database" in the Derby Developer's Guide for more information.) The plugin cannot be used on a database that is at Release 10.10 or lower.

Terminology

The following concepts are important to an understanding of the luceneSupport plugin.

Classpath for running the luceneSupport optional tool

Before you run the luceneSupport optional tool, make sure that your classpath contains the following jar files:

The Lucene jar files are included in the Derby source tree; alternatively, you can download them from http://lucene.apache.org/.

Loading and unloading the luceneSupport optional tool

In a database protected by SQL authorization, only the database owner can issue the commands which load and unload the Lucene plugin. (See "Database Owner" in the Derby Security Guide for more information.)

Loading the plugin looks very much like loading any other optional tool. You call the SYSCS_UTIL.SYSCS_REGISTER_TOOL system procedure in a statement like the following:

call syscs_util.syscs_register_tool( 'luceneSupport', true );

This command creates the LUCENESUPPORT schema, which contains the following objects:

Removing the plugin also looks much like unloading other optional tools. Call the SYSCS_UTIL.SYSCS_REGISTER_TOOL system procedure in a statement like the following:

call syscs_util.syscs_register_tool( 'luceneSupport', false );

This command does the following:

See the Derby Reference Manual for information about the SYSCS_UTIL.SYSCS_REGISTER_TOOL system procedure.

Encryption and the luceneSupport tool

The luceneSupport tool may not be used on an encrypted database. Users who need full-text indexing of encrypted data should store the database in an encrypted directory or on an encrypted device.

Lucene versions

The Derby community has tested the luceneSupport tool against the following versions of Lucene. Other versions of Lucene may or may not work.

Derby cannot make any guarantees about the compatibility of two different versions of Lucene. Users should bear the following in mind:

Related reference
Using the databaseMetaData optional tool
Using the foreignViews optional tool
Using the simpleJson optional tool
Using the rawDBReader optional tool