org.apache.lucene.search.join.package-info Maven / Gradle / Ivy
/*
* 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.
* Index-time joins
*
* 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.
*
* 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.
*
* 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.
*
* 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
*
* 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...
* }
*
*
* 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.
*
*
Query-time joins
*
*
* 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.
*
* Query time joining has the following input:
*
* fromField: The from field to join from.
* fromQuery: The query executed to collect the from terms. This is usually the user specified query.
* multipleValuesPerDocument: Whether the fromField contains more than one value per document
* scoreMode: 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).
* toField: The to field to join to
*
*
* 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 IndexSearcher where the from terms need to be collected from. The returned
* query can be executed with the same IndexSearcher, but also with another IndexSearcher.
* 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()} :
*
*
* 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...
*
*/
package org.apache.lucene.search.join;