/*
* Copyright 2004 The Apache Software Foundation
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
using System;
using Document = Lucene.Net.Documents.Document;
using IndexReader = Lucene.Net.Index.IndexReader;
using Term = Lucene.Net.Index.Term;
namespace Lucene.Net.Search
{
/// The interface for search implementations.
///
/// Searchable is the abstract network protocol for searching.
/// Implementations provide search over a single index, over multiple
/// indices, and over indices on remote servers.
///
///
Queries, filters and sort criteria are designed to be compact so that
/// they may be efficiently passed to a remote index, with only the top-scoring
/// hits being returned, rather than every non-zero scoring hit.
///
public interface Searchable
{
/// Lower-level search API.
///
/// {@link HitCollector#Collect(int,float)} is called for every non-zero
/// scoring document.
///
HitCollector-based access to remote indexes is discouraged.
///
///
Applications should only use this if they need all of the
/// matching documents. The high-level search API ({@link
/// Searcher#Search(Query)}) is usually more efficient, as it skips
/// non-high-scoring hits.
///
///
/// to match documents
///
/// if non-null, a bitset used to eliminate some documents
///
/// to receive hits
///
/// BooleanQuery.TooManyClauses
///
///
///
///
void Search(Query query, Filter filter, HitCollector results);
/// Expert: Low-level search implementation.
/// Identical to {@link #Search(Query, Filter, HitCollector)}, but takes
/// a Weight instead of a query.
///
void Search(Weight weight, Filter filter, HitCollector results);
/// Frees resources associated with this Searcher.
/// Be careful not to call this method while you are still using objects
/// like {@link Hits}.
///
void Close();
/// Expert: Returns the number of documents containing term
.
/// Called by search code to compute term weights.
///
///
///
int DocFreq(Term term);
/// Expert: For each term in the terms array, calculates the number of
/// documents containing term
. Returns an array with these
/// document frequencies. Used to minimize number of remote calls.
///
int[] DocFreqs(Term[] terms);
/// Expert: Returns one greater than the largest possible document number.
/// Called by search code to compute term weights.
///
///
///
int MaxDoc();
/// Expert: Low-level search implementation. Finds the top n
/// hits for query
, applying filter
if non-null.
///
/// Called by {@link Hits}.
///
///
Applications should usually call {@link Searcher#Search(Query)} or
/// {@link Searcher#Search(Query,Filter)} instead.
///
/// BooleanQuery.TooManyClauses
///
///
///
///
TopDocs Search(Query query, Filter filter, int n);
/// Expert: Low-level search implementation.
/// Identical to {@link #Search(Query, Filter, int)}, but takes
/// a Weight instead of a query.
///
TopDocs Search(Weight weight, Filter filter, int n);
/// Expert: Returns the stored fields of document i
.
/// Called by {@link HitCollector} implementations.
///
///
///
Document Doc(int i);
/// Expert: called to re-write queries into primitive queries.
/// BooleanQuery.TooManyClauses
Query Rewrite(Query query);
/// Returns an Explanation that describes how doc
scored against
/// query
.
///
/// This is intended to be used in developing Similarity implementations,
/// and, for good performance, should not be displayed with every hit.
/// Computing an explanation is as expensive as executing the query over the
/// entire index.
///
/// BooleanQuery.TooManyClauses
Explanation Explain(Query query, int doc);
/// Identical to {@link #Search(Query, Filter, HitCollector)}, but takes
/// a Weight instead of a query.
///
Explanation Explain(Weight weight, int doc);
/// Expert: Low-level search implementation with arbitrary sorting. Finds
/// the top n
hits for query
, applying
/// filter
if non-null, and sorting the hits by the criteria in
/// sort
.
///
/// Applications should usually call {@link
/// Searcher#Search(Query,Filter,Sort)} instead.
///
/// BooleanQuery.TooManyClauses
///
///
///
///
TopFieldDocs Search(Query query, Filter filter, int n, Sort sort);
/// Expert: Low-level search implementation.
/// Identical to {@link #Search(Query, Filter, int, Sort)}, but takes
/// a Weight instead of a query.
///
TopFieldDocs Search(Weight weight, Filter filter, int n, Sort sort);
}
}