You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by mi...@apache.org on 2013/11/27 13:07:31 UTC
svn commit: r1546008 - in /lucene/dev/branches/lucene5339: ./ lucene/
lucene/facet/src/java/org/apache/lucene/facet/
Author: mikemccand
Date: Wed Nov 27 12:07:30 2013
New Revision: 1546008
URL: http://svn.apache.org/r1546008
Log:
LUCENE-5339: Gilad's feedback, improve javadocs
Modified:
lucene/dev/branches/lucene5339/TODO
lucene/dev/branches/lucene5339/lucene/build.xml
lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/AssociationFacetField.java
lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/CachedOrdinalsReader.java
lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/DrillDownQuery.java
lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/DrillSideways.java
lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/FacetField.java
lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/FacetResult.java
lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/Facets.java
lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/FacetsConfig.java
lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/FastTaxonomyFacetCounts.java
lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/FloatAssociationFacetField.java
lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/IntAssociationFacetField.java
lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/LabelAndValue.java
lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/Range.java
lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/RangeFacetCounts.java
lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/SortedSetDocValuesReaderState.java
lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/TaxonomyFacetCounts.java
lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/TaxonomyFacetSumFloatAssociations.java
lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/TaxonomyFacetSumIntAssociations.java
lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/TaxonomyFacetSumValueSource.java
lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/TaxonomyFacets.java
lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/package.html
Modified: lucene/dev/branches/lucene5339/TODO
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5339/TODO?rev=1546008&r1=1546007&r2=1546008&view=diff
==============================================================================
--- lucene/dev/branches/lucene5339/TODO (original)
+++ lucene/dev/branches/lucene5339/TODO Wed Nov 27 12:07:30 2013
@@ -4,7 +4,6 @@ TODO
- allow path.length==0?
- make a variant/sugar of FacetsConfig.build that just updates an existing doc?
- need test coverage of utility search methods
- - move DocumentBuilder.build -> FacetsConfig.build
- getSpecificValue for a dim isn't reliable
- we could put more stuff into the "schema", e.g. this field is
sorted-set-DV and that one is taxo?
Modified: lucene/dev/branches/lucene5339/lucene/build.xml
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5339/lucene/build.xml?rev=1546008&r1=1546007&r2=1546008&view=diff
==============================================================================
--- lucene/dev/branches/lucene5339/lucene/build.xml (original)
+++ lucene/dev/branches/lucene5339/lucene/build.xml Wed Nov 27 12:07:30 2013
@@ -240,7 +240,7 @@
<!-- core: problems -->
<check-missing-javadocs dir="build/docs/demo" level="method"/>
<check-missing-javadocs dir="build/docs/expressions" level="method"/>
- <!-- facet: problems -->
+ <check-missing-javadocs dir="build/docs/facet" level="method"/>
<!-- grouping: problems -->
<!-- highlighter: problems -->
<check-missing-javadocs dir="build/docs/join" level="method"/>
Modified: lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/AssociationFacetField.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/AssociationFacetField.java?rev=1546008&r1=1546007&r2=1546008&view=diff
==============================================================================
--- lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/AssociationFacetField.java (original)
+++ lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/AssociationFacetField.java Wed Nov 27 12:07:30 2013
@@ -19,12 +19,20 @@ package org.apache.lucene.facet;
import java.util.Arrays;
+import org.apache.lucene.document.Document; // javadocs
import org.apache.lucene.document.Field;
import org.apache.lucene.document.FieldType;
import org.apache.lucene.util.BytesRef;
-/** Associates an arbitrary byte[] with the added facet
- * path. */
+/** Add an instance of this to your {@link Document} to add
+ * a facet label associated with an arbitrary byte[].
+ * This will require a custom {@link Facets}
+ * implementation at search time; see {@link
+ * IntAssociationFacetField} and {@link
+ * FloatAssociationFacetField} to use existing {@link
+ * Facets} implementations.
+ *
+ * @lucene.experimental */
public class AssociationFacetField extends Field {
static final FieldType TYPE = new FieldType();
static {
@@ -35,6 +43,8 @@ public class AssociationFacetField exten
protected final String[] path;
protected final BytesRef assoc;
+ /** Creates this from {@code dim} and {@code path} and an
+ * association */
public AssociationFacetField(BytesRef assoc, String dim, String... path) {
super("dummy", TYPE);
this.dim = dim;
Modified: lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/CachedOrdinalsReader.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/CachedOrdinalsReader.java?rev=1546008&r1=1546007&r2=1546008&view=diff
==============================================================================
--- lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/CachedOrdinalsReader.java (original)
+++ lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/CachedOrdinalsReader.java Wed Nov 27 12:07:30 2013
@@ -21,7 +21,9 @@ import java.io.IOException;
import java.util.Map;
import java.util.WeakHashMap;
+import org.apache.lucene.codecs.DocValuesFormat; // javadocs
import org.apache.lucene.index.AtomicReaderContext;
+import org.apache.lucene.index.BinaryDocValues; // javadocs
import org.apache.lucene.util.ArrayUtil;
import org.apache.lucene.util.BytesRef;
import org.apache.lucene.util.IntsRef;
Modified: lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/DrillDownQuery.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/DrillDownQuery.java?rev=1546008&r1=1546007&r2=1546008&view=diff
==============================================================================
--- lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/DrillDownQuery.java (original)
+++ lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/DrillDownQuery.java Wed Nov 27 12:07:30 2013
@@ -33,14 +33,14 @@ import org.apache.lucene.search.Constant
import org.apache.lucene.search.Filter;
import org.apache.lucene.search.FilteredQuery;
import org.apache.lucene.search.MatchAllDocsQuery;
+import org.apache.lucene.search.NumericRangeQuery; // javadocs
import org.apache.lucene.search.Query;
import org.apache.lucene.search.TermQuery;
/**
- * A {@link Query} for drill-down over {@link FacetLabel categories}. You
- * should call {@link #add(FacetLabel...)} for every group of categories you
- * want to drill-down over. Each category in the group is {@code OR'ed} with
- * the others, and groups are {@code AND'ed}.
+ * A {@link Query} for drill-down over facet categories. You
+ * should call {@link #add(String, String...)} for every group of categories you
+ * want to drill-down over.
* <p>
* <b>NOTE:</b> if you choose to create your own {@link Query} by calling
* {@link #term}, it is recommended to wrap it with {@link ConstantScoreQuery}
@@ -51,6 +51,7 @@ import org.apache.lucene.search.TermQuer
*/
public final class DrillDownQuery extends Query {
+ /** Creates a drill-down term. */
public static Term term(String field, String dim, String... path) {
return new Term(field, FacetsConfig.pathToString(dim, path));
}
@@ -96,21 +97,17 @@ public final class DrillDownQuery extend
this.config = config;
}
- /**
- * Creates a new {@code DrillDownQuery} without a base query,
- * to perform a pure browsing query (equivalent to using
- * {@link MatchAllDocsQuery} as base).
- */
+ /** Creates a new {@code DrillDownQuery} without a base query,
+ * to perform a pure browsing query (equivalent to using
+ * {@link MatchAllDocsQuery} as base). */
public DrillDownQuery(FacetsConfig config) {
this(config, null);
}
- /**
- * Creates a new {@code DrillDownQuery} over the given base query. Can be
- * {@code null}, in which case the result {@link Query} from
- * {@link #rewrite(IndexReader)} will be a pure browsing query, filtering on
- * the added categories only.
- */
+ /** Creates a new {@code DrillDownQuery} over the given base query. Can be
+ * {@code null}, in which case the result {@link Query} from
+ * {@link #rewrite(IndexReader)} will be a pure browsing query, filtering on
+ * the added categories only. */
public DrillDownQuery(FacetsConfig config, Query baseQuery) {
query = new BooleanQuery(true); // disable coord
if (baseQuery != null) {
@@ -139,10 +136,9 @@ public final class DrillDownQuery extend
}
/** Adds one dimension of drill downs; if you pass the same
- * dimension again, it's OR'd with the previous
- * constraints on that dimension, and all dimensions are
+ * dimension more than once it is OR'd with the previous
+ * cofnstraints on that dimension, and all dimensions are
* AND'd against each other and the base query. */
- // nocommit can we remove FacetLabel here?
public void add(String dim, String... path) {
if (drillDownDims.containsKey(dim)) {
@@ -165,7 +161,9 @@ public final class DrillDownQuery extend
/** Expert: add a custom drill-down subQuery. Use this
* when you have a separate way to drill-down on the
- * dimension than the indexed facet ordinals. */
+ * dimension than the indexed facet ordinals (for
+ * example, use a {@link NumericRangeQuery} to drill down
+ * after{@link RangeFacetCounts}. */
public void add(String dim, Query subQuery) {
// TODO: we should use FilteredQuery?
Modified: lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/DrillSideways.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/DrillSideways.java?rev=1546008&r1=1546007&r2=1546008&view=diff
==============================================================================
--- lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/DrillSideways.java (original)
+++ lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/DrillSideways.java Wed Nov 27 12:07:30 2013
@@ -65,7 +65,6 @@ import org.apache.lucene.search.Weight;
*
* @lucene.experimental
*/
-
public class DrillSideways {
protected final IndexSearcher searcher;
@@ -73,27 +72,21 @@ public class DrillSideways {
protected final SortedSetDocValuesReaderState state;
protected final FacetsConfig config;
- /**
- * Create a new {@code DrillSideways} instance, assuming the categories were
- * indexed with {@link FacetFields}.
- */
+ /** Create a new {@code DrillSideways} instance. */
public DrillSideways(IndexSearcher searcher, FacetsConfig config, TaxonomyReader taxoReader) {
this(searcher, config, taxoReader, null);
}
- /**
- * Create a new {@code DrillSideways} instance, assuming the categories were
- * indexed with {@link SortedSetDocValuesFacetFields}.
- */
+ /** Create a new {@code DrillSideways} instance, assuming the categories were
+ * indexed with {@link SortedSetDocValuesFacetField}. */
public DrillSideways(IndexSearcher searcher, FacetsConfig config, SortedSetDocValuesReaderState state) {
this(searcher, config, null, state);
}
- /**
- * Create a new {@code DrillSideways} instance, where some
- * dimensions are sorted set facets and others are
- * taxononmy facets.
- */
+ /** Create a new {@code DrillSideways} instance, where some
+ * dimensions were indexed with {@link
+ * SortedSetDocValuesFacetField} and others were indexed
+ * with {@link FacetField}. */
public DrillSideways(IndexSearcher searcher, FacetsConfig config, TaxonomyReader taxoReader, SortedSetDocValuesReaderState state) {
this.searcher = searcher;
this.config = config;
Modified: lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/FacetField.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/FacetField.java?rev=1546008&r1=1546007&r2=1546008&view=diff
==============================================================================
--- lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/FacetField.java (original)
+++ lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/FacetField.java Wed Nov 27 12:07:30 2013
@@ -19,20 +19,27 @@ package org.apache.lucene.facet;
import java.util.Arrays;
+import org.apache.lucene.document.Document; // javadoc
import org.apache.lucene.document.Field;
import org.apache.lucene.document.FieldType;
-/** Add an instance of this to your Document for every facet
- * label. */
+/** Add an instance of this to your {@link Document} for
+ * every facet label. */
public class FacetField extends Field {
static final FieldType TYPE = new FieldType();
static {
TYPE.setIndexed(true);
TYPE.freeze();
}
+
+ /** Dimension for this field. */
public final String dim;
+
+ /** Path for this field. */
public final String[] path;
+ /** Creates the this from {@code dim} and
+ * {@code path}. */
public FacetField(String dim, String... path) {
super("dummy", TYPE);
this.dim = dim;
Modified: lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/FacetResult.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/FacetResult.java?rev=1546008&r1=1546007&r2=1546008&view=diff
==============================================================================
--- lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/FacetResult.java (original)
+++ lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/FacetResult.java Wed Nov 27 12:07:30 2013
@@ -27,8 +27,7 @@ public final class FacetResult {
* the topN. */
public final Number value;
- /** How many labels were populated under the requested
- * path. */
+ /** How many child labels were encountered. */
public final int childCount;
/** Child counts. */
Modified: lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/Facets.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/Facets.java?rev=1546008&r1=1546007&r2=1546008&view=diff
==============================================================================
--- lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/Facets.java (original)
+++ lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/Facets.java Wed Nov 27 12:07:30 2013
@@ -31,21 +31,25 @@ import org.apache.lucene.search.TopField
import org.apache.lucene.search.TopFieldDocs;
import org.apache.lucene.search.TopScoreDocCollector;
+/** Common base class for all facets implementations.
+ *
+ * @lucene.experimental */
public abstract class Facets {
/** Returns the topN child labels under the specified
* path. Returns null if the specified path doesn't
- * exist. */
+ * exist or if this dimension was never seen. */
public abstract FacetResult getTopChildren(int topN, String dim, String... path) throws IOException;
- /** Return the count for a specific path. Returns -1 if
+ /** Return the count or value
+ * for a specific path. Returns -1 if
* this path doesn't exist, else the count. */
public abstract Number getSpecificValue(String dim, String... path) throws IOException;
/** Returns topN labels for any dimension that had hits,
* sorted by the number of hits that dimension matched;
* this is used for "sparse" faceting, where many
- * different dimensions were indexed depending on the
- * type of document. */
+ * different dimensions were indexed, for example
+ * depending on the type of document. */
public abstract List<FacetResult> getAllDims(int topN) throws IOException;
// nocommit where to move?
@@ -55,7 +59,7 @@ public abstract class Facets {
* also collect results into a {@link
* FacetsCollector} for faceting. */
public static TopDocs search(IndexSearcher searcher, Query q, int topN, FacetsCollector sfc) throws IOException {
- // nocommit can we pass the "right" boolean for
+ // TODO: can we pass the "right" boolean for
// in-order...? we'd need access to the protected
// IS.search methods taking Weight... could use
// reflection...
Modified: lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/FacetsConfig.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/FacetsConfig.java?rev=1546008&r1=1546007&r2=1546008&view=diff
==============================================================================
--- lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/FacetsConfig.java (original)
+++ lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/FacetsConfig.java Wed Nov 27 12:07:30 2013
@@ -41,15 +41,16 @@ import org.apache.lucene.util.ArrayUtil;
import org.apache.lucene.util.BytesRef;
import org.apache.lucene.util.IntsRef;
-/** By default a dimension is flat, single valued and does
+/** Records per-dimension configuration. By default a
+ * dimension is flat, single valued and does
* not require count for the dimension; use
* the setters in this class to change these settings for
- * any dims.
+ * each dim.
*
* <p><b>NOTE</b>: this configuration is not saved into the
* index, but it's vital, and up to the application to
- * ensure, that at search time the provided FacetsConfig
- * matches what was used during indexing.
+ * ensure, that at search time the provided {@code
+ * FacetsConfig} matches what was used during indexing.
*
* @lucene.experimental */
public class FacetsConfig {
@@ -64,7 +65,9 @@ public class FacetsConfig {
private final TaxonomyWriter taxoWriter;
- /** @lucene.internal */
+ /** Holds the configuration for one dimension
+ *
+ * @lucene.experimental */
// nocommit expose this to the user, vs the setters?
public static final class DimConfig {
/** True if this dimension is hierarchical. */
@@ -82,16 +85,22 @@ public class FacetsConfig {
String indexFieldName = DEFAULT_INDEX_FIELD_NAME;
}
+ /** Default per-dimension configuration. */
+ public final static DimConfig DEFAULT_DIM_CONFIG = new DimConfig();
+
+ /** Default constructor. */
public FacetsConfig() {
this(null);
}
+ /** Use this constructor at index time, with the provided
+ * {@link TaxonomyWriter}, and then use the {@link
+ * #build} method to index documents. */
public FacetsConfig(TaxonomyWriter taxoWriter) {
this.taxoWriter = taxoWriter;
}
- public final static DimConfig DEFAULT_DIM_CONFIG = new DimConfig();
-
+ /** Get the current configuration for a dimension. */
public DimConfig getDimConfig(String dimName) {
DimConfig ft = fieldTypes.get(dimName);
if (ft == null) {
@@ -100,7 +109,8 @@ public class FacetsConfig {
return ft;
}
- // nocommit maybe setDimConfig instead?
+ /** Pass {@code true} if this dimension is hierarchical
+ * (has depth > 1 paths). */
public synchronized void setHierarchical(String dimName, boolean v) {
DimConfig ft = fieldTypes.get(dimName);
if (ft == null) {
@@ -110,6 +120,8 @@ public class FacetsConfig {
ft.hierarchical = v;
}
+ /** Pass {@code true} if this dimension may have more than
+ * one value per document. */
public synchronized void setMultiValued(String dimName, boolean v) {
DimConfig ft = fieldTypes.get(dimName);
if (ft == null) {
@@ -119,6 +131,9 @@ public class FacetsConfig {
ft.multiValued = v;
}
+ /** Pass {@code true} if at search time you require
+ * accurate counts of the dimension, i.e. how many
+ * hits have this dimension. */
public synchronized void setRequireDimCount(String dimName, boolean v) {
DimConfig ft = fieldTypes.get(dimName);
if (ft == null) {
@@ -128,6 +143,9 @@ public class FacetsConfig {
ft.requireDimCount = v;
}
+ /** Specify which index field name should hold the
+ * ordinals for this dimension; this is only used by the
+ * taxonomy based facet methods. */
public synchronized void setIndexFieldName(String dimName, String indexFieldName) {
DimConfig ft = fieldTypes.get(dimName);
if (ft == null) {
@@ -149,7 +167,7 @@ public class FacetsConfig {
}
/** Translates any added {@link FacetField}s into normal
- * fields for indexing */
+ * fields for indexing. */
public IndexDocument build(IndexDocument doc) throws IOException {
// Find all FacetFields, collated by the actual field:
Map<String,List<FacetField>> byField = new HashMap<String,List<FacetField>>();
@@ -442,8 +460,7 @@ public class FacetsConfig {
// Escapes any occurrence of the path component inside the label:
private static final char ESCAPE_CHAR = '\u001E';
- /** Turns a path into a string without stealing any
- * characters. */
+ /** Turns a dim + path into an encoded string. */
public static String pathToString(String dim, String[] path) {
String[] fullPath = new String[1+path.length];
fullPath[0] = dim;
@@ -451,10 +468,13 @@ public class FacetsConfig {
return pathToString(fullPath, fullPath.length);
}
+ /** Turns a dim + path into an encoded string. */
public static String pathToString(String[] path) {
return pathToString(path, path.length);
}
+ /** Turns the first {@code} length elements of {@code
+ * path} into an encoded string. */
public static String pathToString(String[] path, int length) {
// nocommit .... too anal? shouldn't we allow drill
// down on just dim, to get all docs that have that
@@ -486,9 +506,9 @@ public class FacetsConfig {
return sb.toString();
}
- /** Turns a result from previous call to {@link
- * #pathToString} back into the original {@code String[]}
- * without stealing any characters. */
+ /** Turns an encoded string (from a previous call to {@link
+ * #pathToString}) back into the original {@code
+ * String[]}. */
public static String[] stringToPath(String s) {
List<String> parts = new ArrayList<String>();
int length = s.length();
Modified: lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/FastTaxonomyFacetCounts.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/FastTaxonomyFacetCounts.java?rev=1546008&r1=1546007&r2=1546008&view=diff
==============================================================================
--- lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/FastTaxonomyFacetCounts.java (original)
+++ lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/FastTaxonomyFacetCounts.java Wed Nov 27 12:07:30 2013
@@ -28,14 +28,24 @@ import org.apache.lucene.index.BinaryDoc
import org.apache.lucene.util.BytesRef;
import org.apache.lucene.util.FixedBitSet;
-// nocommit jdoc that this assumes/requires the default encoding
+/** Computes facets counts, assuming the default encoding
+ * into DocValues was used.
+ *
+ * @lucene.experimental */
public class FastTaxonomyFacetCounts extends TaxonomyFacets {
private final int[] counts;
+ /** Create {@code FastTaxonomyFacetCounts}, which also
+ * counts all facet labels. */
public FastTaxonomyFacetCounts(TaxonomyReader taxoReader, FacetsConfig config, FacetsCollector fc) throws IOException {
this(FacetsConfig.DEFAULT_INDEX_FIELD_NAME, taxoReader, config, fc);
}
+ /** Create {@code FastTaxonomyFacetCounts}, using the
+ * specified {@code indexFieldName} for ordinals. Use
+ * this if you had set {@link
+ * FacetsConfig#setIndexFieldName} to change the index
+ * field name for certain dimensions. */
public FastTaxonomyFacetCounts(String indexFieldName, TaxonomyReader taxoReader, FacetsConfig config, FacetsCollector fc) throws IOException {
super(indexFieldName, taxoReader, config);
counts = new int[taxoReader.getSize()];
@@ -106,8 +116,6 @@ public class FastTaxonomyFacetCounts ext
return sum;
}
- /** Return the count for a specific path. Returns -1 if
- * this path doesn't exist, else the count. */
@Override
public Number getSpecificValue(String dim, String... path) throws IOException {
verifyDim(dim);
@@ -120,6 +128,7 @@ public class FastTaxonomyFacetCounts ext
@Override
public FacetResult getTopChildren(int topN, String dim, String... path) throws IOException {
+ // TODO: can we factor this out?
if (topN <= 0) {
throw new IllegalArgumentException("topN must be > 0 (got: " + topN + ")");
}
Modified: lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/FloatAssociationFacetField.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/FloatAssociationFacetField.java?rev=1546008&r1=1546007&r2=1546008&view=diff
==============================================================================
--- lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/FloatAssociationFacetField.java (original)
+++ lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/FloatAssociationFacetField.java Wed Nov 27 12:07:30 2013
@@ -19,24 +19,31 @@ package org.apache.lucene.facet;
import java.util.Arrays;
+import org.apache.lucene.document.Document; // javadocs
import org.apache.lucene.document.Field;
import org.apache.lucene.document.FieldType;
import org.apache.lucene.util.BytesRef;
-/** Associates an arbitrary float with the added facet
- * path, encoding the float into a 4-byte BytesRef. */
+/** Add an instance of this to your {@link Document} to add
+ * a facet label associated with a float. Use {@link
+ * TaxonomyFacetSumFloatAssociations} to aggregate float values
+ * per facet label at search time.
+ *
+ * @lucene.experimental */
public class FloatAssociationFacetField extends AssociationFacetField {
- /** Utility ctor: associates an int value (translates it
- * to 4-byte BytesRef). */
+ /** Creates this from {@code dim} and {@code path} and a
+ * float association */
public FloatAssociationFacetField(float assoc, String dim, String... path) {
super(floatToBytesRef(assoc), dim, path);
}
+ /** Encodes a {@code float} as a 4-byte {@link BytesRef}. */
public static BytesRef floatToBytesRef(float v) {
return IntAssociationFacetField.intToBytesRef(Float.floatToIntBits(v));
}
+ /** Decodes a previously encoded {@code float}. */
public static float bytesRefToFloat(BytesRef b) {
return Float.intBitsToFloat(IntAssociationFacetField.bytesRefToInt(b));
}
Modified: lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/IntAssociationFacetField.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/IntAssociationFacetField.java?rev=1546008&r1=1546007&r2=1546008&view=diff
==============================================================================
--- lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/IntAssociationFacetField.java (original)
+++ lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/IntAssociationFacetField.java Wed Nov 27 12:07:30 2013
@@ -19,20 +19,27 @@ package org.apache.lucene.facet;
import java.util.Arrays;
+import org.apache.lucene.document.Document; // javadocs
import org.apache.lucene.document.Field;
import org.apache.lucene.document.FieldType;
import org.apache.lucene.util.BytesRef;
-/** Associates an arbitrary int with the added facet
- * path, encoding the int into a 4-byte BytesRef. */
+/** Add an instance of this to your {@link Document} to add
+ * a facet label associated with an int. Use {@link
+ * TaxonomyFacetSumIntAssociations} to aggregate int values
+ * per facet label at search time.
+ *
+ * @lucene.experimental */
public class IntAssociationFacetField extends AssociationFacetField {
- /** Utility ctor: associates an int value (translates it
- * to 4-byte BytesRef). */
+ /** Creates this from {@code dim} and {@code path} and an
+ * int association */
public IntAssociationFacetField(int assoc, String dim, String... path) {
super(intToBytesRef(assoc), dim, path);
}
+ /** Encodes an {@code int} as a 4-byte {@link BytesRef},
+ * big-endian. */
public static BytesRef intToBytesRef(int v) {
byte[] bytes = new byte[4];
// big-endian:
@@ -43,6 +50,7 @@ public class IntAssociationFacetField ex
return new BytesRef(bytes);
}
+ /** Decodes a previously encoded {@code int}. */
public static int bytesRefToInt(BytesRef b) {
return ((b.bytes[b.offset]&0xFF) << 24) |
((b.bytes[b.offset+1]&0xFF) << 16) |
Modified: lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/LabelAndValue.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/LabelAndValue.java?rev=1546008&r1=1546007&r2=1546008&view=diff
==============================================================================
--- lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/LabelAndValue.java (original)
+++ lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/LabelAndValue.java Wed Nov 27 12:07:30 2013
@@ -43,5 +43,8 @@ public final class LabelAndValue {
return label.equals(other.label) && value.equals(other.value);
}
- // nocommit hashCode
+ @Override
+ public int hashCode() {
+ return label.hashCode() + 1439 * value.hashCode();
+ }
}
Modified: lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/Range.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/Range.java?rev=1546008&r1=1546007&r2=1546008&view=diff
==============================================================================
--- lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/Range.java (original)
+++ lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/Range.java Wed Nov 27 12:07:30 2013
@@ -17,11 +17,10 @@ package org.apache.lucene.facet;
* limitations under the License.
*/
-/** Represents a single labelled range, one facet label in
- * the facets computed by {@link RangeAccumulator}.
+/** Represents a single labeled range, one facet label in
+ * the facets computed by {@link RangeFacetCounts}.
*
* @lucene.experimental */
-
public abstract class Range {
public final String label;
Modified: lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/RangeFacetCounts.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/RangeFacetCounts.java?rev=1546008&r1=1546007&r2=1546008&view=diff
==============================================================================
--- lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/RangeFacetCounts.java (original)
+++ lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/RangeFacetCounts.java Wed Nov 27 12:07:30 2013
@@ -27,19 +27,28 @@ import org.apache.lucene.queries.functio
import org.apache.lucene.queries.function.ValueSource;
import org.apache.lucene.queries.function.valuesource.LongFieldSource;
-/**
- * accumulates counts for provided ranges.
- */
+/** {@link Facets} implementation that computes counts for
+ * dynamic ranges from a provided {@link ValueSource}. Use
+ * this for dimensions that change in real-time (e.g. a
+ * relative time based dimension like "Past day", "Past 2
+ * days", etc.) or that change for each user (e.g. a
+ * distance dimension like "< 1 km", "< 2 km", etc.).
+ *
+ * @lucene.experimental */
public class RangeFacetCounts extends Facets {
private final Range[] ranges;
private final int[] counts;
private final String field;
private int totCount;
+ /** Create {@code RangeFacetCounts}, using {@link
+ * LongFieldSource} from the specified field. */
public RangeFacetCounts(String field, FacetsCollector hits, Range... ranges) throws IOException {
this(field, new LongFieldSource(field), hits, ranges);
}
+ /** Create {@code RangeFacetCounts}, using the provided
+ * {@link ValueSource}. */
public RangeFacetCounts(String field, ValueSource valueSource, FacetsCollector hits, Range... ranges) throws IOException {
this.ranges = ranges;
this.field = field;
Modified: lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/SortedSetDocValuesReaderState.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/SortedSetDocValuesReaderState.java?rev=1546008&r1=1546007&r2=1546008&view=diff
==============================================================================
--- lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/SortedSetDocValuesReaderState.java (original)
+++ lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/SortedSetDocValuesReaderState.java Wed Nov 27 12:07:30 2013
@@ -71,13 +71,14 @@ public final class SortedSetDocValuesRea
private final Map<String,OrdRange> prefixToOrdRange = new HashMap<String,OrdRange>();
+ /** Creates this, pulling doc values from the default {@link
+ * FacetsConfig#DEFAULT_INDEX_FIELD_NAME}. */
public SortedSetDocValuesReaderState(IndexReader reader) throws IOException {
this(reader, FacetsConfig.DEFAULT_INDEX_FIELD_NAME);
}
- /** Create an instance, scanning the {@link
- * SortedSetDocValues} from the provided reader, with
- * default {@link FacetIndexingParams}. */
+ /** Creates this, pulling doc values from the specified
+ * field. */
public SortedSetDocValuesReaderState(IndexReader reader, String field) throws IOException {
this.field = field;
Modified: lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/TaxonomyFacetCounts.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/TaxonomyFacetCounts.java?rev=1546008&r1=1546007&r2=1546008&view=diff
==============================================================================
--- lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/TaxonomyFacetCounts.java (original)
+++ lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/TaxonomyFacetCounts.java Wed Nov 27 12:07:30 2013
@@ -30,13 +30,19 @@ import org.apache.lucene.util.IntsRef;
/** Reads from any {@link OrdinalsReader}; use {@link
* FastTaxonomyFacetCounts} if you are just using the
- * default encoding from {@link BinaryDocValues}. */
+ * default encoding from {@link BinaryDocValues}.
+ *
+ * @lucene.experimental */
// nocommit remove & add specialized Cached variation only?
public class TaxonomyFacetCounts extends TaxonomyFacets {
private final OrdinalsReader ordinalsReader;
private final int[] counts;
+ /** Create {@code TaxonomyFacetCounts}, which also
+ * counts all facet labels. Use this for a non-default
+ * {@link OrdinalsReader}; otherwise use {@link
+ * FastTaxonomyFacetCounts}. */
public TaxonomyFacetCounts(OrdinalsReader ordinalsReader, TaxonomyReader taxoReader, FacetsConfig config, FacetsCollector fc) throws IOException {
super(ordinalsReader.getIndexFieldName(), taxoReader, config);
this.ordinalsReader = ordinalsReader;
@@ -89,8 +95,6 @@ public class TaxonomyFacetCounts extends
return sum;
}
- /** Return the count for a specific path. Returns -1 if
- * this path doesn't exist, else the count. */
@Override
public Number getSpecificValue(String dim, String... path) throws IOException {
verifyDim(dim);
@@ -103,6 +107,7 @@ public class TaxonomyFacetCounts extends
@Override
public FacetResult getTopChildren(int topN, String dim, String... path) throws IOException {
+ // TODO: can we factor this out?
if (topN <= 0) {
throw new IllegalArgumentException("topN must be > 0 (got: " + topN + ")");
}
Modified: lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/TaxonomyFacetSumFloatAssociations.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/TaxonomyFacetSumFloatAssociations.java?rev=1546008&r1=1546007&r2=1546008&view=diff
==============================================================================
--- lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/TaxonomyFacetSumFloatAssociations.java (original)
+++ lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/TaxonomyFacetSumFloatAssociations.java Wed Nov 27 12:07:30 2013
@@ -27,14 +27,22 @@ import org.apache.lucene.index.BinaryDoc
import org.apache.lucene.util.BytesRef;
import org.apache.lucene.util.FixedBitSet;
-// nocommit jdoc that this assumes/requires the default encoding
+/** Aggregates sum of int values previously indexed with
+ * {@link FloatAssociationFacetField}, assuming the default
+ * encoding.
+ *
+ * @lucene.experimental */
public class TaxonomyFacetSumFloatAssociations extends TaxonomyFacets {
private final float[] values;
+ /** Create {@code TaxonomyFacetSumFloatAssociations} against
+ * the default index field. */
public TaxonomyFacetSumFloatAssociations(TaxonomyReader taxoReader, FacetsConfig config, FacetsCollector fc) throws IOException {
this(FacetsConfig.DEFAULT_INDEX_FIELD_NAME, taxoReader, config, fc);
}
+ /** Create {@code TaxonomyFacetSumFloatAssociations} against
+ * the specified index field. */
public TaxonomyFacetSumFloatAssociations(String indexFieldName, TaxonomyReader taxoReader, FacetsConfig config, FacetsCollector fc) throws IOException {
super(indexFieldName, taxoReader, config);
values = new float[taxoReader.getSize()];
@@ -80,8 +88,6 @@ public class TaxonomyFacetSumFloatAssoci
}
}
- /** Return the count for a specific path. Returns -1 if
- * this path doesn't exist, else the count. */
@Override
public Number getSpecificValue(String dim, String... path) throws IOException {
verifyDim(dim);
@@ -94,6 +100,7 @@ public class TaxonomyFacetSumFloatAssoci
@Override
public FacetResult getTopChildren(int topN, String dim, String... path) throws IOException {
+ // TODO: can we factor this out?
if (topN <= 0) {
throw new IllegalArgumentException("topN must be > 0 (got: " + topN + ")");
}
Modified: lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/TaxonomyFacetSumIntAssociations.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/TaxonomyFacetSumIntAssociations.java?rev=1546008&r1=1546007&r2=1546008&view=diff
==============================================================================
--- lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/TaxonomyFacetSumIntAssociations.java (original)
+++ lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/TaxonomyFacetSumIntAssociations.java Wed Nov 27 12:07:30 2013
@@ -27,14 +27,22 @@ import org.apache.lucene.index.BinaryDoc
import org.apache.lucene.util.BytesRef;
import org.apache.lucene.util.FixedBitSet;
-// nocommit jdoc that this assumes/requires the default encoding
+/** Aggregates sum of int values previously indexed with
+ * {@link IntAssociationFacetField}, assuming the default
+ * encoding.
+ *
+ * @lucene.experimental */
public class TaxonomyFacetSumIntAssociations extends TaxonomyFacets {
private final int[] values;
+ /** Create {@code TaxonomyFacetSumIntAssociations} against
+ * the default index field. */
public TaxonomyFacetSumIntAssociations(TaxonomyReader taxoReader, FacetsConfig config, FacetsCollector fc) throws IOException {
this(FacetsConfig.DEFAULT_INDEX_FIELD_NAME, taxoReader, config, fc);
}
+ /** Create {@code TaxonomyFacetSumIntAssociations} against
+ * the specified index field. */
public TaxonomyFacetSumIntAssociations(String indexFieldName, TaxonomyReader taxoReader, FacetsConfig config, FacetsCollector fc) throws IOException {
super(indexFieldName, taxoReader, config);
values = new int[taxoReader.getSize()];
@@ -80,8 +88,6 @@ public class TaxonomyFacetSumIntAssociat
}
}
- /** Return the count for a specific path. Returns -1 if
- * this path doesn't exist, else the count. */
@Override
public Number getSpecificValue(String dim, String... path) throws IOException {
verifyDim(dim);
@@ -94,6 +100,7 @@ public class TaxonomyFacetSumIntAssociat
@Override
public FacetResult getTopChildren(int topN, String dim, String... path) throws IOException {
+ // TODO: can we factor this out?
if (topN <= 0) {
throw new IllegalArgumentException("topN must be > 0 (got: " + topN + ")");
}
Modified: lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/TaxonomyFacetSumValueSource.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/TaxonomyFacetSumValueSource.java?rev=1546008&r1=1546007&r2=1546008&view=diff
==============================================================================
--- lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/TaxonomyFacetSumValueSource.java (original)
+++ lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/TaxonomyFacetSumValueSource.java Wed Nov 27 12:07:30 2013
@@ -34,8 +34,9 @@ import org.apache.lucene.util.FixedBitSe
import org.apache.lucene.util.IntsRef;
/** Aggregates sum of values from a {@link ValueSource}, for
- * each facet label. */
-
+ * each facet label.
+ *
+ * @lucene.experimental */
public class TaxonomyFacetSumValueSource extends TaxonomyFacets {
private final float[] values;
private final OrdinalsReader ordinalsReader;
@@ -141,6 +142,7 @@ public class TaxonomyFacetSumValueSource
@Override
public FacetResult getTopChildren(int topN, String dim, String... path) throws IOException {
+ // TODO: can we factor this out?
if (topN <= 0) {
throw new IllegalArgumentException("topN must be > 0 (got: " + topN + ")");
}
Modified: lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/TaxonomyFacets.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/TaxonomyFacets.java?rev=1546008&r1=1546007&r2=1546008&view=diff
==============================================================================
--- lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/TaxonomyFacets.java (original)
+++ lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/TaxonomyFacets.java Wed Nov 27 12:07:30 2013
@@ -27,23 +27,19 @@ import org.apache.lucene.facet.taxonomy.
import org.apache.lucene.facet.taxonomy.TaxonomyReader;
/** Base class for all taxonomy-based facets impls. */
-abstract class TaxonomyFacets extends Facets {
+public abstract class TaxonomyFacets extends Facets {
protected final String indexFieldName;
protected final TaxonomyReader taxoReader;
protected final FacetsConfig config;
protected final int[] children;
- protected final int[] parents;
protected final int[] siblings;
- /** Sole parameter is the field name that holds the facet
- * counts. */
protected TaxonomyFacets(String indexFieldName, TaxonomyReader taxoReader, FacetsConfig config) throws IOException {
this.indexFieldName = indexFieldName;
this.taxoReader = taxoReader;
this.config = config;
ParallelTaxonomyArrays pta = taxoReader.getParallelTaxonomyArrays();
children = pta.children();
- parents = pta.parents();
siblings = pta.siblings();
}
Modified: lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/package.html
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/package.html?rev=1546008&r1=1546007&r2=1546008&view=diff
==============================================================================
--- lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/package.html (original)
+++ lucene/dev/branches/lucene5339/lucene/facet/src/java/org/apache/lucene/facet/package.html Wed Nov 27 12:07:30 2013
@@ -21,4 +21,16 @@
<body>
<h1>faceted search</h1>
</body>
-</html>
\ No newline at end of file
+ <p>
+ This module provides multiple methods for computing facet counts and
+ value aggregations.
+ </p>
+ <p>
+ The taxonomy-based methods ({@link FastTaxonomyFacetCounts},
+ {@link TaxonomyFacetSumIntAssociations
+ The Facets.search utility methods are useful for doing an "ordinary"
+ search (sorting by score, or by a specified Sort) but also
+ collecting into a FacetsCollector for subsequent faceting.
+
+ <p>
+</html>