martijnvg commented on code in PR #16286:
URL: https://github.com/apache/lucene/pull/16286#discussion_r3497538545
##########
lucene/core/src/java/org/apache/lucene/index/BinaryDocValues.java:
##########
@@ -33,4 +35,76 @@ protected BinaryDocValues() {}
* @return binary value
*/
public abstract BytesRef binaryValue() throws IOException;
+
+ /**
+ * Bulk retrieval of binary doc values. This API helps reduce the
performance impact of virtual
+ * function calls.
+ *
+ * <p>This API behaves as if implemented as below, which is the default
implementation:
+ *
+ * <pre><code class="language-java">
+ * public void binaryValues(int size, int[] docs, BytesRef[] values) throws
IOException {
+ * for (int i = 0; i < size; ++i) {
+ * int doc = docs[i];
+ * if (advanceExact(doc)) {
+ * values[i] = BytesRef.deepCopyOf(binaryValue());
+ * } else {
+ * values[i] = null;
+ * }
+ * }
+ * }
+ * </code></pre>
+ *
+ * <p><b>NOTE</b>: The {@code docs} array is required to be sorted in
ascending order with no
+ * duplicates.
+ *
+ * <p><b>NOTE</b>: Documents that don't have a value for this field will
have their corresponding
+ * entry set to {@code null}. If you need to exclude documents that don't
have a value, then you
+ * could apply a {@link FieldExistsQuery} as a {@link Occur#FILTER} clause.
Another option is to
+ * fall back to using {@link #advanceExact} and {@link #binaryValue()} on
ranges of doc IDs that
+ * may not be dense, e.g.
+ *
+ * <pre><code class="language-java">
+ * if (size > 0 && values.advanceExact(docs[0]) &&
values.docIDRunEnd() > docs[size - 1]) {
+ * // use values#binaryValues to retrieve values
+ * } else {
+ * // some docs may not have a value, use #advanceExact and #binaryValue
+ * }
+ * </code></pre>
+ *
+ * <p><b>NOTE</b>: Each returned {@link BytesRef} is a deep copy owned by
the caller and remains
+ * valid after subsequent calls.
+ *
+ * @param size the number of values to retrieve
+ * @param docs the buffer of doc IDs whose values should be looked up
+ * @param values the buffer of values to fill; entries are set to {@code
null} when a document
+ * doesn't have a value
+ */
+ public void binaryValues(int size, int[] docs, BytesRef[] values) throws
IOException {
+ binaryValues(size, docs, 0, values, 0);
+ }
+
+ /**
+ * Offset-aware variant of {@link #binaryValues(int, int[], BytesRef[])}.
Reads {@code size} doc
+ * IDs starting at {@code docs[docsOffset]} and writes the corresponding
values starting at {@code
+ * values[valuesOffset]}. This follows the same convention as {@link
System#arraycopy}.
+ *
+ * @param size the number of values to retrieve
+ * @param docs the buffer of doc IDs whose values should be looked up
+ * @param docsOffset first position in {@code docs} to read
+ * @param values the buffer of values to fill; entries are set to {@code
null} when a document
+ * doesn't have a value
+ * @param valuesOffset first position in {@code values} to write
+ */
+ public void binaryValues(
+ int size, int[] docs, int docsOffset, BytesRef[] values, int
valuesOffset)
Review Comment:
I see, I think this makes sense.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
