/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You 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.
 */

/**
 * Support for index-time and query-time joins.
 * <h2>Index-time joins</h2>
 *
 * <p>The index-time joining support joins while searching, where joined
 *   documents are indexed as a single document block using
 *   {@link org.apache.lucene.index.IndexWriter#addDocuments IndexWriter.addDocuments()}.  
 *   This is useful for any normalized content (XML documents or database tables).  In database terms, all rows for all
 *   joined tables matching a single row of the primary table must be
 *   indexed as a single document block, with the parent document
 *   being last in the group.</p>
 * 
 * <p>When you index in this way, the documents in your index are divided
 *   into parent documents (the last document of each block) and child
 *   documents (all others).  You provide a {@link org.apache.lucene.search.join.BitSetProducer} that identifies the
 *   parent documents, as Lucene does not currently record any information
 *   about doc blocks.</p>
 * 
 * <p>At search time, use {@link
 *   org.apache.lucene.search.join.ToParentBlockJoinQuery} to remap/join
 *   matches from any child {@link org.apache.lucene.search.Query} (ie, a
 *   query that matches only child documents) up to the parent document
 *   space.  The
 *   resulting query can then be used as a clause in any query that
 *   matches parent.</p>
 * 
 * <p>If you care about what child documents matched for each parent document,
 *    then use the {@link org.apache.lucene.search.join.ParentChildrenBlockJoinQuery} query to
 *    per matched parent document retrieve the child documents that caused to match the
 *    parent document in first place. This query should be used after your main query
 *    has been executed. For each hit execute the the
 *    {@link org.apache.lucene.search.join.ParentChildrenBlockJoinQuery} query </p>
 * <pre class="prettyprint">
 *   TopDocs results = searcher.search(mainQuery, 10);
 *   for (int i = 0; i < results.scoreDocs.length; i++) {
 *     ScoreDoc scoreDoc = results.scoreDocs[i];
 *
 *     // Run ParentChildrenBlockJoinQuery to figure out the top matching child docs:
 *     ParentChildrenBlockJoinQuery parentChildrenBlockJoinQuery =
 *       new ParentChildrenBlockJoinQuery(parentFilter, childQuery, scoreDoc.doc);
 *     TopDocs topChildResults = searcher.search(parentChildrenBlockJoinQuery, 3);
 *     // Process top child hits...
 *   }
 * </pre>
 *
 * <p>To map/join in the opposite direction, use {@link
 *   org.apache.lucene.search.join.ToChildBlockJoinQuery}.  This wraps
 *   any query matching parent documents, creating the joined query
 *   matching only child documents.
 * 
 * <h2>Query-time joins</h2>
 * 
 * <p>
 *   The query time joining is index term based and implemented as two pass search. The first pass collects all the terms from a fromField
 *   that match the fromQuery. The second pass returns all documents that have matching terms in a toField to the terms
 *   collected in the first pass.
 * </p>
 * <p>Query time joining has the following input:</p>
 * <ul>
 *   <li><code>fromField</code>: The from field to join from.
 *   <li><code>fromQuery</code>:  The query executed to collect the from terms. This is usually the user specified query.
 *   <li><code>multipleValuesPerDocument</code>:  Whether the fromField contains more than one value per document
 *   <li><code>scoreMode</code>:  Defines how scores are translated to the other join side. If you don't care about scoring
 *   use {@link org.apache.lucene.search.join.ScoreMode#None} mode. This will disable scoring and is therefore more
 *   efficient (requires less memory and is faster).
 *   <li><code>toField</code>: The to field to join to
 * </ul>
 * <p>
 *   Basically the query-time joining is accessible from one static method. The user of this method supplies the method
 *   with the described input and a <code>IndexSearcher</code> where the from terms need to be collected from. The returned
 *   query can be executed with the same <code>IndexSearcher</code>, but also with another <code>IndexSearcher</code>.
 *   Example usage of the {@link org.apache.lucene.search.join.JoinUtil#createJoinQuery(String, boolean, String, org.apache.lucene.search.Query, org.apache.lucene.search.IndexSearcher, org.apache.lucene.search.join.ScoreMode)
 *   JoinUtil.createJoinQuery()} :
 * </p>
 * <pre class="prettyprint">
 *   String fromField = "from"; // Name of the from field
 *   boolean multipleValuesPerDocument = false; // Set only to true in the case when your fromField has multiple values per document in your index
 *   String toField = "to"; // Name of the to field
 *   ScoreMode scoreMode = ScoreMode.Max; // Defines how the scores are translated into the other side of the join.
 *   Query fromQuery = new TermQuery(new Term("content", searchTerm)); // Query executed to collect from values to join to the to values
 * 
 *   Query joinQuery = JoinUtil.createJoinQuery(fromField, multipleValuesPerDocument, toField, fromQuery, fromSearcher, scoreMode);
 *   TopDocs topDocs = toSearcher.search(joinQuery, 10); // Note: toSearcher can be the same as the fromSearcher
 *   // Render topDocs...
 * </pre>
 */
package org.apache.lucene.search.join;