One of the powerful Domino features is fulltext search. It enables the user to search for words and phrases in some or all documents of a database. To speed up the search process Domino maintains a fulltext search index which can be configured by the user. The search index is stored in separate files in the Domino data directory. Domino Connection provides a method to find out whether an index is present. Use the isIndexed method to receive a Boolean value that indicates the index state.
Domino Connection supports fulltext search on a document level. After the query is executed and a collection of documents is returned, no further discrimination is performed on the fields in the note. If you want to further find out about the position of your fulltext query within the documents retrieved, you have to explicitly iterate through the item dictionaries and perform a stream search on the items contents. There is no support for this operation from the Domino API.
You need to have or create a fulltext index before you can execute a query.
Note: | Domino API does not support the creation of fulltext indices on remote databases. The following methods can only be used with local databases. |
If a AbtLnDatabase is not indexed yet, there are two ways to create a fulltext index:
The class AbtLnFTIndexOptions allows you to set up the search index like you would do it using the Notes client software. To learn about indexing options, see your Domino documentation. Here is a code fragment showing how to create a fulltext search index on a database with the following options:
| connection database ftOptions | "Start runtime system" AbtLnEnvironment startUp. "Create a connection to local databases" connection := AbtLnConnection local. "Open one of the sample databases provided with the feature" database := connection openDatabase: 'VASAMPLE\VASAMPLE.NSF'. "Find out if the database is indexed" database isIndexed ifFalse: [ "If the database is not indexed, create an index using the special indexing options" ftOptions := AbtLnFTIndexOptions new disableEncryptedFields; disableCaseSensitve; enableSentenceAndParagraphs. database createIndexWithOptions: ftOptions. ]. "...... application code follows"
Note: | Building a fulltext index can take some time. On large databases the creation can take several minutes. You should consider executing the createIndex method in a separate process. |
As a fulltext index is a static structure, it can be out of date. Adding or deleting documents can force you to re-index a databases for proper fulltext search results. Use the updateIndex method with your databases to restructure a previously existing index.
Fulltext indices tend to become very big on large databases. To save space on your disk, you can discard a FT index after use. Send the deleteIndex message to the indexed database. All associated index files will be deleted.
There are two basic mechanisms to be used when searching with Domino Connection:
To execute a fulltext query, you have to specify a number of parameters for the search. Use the AbtLnFTSearchQualifier class to set up a detailed query or pass a String as argument to the ftSearch: method. The result of a fulltext search is a collection of AbtLnNotes which are initialized with their item dictionaries, but not yet filled with data. Use the fill method with each document to read the actual data.
Here is a step-by-step example how to find all documents in your local names and address book which contain a simple string (i.e. 'Your name' -- please replace this string with your name).
| connection database answerSet | "Start runtime system" AbtLnEnvironment startUp. "Create a connection to local databases" connection := AbtLnConnection local. "open the local names and address book" database := connection openDatabase: 'NAMES'. "Find out if the database is indexed and create an index if necessary" database isIndexed ifFalse: [ database createIndex ]. "Perform a fulltext query on the database using your user name as search string" answerSet := database ftSearch:'Your name'. "Convert the search results to real documents and print the documents to the Transcript window" answerSet do: [ :note | Transcript nextPutAll: note fill printString ]. "Close the database" database close. "Shut down runtime system" AbtLnEnvironment shutDown.
Here is a more complicated example that makes use of the AbtLnSerachQualifierclass to specify search options. You will search your mail servers names and address books view named 'People' for certain strings (i.e. 'YourName') , limit the number of search results to two documents and sort the search result by relevance (which is the number of occurrences of the search string).
| connection database answerSet qualifier | "Start runtime system" AbtLnEnvironment startUp. "Open a connection the your mail server" connection := AbtLnConnection mailServer. "Open the names and address book on the mail server" database := connection openDatabase: 'NAMES'. "Specify a query qualifier containing your user name and limit the number of result documents to two" database isIndexed ifTrue: [ qualifier := AbtLnFTQueryQualifier new queryString: 'Your Name'; sortByRelevance; maximumResults: 2. "Execute the query on the specified view only" answerSet := database ftSearch: qualifier viewNamed: 'People'. "Print the results of the query onto the Transcript window" answerSet do: [ :note | Transcript nextPutAll: note fill printString ]. ] ifFalse: [ "In case the database is not indexed, give up because you cannot create an index on a remote database" Transcript nextPutAll: 'NAMES.NSF of mail server is not indexed, can not search the database'; cr. ]. "Close the database" database close. "Shutdown runtime system" AbtLnEnvironment shutDown.