unprocessedFTSearch (AgentContext - Java)

Given a full-text query, returns documents in a database:

  • That the current agent considers to be unprocessed
  • And that match the query

Defined in

AgentContext

Syntax

public DocumentCollection unprocessedFTSearch(String query, int maxdocs)
    throws NotesException
public DocumentCollection unprocessedFTSearch(String query, int maxdocs, int sortopt, int otheropt)
    throws NotesException

Parameters

String query

The full-text query.

int maxdocs

The maximum number of documents you want returned; 0 means all matching documents.

int sortopt

Use one of these to specify a sorting option:

  • Database.FT_SCORES (default) sorts by relevance score with highest relevance first.
  • Database.FT_DATECREATED_DES sorts by document creation date in descending order.

  • Database.FT_DATECREATED_ASC sorts by document creation date in ascending order.

  • Database.FT_DATE_DES sorts by document date in descending order.

  • Database.FT_DATE_ASC sorts by document date in ascending order.

otheropt

Integer. Use the following constants to specify additional search options. To specify more than one option, use a logical OR operation.

  • Database.FT_DATABASE includes Domino® databases in the search scope.
  • Database.FT_FILESYSTEM includes files other than Domino® databases in the search scope.
  • Database.FT_FUZZY specifies a fuzzy search.
  • Database.FT_STEMS uses stem words as the basis of the search.

Return value


DocumentCollection

A sorted collection of documents that are not yet processed and match the query.

Usage

This method is valid only for agents.

How does it work?

This method works in two parts:

  • First, it finds a collection of documents that the agent considers to be "unprocessed." The type of agent determines which documents are considered to be unprocessed. This document collection is identical to that returned by getUnprocessedDocuments.
  • Second, it conducts a full-text search on the unprocessed documents and returns a collection of those documents that match the query.

For example, in an agent that runs on all selected documents in a view, getUnprocessedFTSearch searches only the selected documents and returns those that match the query. In an agent that runs on all new and modified documents since the last run, getUnprocessedFTSearch searches only the documents that were not marked by updateProcessedDoc, and returns those that match the query.

What documents are returned?

The following table describes the documents that are returned by unprocessedFTSearch. Document selection occurs once, before the agent runs.

Agent runs on:

unprocessedFTSearch returns documents that meet all of these requirements:

All documents in database

Meet the search criteria specified in Agent Properties box

Meet the full-text search critieria specified in this method

All new & modified documents

Not processed by this agent with updateProcessedDoc

Created or modified since the agent last ran

Meet the search criteria specified in Agent Properties box

Meet the full-text search critieria specified in this method

All unread documents in view

Are unread and in the view

Meet the search criteria specified in Agent Properties box

Meet the full-text search criteria specified in this method

All documents in view

Are in the view

Meet the search criteria specified in Agent Properties box

Meet the full-text search criteria specified in this method

All selected documents

Are selected in the view

Meet the search criteria specified in Agent Properties box

Meet the full-text search criteria specified in this method

None

Is the current document only

Using updateProcessedDoc

For agents that run on new and modified documents, you must use updateProcessedDoc to mark each document as "processed," which ensures that a document gets processed by the agent only once (unless it's modified again). If you do not call this method for each document, the agent processes the same documents the next time it runs.

The updateProcessedDoc method marks a document as processed only for the particular agent from which it is called. Using updateProcessedDoc in one agent has no effect on the documents that another agent processes.

In all other agents and view actions, updateProcessedDoc has no effect.

View actions

When used in a view action, unprocessedFTSearch returns the same documents as an agent that runs on selected documents.

Full-text indexes

If the database is not full-text indexed, this method works, but less efficiently. To test for an index, use isFTIndexed. To create an index on a local database, use updateFTIndex.

This method returns a maximum of 5,000 documents by default. The Notes®.ini variable FT_MAX_SEARCH_RESULTS overrides this limit for indexed databases or databases that are not indexed but that are running in an agent on the client. For a database that is not indexed and is running in an agent on the server, you must set the TEMP_INDEX_MAX_DOC Notes®.ini variable as well. The absolute maximum is 2,147,483,647.

Options

If you don't specify any sort options, the documents are sorted by relevance score. When the collection is sorted by relevance the highest relevance appears first. To access the relevance score of each document in the collection, use FTSearchScore in Document.

If you ask for a sort by date, you don't get relevance scores. If you pass the resulting DocumentCollection to a Newsletter object, it formats its doclink report with either the document creation date or the relevance score, depending on the sort options.

Query syntax

To search for a word or phrase, enter the word or phrase as is, except that search keywords must be enclosed in quotes. Remember to escape quotes if you are inside a literal.

Wildcards, operators, and other syntax are permitted. For the complete syntax rules, see "Refining a search query using operators" in Notes® Help. Search for "query syntax" in the Domino® Designer Eclipse help system or information center (for example, http://publib.boulder.ibm.com/infocenter/domhelp/v8r0/index.jsp), both of which include Notes®.

Example