rmuir commented on code in PR #12054: URL: https://github.com/apache/lucene/pull/12054#discussion_r1097738909
########## lucene/core/src/java/org/apache/lucene/document/KeywordField.java: ########## @@ -0,0 +1,188 @@ +/* + * 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. + */ +package org.apache.lucene.document; + +import java.util.Collection; +import java.util.Objects; +import org.apache.lucene.index.DocValuesType; +import org.apache.lucene.index.IndexOptions; +import org.apache.lucene.index.Term; +import org.apache.lucene.search.ConstantScoreQuery; +import org.apache.lucene.search.Query; +import org.apache.lucene.search.SortField; +import org.apache.lucene.search.SortedSetSelector; +import org.apache.lucene.search.SortedSetSortField; +import org.apache.lucene.search.TermInSetQuery; +import org.apache.lucene.search.TermQuery; +import org.apache.lucene.util.BytesRef; + +/** + * Field that indexes a per-document String or {@link BytesRef} into an inverted index for fast + * filtering, stores values in a columnar fashion using {@link DocValuesType#SORTED_SET} doc values + * for sorting and faceting, and optionally stores values as stored fields for top-hits retrieval. + * This field does not support scoring: queries produce constant scores. If you also need to store + * the value, you should add a separate {@link StoredField} instance. If you need more fine-grained + * control you can use {@link StringField}, {@link SortedDocValuesField} or {@link + * SortedSetDocValuesField}, and {@link StoredField}. + * + * <p>This field defines static factory methods for creating common query objects: + * + * <ul> + * <li>{@link #newExactQuery} for matching a value. + * <li>{@link #newSetQuery} for matching any of the values coming from a set. + * <li>{@link #newSortField} for matching a value. + * </ul> + */ +public class KeywordField extends Field { + + private static final FieldType FIELD_TYPE = new FieldType(); + private static final FieldType FIELD_TYPE_STORED; + + static { + FIELD_TYPE.setIndexOptions(IndexOptions.DOCS); + FIELD_TYPE.setOmitNorms(true); + FIELD_TYPE.setTokenized(false); + FIELD_TYPE.setDocValuesType(DocValuesType.SORTED_SET); + FIELD_TYPE.freeze(); + + FIELD_TYPE_STORED = new FieldType(FIELD_TYPE); + FIELD_TYPE_STORED.setStored(true); + FIELD_TYPE_STORED.freeze(); + } + + private final StoredValue storedValue; + + /** + * Creates a new KeywordField. + * + * @param name field name + * @param value the BytesRef value + * @param stored whether to store the field + * @throws IllegalArgumentException if the field name or value is null. + */ + public KeywordField(String name, BytesRef value, Store stored) { + super(name, value, stored == Field.Store.YES ? FIELD_TYPE_STORED : FIELD_TYPE); + if (stored == Store.YES) { + storedValue = new StoredValue(value); + } else { + storedValue = null; + } + } + + /** + * Creates a new KeywordField from a String value, by indexing its UTF-8 representation. + * + * @param name field name + * @param value the BytesRef value + * @param stored whether to store the field + * @throws IllegalArgumentException if the field name or value is null. + */ + public KeywordField(String name, String value, Store stored) { + super(name, value, stored == Field.Store.YES ? FIELD_TYPE_STORED : FIELD_TYPE); + if (stored == Store.YES) { + storedValue = new StoredValue(value); + } else { + storedValue = null; + } + } + + @Override + public BytesRef binaryValue() { + BytesRef binaryValue = super.binaryValue(); + if (binaryValue != null) { + return binaryValue; + } else { + return new BytesRef(stringValue()); + } + } + + @Override + public void setStringValue(String value) { + super.setStringValue(value); + if (storedValue != null) { + storedValue.setStringValue(value); + } + } + + @Override + public void setBytesValue(BytesRef value) { + super.setBytesValue(value); + if (storedValue != null) { + storedValue.setBinaryValue(value); + } + } + + @Override + public StoredValue storedValue() { + return storedValue; + } + + /** + * Create a query for matching an exact {@link BytesRef} value. + * + * @param field field name. must not be {@code null}. + * @param value exact value + * @throws NullPointerException if {@code field} is null. + * @return a query matching documents with this exact value + */ + public static Query newExactQuery(String field, BytesRef value) { + Objects.requireNonNull(field, "field must not be null"); + Objects.requireNonNull(value, "value must not be null"); + return new ConstantScoreQuery(new TermQuery(new Term(field, value))); + } + + /** + * Create a query for matching an exact {@link String} value. + * + * @param field field name. must not be {@code null}. + * @param value exact value + * @throws NullPointerException if {@code field} is null. + * @return a query matching documents with this exact value + */ + public static Query newExactQuery(String field, String value) { + Objects.requireNonNull(value, "value must not be null"); + return newExactQuery(field, new BytesRef(value)); + } + + /** + * Create a query for matching any of a set of provided {@link BytesRef} values. + * + * @param field field name. must not be {@code null}. + * @param values the set of values to match + * @throws NullPointerException if {@code field} is null. + * @return a query matching documents with this exact value + */ + public static Query newSetQuery(String field, Collection<BytesRef> values) { Review Comment: Can we expose this as `BytesRef...` instead of collection, consistent with all the other `newSetQuery`'s? -- 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: issues-unsubscr...@lucene.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org --------------------------------------------------------------------- To unsubscribe, e-mail: issues-unsubscr...@lucene.apache.org For additional commands, e-mail: issues-h...@lucene.apache.org
