Used to efficiently limit the results of a search to a specified subset of one or more indexes.
File: dtsearch.h
|
Operator |
Description |
|---|---|
|
Copy another search filter |
|
Method |
Description |
|---|---|
|
Add an index to the filter, returning an integer that can be used to identify the index in the selection functions. | |
|
Select only the document ids that are not selected in another search filter | |
|
Select only the document ids that are also selected in another search filter | |
|
Clear all data from a search filter | |
|
Copy a search fitler | |
|
Copy a search fitler | |
|
Returns the handle for the search filter and detaches it from this object, so the caller is responsible for deleting the search filter. | |
|
Create an empty search filter | |
|
Create a search filter that is a copy of another search filter | |
|
Compare two search filters for equality. Two search filters are equal if they contain the same indexes and, for each index, the same document selections | |
|
Retrieves information about whether a search filter is out of date. If the index was compressed (without the dtsIndexKeepExistingDocIds flag) or created since the search was done, the search filter is obsolete because the doc ids in the search filter will not correspond to the doc ids in the index. If the index was updated since the search filter was created, it may be incomplete. | |
|
Returns the handle for a search filter, which can be used to limit a search (set dtsSearchJob.searchFilterHandle) or to receive the results of a search (set dtsSearchJob.outputSearchFilterHandle). | |
|
Returns the number of indexes in the filter, or -1 if the handle is missing or invalid | |
|
Returns the index path for an index in the filter | |
|
Returns an array of integers containing the document ids of the documents selected in the filter. | |
|
Select all document ids listed in search results (deprecated) makeFrom() is deprecated because the search results may contain only some of the matching documents (for example, a SearchResults object may contain only the best-matching 100 documents). Instead, either using selectItemsBySearch or setting SearchJob.WantResultsAsFilter is recommended, to ensure that the SearchFilter produced is complete. | |
|
Select any document ids that are also selected in another search filter | |
|
Read the search filter from a disk file. Any existing data in the search filter is replaced by the data read from the file. | |
|
Select all of the documents in the index. | |
|
Set the selection state of a range of document ids to the value indicated by fSelected. | |
|
Set the selection state of a set of document ids based on the results of a search. All documents retrieved by the search set up by searchJob will have their selection state changed to the state indicated by fSelected. *All* documents retrieved in the search are selected, regardless of the maxFilesToRetrieve value in the dtsSearchJob. | |
|
Select no documents in the index. By default, no documents are selected when a search filter is created, so there is no need to call selectNone to initialize the filter. | |
|
Set the selection state of a list of document ids to the value indicated by fSelected. | |
|
Write the search filter to a disk file. | |
|
Free resources allocated for a search filter |
|
Method |
Description |
|---|---|
|
Add an index to the filter, returning an integer that can be used to identify the index in the selection functions. | |
|
Select only the document ids that are not selected in another search filter | |
|
Select only the document ids that are also selected in another search filter | |
|
Clear all data from a search filter | |
|
Copy a search fitler | |
|
Copy a search fitler | |
|
Returns the handle for the search filter and detaches it from this object, so the caller is responsible for deleting the search filter. | |
|
Create an empty search filter | |
|
Create a search filter that is a copy of another search filter | |
|
Compare two search filters for equality. Two search filters are equal if they contain the same indexes and, for each index, the same document selections | |
|
Retrieves information about whether a search filter is out of date. If the index was compressed (without the dtsIndexKeepExistingDocIds flag) or created since the search was done, the search filter is obsolete because the doc ids in the search filter will not correspond to the doc ids in the index. If the index was updated since the search filter was created, it may be incomplete. | |
|
Returns the handle for a search filter, which can be used to limit a search (set dtsSearchJob.searchFilterHandle) or to receive the results of a search (set dtsSearchJob.outputSearchFilterHandle). | |
|
Returns the number of indexes in the filter, or -1 if the handle is missing or invalid | |
|
Returns the index path for an index in the filter | |
|
Returns an array of integers containing the document ids of the documents selected in the filter. | |
|
Select all document ids listed in search results (deprecated) makeFrom() is deprecated because the search results may contain only some of the matching documents (for example, a SearchResults object may contain only the best-matching 100 documents). Instead, either using selectItemsBySearch or setting SearchJob.WantResultsAsFilter is recommended, to ensure that the SearchFilter produced is complete. | |
|
Select any document ids that are also selected in another search filter | |
|
Read the search filter from a disk file. Any existing data in the search filter is replaced by the data read from the file. | |
|
Select all of the documents in the index. | |
|
Set the selection state of a range of document ids to the value indicated by fSelected. | |
|
Set the selection state of a set of document ids based on the results of a search. All documents retrieved by the search set up by searchJob will have their selection state changed to the state indicated by fSelected. *All* documents retrieved in the search are selected, regardless of the maxFilesToRetrieve value in the dtsSearchJob. | |
|
Select no documents in the index. By default, no documents are selected when a search filter is created, so there is no need to call selectNone to initialize the filter. | |
|
Set the selection state of a list of document ids to the value indicated by fSelected. | |
|
Write the search filter to a disk file. | |
|
Free resources allocated for a search filter |
|
Operator |
Description |
|---|---|
|
Copy another search filter |
The dtsSearchFilter class provides a way to designate which documents can be returned by a search. It is useful in situations where a text search using must be combined with a search of a database. The database search is done first, and then the results of the database search are used to limit the dtSearch search.
To use a search filter to limit a search,
- Create the search filter, or read a previously-create search filter from a disk file.
- Attach the search filter to a dtsSearchJob's searchFilterHandle
Search filters do not use names to identify documents because a filter may specify thousands, or hundreds of thousands, of documents, and a table of filenames would take too much memory and would take too long to check. Instead, each document is identified by (a) the index it belongs to, and (b) the document's document id, or docId, a unique integer that is assigned to each document in an index. The docId for a document can be obtained by searching for the document by name, and then examining the document's properties in search results. In the C++ API, the docId is returned as dtsSearchResultsItem.docId. See: Document Ids
The first document added to an index has the DocId 1, and subsequent documents will have sequentially numbered DocIds 2, 3, 4, and so forth. When a document is reindexed, its docId is "cancelled" and a new docId is assigned. Compressing an index renumbers all of the docIds, so after an index has been compressed, a document's docId may change.
A docId that is selected may be returned in search results. A document that is not selected will not be returned in search results, even if it otherwise satisfies the search request.
If the criteria for the search filter can be expressed as one or more search requests, you can use selectItemsBySearch to select documents in the SearchFilter.
A search filter can cover any number of indexes. To add an index to a search filter, call addIndex() with the full path to the index. The path must be expressed exactly as it will be expressed in the search job. The addIndex() function returns an integer that is used to identify that index when selecting and de-selecting documents for the filter. (This makes the selection and de-selection functions, which may be called thousands of times, more effiicent.)
A search filter is implemented in the dtSearch Engine using a table of bit vectors, one for each index in the filter. Each bit vector has one bit for each document in its index. For example, a search filter for a single index with 1,000,000 documents would have 1,000,000 bits, or 125 kilobytes of data. The write function compresses the bit vector where possible, so a saved search filter may be smaller than the bit vectors that it contains.
When a search filter is created, the dtSearch Engine returns a handle to it. The dtsSearchFilter class wraps this handle.
The following code sequence demonstrates the use of dtsSearchFilter to limit a search: