From 7f1eda4736e851e0855d1dbee1c12bbfeeb96086 Mon Sep 17 00:00:00 2001
From: Jordan Powers <jordan.powers@elastic.co>
Date: Thu, 20 Nov 2025 16:58:19 -0800
Subject: [PATCH 01/14] Add doc_values.cardinality paramter to keyword fields

---
 .../index/mapper/FieldMapper.java             | 80 +++++++++++++++++--
 .../index/mapper/KeywordFieldMapper.java      | 61 ++++++++++----
 .../index/mapper/KeywordFieldMapperTests.java | 24 ++++++
 3 files changed, 141 insertions(+), 24 deletions(-)

diff --git a/server/src/main/java/org/elasticsearch/index/mapper/FieldMapper.java b/server/src/main/java/org/elasticsearch/index/mapper/FieldMapper.java
index 14c1232696976..cea39b536e838 100644
--- a/server/src/main/java/org/elasticsearch/index/mapper/FieldMapper.java
+++ b/server/src/main/java/org/elasticsearch/index/mapper/FieldMapper.java
@@ -617,7 +617,7 @@ public Builder add(FieldMapper.Builder builder) {
 
                 if (builder instanceof KeywordFieldMapper.Builder kwd) {
                     if ((kwd.hasNormalizer() == false || kwd.isNormalizerSkipStoreOriginalValue())
-                        && (kwd.hasDocValues() || kwd.isStored())) {
+                        && (kwd.docValuesParameters().enabled || kwd.isStored())) {
                         hasSyntheticSourceCompatibleKeywordField = true;
                     }
                 }
@@ -778,7 +778,7 @@ public interface SerializerCheck<T> {
      * A configurable parameter for a field mapper
      * @param <T> the type of the value the parameter holds
      */
-    public static final class Parameter<T> implements Supplier<T> {
+    public static class Parameter<T> implements Supplier<T> {
 
         public final String name;
         private List<String> deprecatedNames = List.of();
@@ -1405,6 +1405,76 @@ public static Parameter<OnScriptError> onScriptErrorParam(
         }
     }
 
+    public static final class DocValuesParameter extends Parameter<DocValuesParameter.Values> {
+        public static final String PARAMETER_NAME = "doc_values";
+
+        public record Values(boolean enabled, Cardinality cardinality) {
+            public enum Cardinality {
+                LOW,
+                HIGH;
+
+                @Override
+                public String toString() {
+                    return name().toLowerCase(Locale.ROOT);
+                }
+            }
+
+            public static Values DISABLED = new Values(false, Cardinality.LOW);
+        }
+
+        public final Parameter<Values.Cardinality> cardinalityParameter;
+
+        public DocValuesParameter(Values defaultValue, Function<FieldMapper, Values> initializer) {
+            super(PARAMETER_NAME, false, () -> defaultValue, null, initializer, null, Values::toString);
+
+            cardinalityParameter = Parameter.enumParam(
+                "cardinality",
+                false,
+                m -> initializer.apply(m).cardinality,
+                defaultValue.cardinality,
+                Values.Cardinality.class
+            );
+        }
+
+        @Override
+        public void parse(String field, MappingParserContext context, Object value) {
+            if (value instanceof Boolean valueBool) {
+                if (valueBool) {
+                    setValue(getDefaultValue());
+                } else {
+                    setValue(Values.DISABLED);
+                }
+            } else if (value instanceof Map) {
+                @SuppressWarnings("unchecked")
+                Map<String, Object> valueMap = (Map<String, Object>) value;
+                cardinalityParameter.parse(field, context, valueMap.get(cardinalityParameter.name));
+
+                setValue(new Values(true, cardinalityParameter.getValue()));
+            } else {
+                throw new IllegalArgumentException("Illegal value [" + value + "] for parameter [" + name + "]");
+            }
+        }
+
+        @Override
+        public void setValue(Values value) {
+            super.setValue(value);
+            cardinalityParameter.setValue(value.cardinality);
+        }
+
+        protected void toXContent(XContentBuilder builder, boolean includeDefaults) throws IOException {
+            Values value = getValue();
+            if (includeDefaults || isConfigured()) {
+                if (value.enabled == false) {
+                    builder.field(name, false);
+                } else {
+                    builder.startObject(name);
+                    builder.field(cardinalityParameter.name, value.cardinality);
+                    builder.endObject();
+                }
+            }
+        }
+    }
+
     public static final class Conflicts {
 
         private final String mapperName;
@@ -1499,11 +1569,7 @@ protected final void validate() {
         @Override
         public abstract FieldMapper build(MapperBuilderContext context);
 
-        protected void addScriptValidation(
-            Parameter<Script> scriptParam,
-            Parameter<Boolean> indexParam,
-            Parameter<Boolean> docValuesParam
-        ) {
+        protected void addScriptValidation(Parameter<Script> scriptParam, Parameter<Boolean> indexParam, Supplier<Boolean> docValuesParam) {
             scriptParam.addValidator(s -> {
                 if (s != null && indexParam.get() == false && docValuesParam.get() == false) {
                     throw new MapperParsingException("Cannot define script on field with index:false and doc_values:false");
diff --git a/server/src/main/java/org/elasticsearch/index/mapper/KeywordFieldMapper.java b/server/src/main/java/org/elasticsearch/index/mapper/KeywordFieldMapper.java
index 31fd1e404d108..0e97677c58532 100644
--- a/server/src/main/java/org/elasticsearch/index/mapper/KeywordFieldMapper.java
+++ b/server/src/main/java/org/elasticsearch/index/mapper/KeywordFieldMapper.java
@@ -110,6 +110,11 @@ public final class KeywordFieldMapper extends FieldMapper {
     public static final String CONTENT_TYPE = "keyword";
     private static final String HOST_NAME = "host.name";
 
+    private static final DocValuesParameter.Values DEFAULT_DOC_VALUES_PARAMS = new DocValuesParameter.Values(
+        true,
+        DocValuesParameter.Values.Cardinality.LOW
+    );
+
     public static class Defaults {
         public static final FieldType FIELD_TYPE;
         public static final FieldType FIELD_TYPE_WITH_SKIP_DOC_VALUES;
@@ -173,7 +178,10 @@ private static KeywordFieldMapper toType(FieldMapper in) {
     public static final class Builder extends FieldMapper.DimensionBuilder {
 
         private final Parameter<Boolean> indexed;
-        private final Parameter<Boolean> hasDocValues = Parameter.docValuesParam(m -> toType(m).hasDocValues, true);
+        private final DocValuesParameter docValuesParameters = new DocValuesParameter(
+            DEFAULT_DOC_VALUES_PARAMS,
+            m -> toType(m).docValuesParameters()
+        );
         private final Parameter<Boolean> stored = Parameter.storeParam(m -> toType(m).fieldType.stored(), false);
 
         private final Parameter<String> nullValue = Parameter.stringParam("null_value", false, m -> toType(m).fieldType().nullValue, null)
@@ -257,10 +265,12 @@ public Builder(
 
             this.script.precludesParameters(nullValue);
 
-            this.dimension = TimeSeriesParams.dimensionParam(m -> toType(m).fieldType().isDimension(), hasDocValues::get)
-                .precludesParameters(normalizer);
+            this.dimension = TimeSeriesParams.dimensionParam(
+                m -> toType(m).fieldType().isDimension(),
+                () -> docValuesParameters.getValue().enabled()
+            ).precludesParameters(normalizer);
             this.indexed = Parameter.indexParam(m -> toType(m).indexed, indexSettings, dimension);
-            addScriptValidation(script, indexed, hasDocValues);
+            addScriptValidation(script, indexed, () -> docValuesParameters.getValue().enabled());
 
             this.ignoreAbove = Parameter.ignoreAboveParam(
                 m -> toType(m).fieldType().ignoreAbove().get(),
@@ -306,13 +316,14 @@ Builder nullValue(String nullValue) {
             return this;
         }
 
+        @Deprecated()
         public Builder docValues(boolean hasDocValues) {
-            this.hasDocValues.setValue(hasDocValues);
+            this.docValuesParameters.setValue(hasDocValues ? DEFAULT_DOC_VALUES_PARAMS : DocValuesParameter.Values.DISABLED);
             return this;
         }
 
-        public boolean hasDocValues() {
-            return this.hasDocValues.get();
+        public DocValuesParameter.Values docValuesParameters() {
+            return docValuesParameters.getValue();
         }
 
         public SimilarityProvider similarity() {
@@ -354,7 +365,7 @@ private FieldValues<String> scriptValues() {
         protected Parameter<?>[] getParameters() {
             return new Parameter<?>[] {
                 indexed,
-                hasDocValues,
+                docValuesParameters,
                 stored,
                 nullValue,
                 eagerGlobalOrdinals,
@@ -418,7 +429,7 @@ public KeywordFieldMapper build(MapperBuilderContext context) {
             String offsetsFieldName = getOffsetsFieldName(
                 context,
                 indexSettings.sourceKeepMode(),
-                hasDocValues.getValue(),
+                docValuesParameters.get().enabled(),
                 stored.getValue(),
                 this,
                 indexCreatedVersion,
@@ -441,7 +452,17 @@ private FieldType resolveFieldType(final boolean forceDocValuesSkipper, final St
             }
             fieldtype.setOmitNorms(this.hasNorms.getValue() == false);
             fieldtype.setStored(this.stored.getValue());
-            fieldtype.setDocValuesType(this.hasDocValues.getValue() ? DocValuesType.SORTED_SET : DocValuesType.NONE);
+
+            DocValuesParameter.Values docValuesParameters = this.docValuesParameters.get();
+            if (docValuesParameters.enabled() == false) {
+                fieldtype.setDocValuesType(DocValuesType.NONE);
+            } else if (docValuesParameters.cardinality() == DocValuesParameter.Values.Cardinality.HIGH) {
+                fieldtype.setDocValuesType(DocValuesType.BINARY);
+            } else {
+                assert docValuesParameters.cardinality() == DocValuesParameter.Values.Cardinality.LOW;
+                fieldtype.setDocValuesType(DocValuesType.SORTED_SET);
+            }
+
             if (fieldtype.equals(Defaults.FIELD_TYPE_WITH_SKIP_DOC_VALUES) == false) {
                 // NOTE: override index options only if we are not using a sparse doc values index (and we use an inverted index)
                 fieldtype.setIndexOptions(TextParams.toIndexOptions(this.indexed.getValue(), this.indexOptions.getValue()));
@@ -457,11 +478,13 @@ private FieldType resolveFieldType(final boolean forceDocValuesSkipper, final St
         }
 
         private boolean shouldUseTimeSeriesSkipper() {
-            return hasDocValues.get() && indexed.get() == false && useTimeSeriesDocValuesSkippers(indexSettings, dimension.get());
+            return docValuesParameters.getValue().enabled()
+                && indexed.get() == false
+                && useTimeSeriesDocValuesSkippers(indexSettings, dimension.get());
         }
 
         private boolean shouldUseHostnameSkipper(final String fullFieldName) {
-            return hasDocValues.get()
+            return docValuesParameters.getValue().enabled()
                 && IndexSettings.USE_DOC_VALUES_SKIPPER.get(indexSettings.getSettings())
                 && indexSettings.getIndexVersionCreated().onOrAfter(IndexVersions.SKIPPERS_ENABLED_BY_DEFAULT)
                 && IndexMode.LOGSDB.equals(indexSettings.getMode())
@@ -1041,7 +1064,7 @@ public Query automatonQuery(
     }
 
     private final boolean indexed;
-    private final boolean hasDocValues;
+    private final DocValuesParameter.Values docValuesParameters;
     private final String indexOptions;
     private final FieldType fieldType;
     private final String normalizerName;
@@ -1066,7 +1089,7 @@ private KeywordFieldMapper(
         super(simpleName, mappedFieldType, builderParams);
         assert fieldType.indexOptions().compareTo(IndexOptions.DOCS_AND_FREQS) <= 0;
         this.indexed = builder.indexed.getValue();
-        this.hasDocValues = builder.hasDocValues.getValue();
+        this.docValuesParameters = builder.docValuesParameters.getValue();
         this.indexOptions = builder.indexOptions.getValue();
         this.fieldType = freezeAndDeduplicateFieldType(fieldType);
         this.normalizerName = builder.normalizer.getValue();
@@ -1094,6 +1117,10 @@ public boolean isNormalizerSkipStoreOriginalValue() {
         return normalizerSkipStoreOriginalValue;
     }
 
+    public DocValuesParameter.Values docValuesParameters() {
+        return docValuesParameters;
+    }
+
     protected void parseCreateField(DocumentParserContext context) throws IOException {
         var value = context.parser().optimizedTextOrNull();
 
@@ -1273,7 +1300,7 @@ protected SyntheticSourceSupport syntheticSourceSupport() {
             return SyntheticSourceSupport.FALLBACK;
         }
 
-        if (fieldType.stored() || hasDocValues) {
+        if (fieldType.stored() || docValuesParameters.enabled()) {
             return new SyntheticSourceSupport.Native(() -> syntheticFieldLoader(fullPath(), leafName()));
         }
 
@@ -1281,7 +1308,7 @@ protected SyntheticSourceSupport syntheticSourceSupport() {
     }
 
     public CompositeSyntheticFieldLoader syntheticFieldLoader(String fullFieldName, String leafFieldName) {
-        assert fieldType.stored() || hasDocValues;
+        assert fieldType.stored() || docValuesParameters.enabled();
 
         var layers = new ArrayList<CompositeSyntheticFieldLoader.Layer>(2);
         if (fieldType.stored()) {
@@ -1292,7 +1319,7 @@ protected void writeValue(Object value, XContentBuilder b) throws IOException {
                     b.utf8Value(ref.bytes, ref.offset, ref.length);
                 }
             });
-        } else if (hasDocValues) {
+        } else if (docValuesParameters.enabled()) {
             if (offsetsFieldName != null) {
                 layers.add(new SortedSetWithOffsetsDocValuesSyntheticFieldLoaderLayer(fullPath(), offsetsFieldName));
             } else {
diff --git a/server/src/test/java/org/elasticsearch/index/mapper/KeywordFieldMapperTests.java b/server/src/test/java/org/elasticsearch/index/mapper/KeywordFieldMapperTests.java
index 1744cc1b69611..57516ac168617 100644
--- a/server/src/test/java/org/elasticsearch/index/mapper/KeywordFieldMapperTests.java
+++ b/server/src/test/java/org/elasticsearch/index/mapper/KeywordFieldMapperTests.java
@@ -938,6 +938,30 @@ public void testDocValuesLoadedFromStoredSynthetic() throws IOException {
         assertScriptDocValues(mapper, "foo", equalTo(List.of("foo")));
     }
 
+    public void testDocValuesLowCardinality() throws IOException {
+        MapperService mapperService = createMapperService(
+            fieldMapping(b -> b.field("type", "keyword").startObject("doc_values").field("cardinality", "low").endObject())
+        );
+        KeywordFieldMapper mapper = (KeywordFieldMapper) mapperService.documentMapper().mappers().getMapper("field");
+        assertThat(
+            mapper.docValuesParameters(),
+            equalTo(new FieldMapper.DocValuesParameter.Values(true, FieldMapper.DocValuesParameter.Values.Cardinality.LOW))
+        );
+        assertScriptDocValues(mapperService, List.of("bar", "foo"), equalTo(List.of("bar", "foo")));
+    }
+
+    public void testDocValuesHighCardinality() throws IOException {
+        MapperService mapperService = createMapperService(
+            fieldMapping(b -> b.field("type", "keyword").startObject("doc_values").field("cardinality", "high").endObject())
+        );
+        KeywordFieldMapper mapper = (KeywordFieldMapper) mapperService.documentMapper().mappers().getMapper("field");
+        assertThat(
+            mapper.docValuesParameters(),
+            equalTo(new FieldMapper.DocValuesParameter.Values(true, FieldMapper.DocValuesParameter.Values.Cardinality.HIGH))
+        );
+        assertScriptDocValues(mapperService, List.of("bar", "foo"), equalTo(List.of("bar", "foo")));
+    }
+
     public void testFieldTypeWithSkipDocValues_LogsDbModeDisabledSetting() throws IOException {
         final MapperService mapperService = createMapperService(
             Settings.builder()

From 43c980edb9613746701944534743eb265798bbf3 Mon Sep 17 00:00:00 2001
From: Jordan Powers <jordan.powers@elastic.co>
Date: Sun, 23 Nov 2025 17:53:25 -0800
Subject: [PATCH 02/14] Add new cardinality parameter to randomized testing

---
 .../DefaultMappingParametersHandler.java      | 20 ++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)

diff --git a/test/framework/src/main/java/org/elasticsearch/datageneration/datasource/DefaultMappingParametersHandler.java b/test/framework/src/main/java/org/elasticsearch/datageneration/datasource/DefaultMappingParametersHandler.java
index 3fb817f6af681..97c161ac5a7d1 100644
--- a/test/framework/src/main/java/org/elasticsearch/datageneration/datasource/DefaultMappingParametersHandler.java
+++ b/test/framework/src/main/java/org/elasticsearch/datageneration/datasource/DefaultMappingParametersHandler.java
@@ -83,7 +83,15 @@ private Supplier<Map<String, Object>> numberMapping(FieldType fieldType) {
 
     private Supplier<Map<String, Object>> keywordMapping(DataSourceRequest.LeafMappingParametersGenerator request) {
         return () -> {
-            var mapping = commonMappingParameters();
+            var mapping = new HashMap<String, Object>();
+            mapping.put("store", ESTestCase.randomBoolean());
+            mapping.put("index", ESTestCase.randomBoolean());
+
+            if (ESTestCase.randomBoolean()) {
+                mapping.put(Mapper.SYNTHETIC_SOURCE_KEEP_PARAM, randomFrom("none", "arrays", "all"));
+            }
+
+            mapping.put("doc_values", extendedDocValuesParams());
 
             // Inject copy_to sometimes but reflect that it is not widely used in reality.
             // We only add copy_to to keywords because we get into trouble with numeric fields that are copied to dynamic fields.
@@ -271,6 +279,16 @@ public static HashMap<String, Object> commonMappingParameters() {
         return map;
     }
 
+    public static Object extendedDocValuesParams() {
+        return switch (ESTestCase.randomInt(3)) {
+            case 0 -> false;
+            case 1 -> Map.of("cardinality", "low");
+            case 2 -> Map.of("cardinality", "high");
+            case 3 -> true;
+            default -> throw new IllegalStateException();
+        };
+    }
+
     @Override
     public DataSourceResponse.ObjectMappingParametersGenerator handle(DataSourceRequest.ObjectMappingParametersGenerator request) {
         if (request.isNested()) {

From 64b78f326e26414225e0d6a69a67e02431b9fc0a Mon Sep 17 00:00:00 2001
From: Jordan Powers <jordan.powers@elastic.co>
Date: Sun, 23 Nov 2025 17:19:26 -0800
Subject: [PATCH 03/14] Store high-cardinality keyword fields in binary doc
 values

---
 .../percolator/QueryBuilderStoreTests.java    |   3 +-
 .../MultiValuedSortedBinaryDocValues.java     |  55 +++++++
 .../plain/AbstractBinaryDVLeafFieldData.java  |  40 +----
 .../plain/BytesBinaryDVLeafFieldData.java     |  10 +-
 .../plain/BytesBinaryIndexFieldData.java      |  18 ++-
 ...aryDocValuesSyntheticFieldLoaderLayer.java |  70 +++++++++
 .../index/mapper/BinaryFieldMapper.java       |   3 +-
 .../index/mapper/KeywordFieldMapper.java      | 138 ++++++++++++++----
 .../queries/LeafQueryGenerator.java           |  13 +-
 .../KeywordFieldSyntheticSourceSupport.java   |  22 ++-
 10 files changed, 291 insertions(+), 81 deletions(-)
 create mode 100644 server/src/main/java/org/elasticsearch/index/fielddata/MultiValuedSortedBinaryDocValues.java
 create mode 100644 server/src/main/java/org/elasticsearch/index/mapper/BinaryDocValuesSyntheticFieldLoaderLayer.java

diff --git a/modules/percolator/src/test/java/org/elasticsearch/percolator/QueryBuilderStoreTests.java b/modules/percolator/src/test/java/org/elasticsearch/percolator/QueryBuilderStoreTests.java
index 67527a4d27436..c98e70131b554 100644
--- a/modules/percolator/src/test/java/org/elasticsearch/percolator/QueryBuilderStoreTests.java
+++ b/modules/percolator/src/test/java/org/elasticsearch/percolator/QueryBuilderStoreTests.java
@@ -32,6 +32,7 @@
 import org.elasticsearch.index.mapper.TestDocumentParserContext;
 import org.elasticsearch.index.query.SearchExecutionContext;
 import org.elasticsearch.index.query.TermQueryBuilder;
+import org.elasticsearch.script.field.BinaryDocValuesField;
 import org.elasticsearch.search.SearchModule;
 import org.elasticsearch.search.aggregations.support.CoreValuesSourceType;
 import org.elasticsearch.test.ESTestCase;
@@ -88,7 +89,7 @@ public void testStoringQueryBuilders() throws IOException {
             when(searchExecutionContext.getWriteableRegistry()).thenReturn(writableRegistry());
             when(searchExecutionContext.getParserConfig()).thenReturn(parserConfig());
             when(searchExecutionContext.getForField(fieldMapper.fieldType(), fielddataOperation)).thenReturn(
-                new BytesBinaryIndexFieldData(fieldMapper.fullPath(), CoreValuesSourceType.KEYWORD)
+                new BytesBinaryIndexFieldData(fieldMapper.fullPath(), CoreValuesSourceType.KEYWORD, BinaryDocValuesField::new)
             );
             when(searchExecutionContext.getFieldType(Mockito.anyString())).thenAnswer(invocation -> {
                 final String fieldName = (String) invocation.getArguments()[0];
diff --git a/server/src/main/java/org/elasticsearch/index/fielddata/MultiValuedSortedBinaryDocValues.java b/server/src/main/java/org/elasticsearch/index/fielddata/MultiValuedSortedBinaryDocValues.java
new file mode 100644
index 0000000000000..cb48b900b3bc4
--- /dev/null
+++ b/server/src/main/java/org/elasticsearch/index/fielddata/MultiValuedSortedBinaryDocValues.java
@@ -0,0 +1,55 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the "Elastic License
+ * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
+ * Public License v 1"; you may not use this file except in compliance with, at
+ * your election, the "Elastic License 2.0", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+package org.elasticsearch.index.fielddata;
+
+import org.apache.lucene.index.BinaryDocValues;
+import org.apache.lucene.util.BytesRef;
+import org.elasticsearch.common.io.stream.ByteArrayStreamInput;
+
+import java.io.IOException;
+
+public class MultiValuedSortedBinaryDocValues extends SortedBinaryDocValues {
+
+    BinaryDocValues values;
+    int count;
+    final ByteArrayStreamInput in = new ByteArrayStreamInput();
+    final BytesRef scratch = new BytesRef();
+
+    public MultiValuedSortedBinaryDocValues(BinaryDocValues values) {
+        this.values = values;
+    }
+
+    @Override
+    public boolean advanceExact(int doc) throws IOException {
+        if (values.advanceExact(doc)) {
+            final BytesRef bytes = values.binaryValue();
+            assert bytes.length > 0;
+            in.reset(bytes.bytes, bytes.offset, bytes.length);
+            count = in.readVInt();
+            scratch.bytes = bytes.bytes;
+            return true;
+        } else {
+            return false;
+        }
+    }
+
+    @Override
+    public int docValueCount() {
+        return count;
+    }
+
+    @Override
+    public BytesRef nextValue() throws IOException {
+        scratch.length = in.readVInt();
+        scratch.offset = in.getPosition();
+        in.setPosition(scratch.offset + scratch.length);
+        return scratch;
+    }
+}
diff --git a/server/src/main/java/org/elasticsearch/index/fielddata/plain/AbstractBinaryDVLeafFieldData.java b/server/src/main/java/org/elasticsearch/index/fielddata/plain/AbstractBinaryDVLeafFieldData.java
index 63fa0e21c6cb6..ce332e28d2508 100644
--- a/server/src/main/java/org/elasticsearch/index/fielddata/plain/AbstractBinaryDVLeafFieldData.java
+++ b/server/src/main/java/org/elasticsearch/index/fielddata/plain/AbstractBinaryDVLeafFieldData.java
@@ -10,13 +10,10 @@
 package org.elasticsearch.index.fielddata.plain;
 
 import org.apache.lucene.index.BinaryDocValues;
-import org.apache.lucene.util.BytesRef;
-import org.elasticsearch.common.io.stream.ByteArrayStreamInput;
 import org.elasticsearch.index.fielddata.LeafFieldData;
+import org.elasticsearch.index.fielddata.MultiValuedSortedBinaryDocValues;
 import org.elasticsearch.index.fielddata.SortedBinaryDocValues;
 
-import java.io.IOException;
-
 abstract class AbstractBinaryDVLeafFieldData implements LeafFieldData {
     private final BinaryDocValues values;
 
@@ -32,40 +29,7 @@ public long ramBytesUsed() {
 
     @Override
     public SortedBinaryDocValues getBytesValues() {
-        return new SortedBinaryDocValues() {
-
-            int count;
-            final ByteArrayStreamInput in = new ByteArrayStreamInput();
-            final BytesRef scratch = new BytesRef();
-
-            @Override
-            public boolean advanceExact(int doc) throws IOException {
-                if (values.advanceExact(doc)) {
-                    final BytesRef bytes = values.binaryValue();
-                    assert bytes.length > 0;
-                    in.reset(bytes.bytes, bytes.offset, bytes.length);
-                    count = in.readVInt();
-                    scratch.bytes = bytes.bytes;
-                    return true;
-                } else {
-                    return false;
-                }
-            }
-
-            @Override
-            public int docValueCount() {
-                return count;
-            }
-
-            @Override
-            public BytesRef nextValue() throws IOException {
-                scratch.length = in.readVInt();
-                scratch.offset = in.getPosition();
-                in.setPosition(scratch.offset + scratch.length);
-                return scratch;
-            }
-
-        };
+        return new MultiValuedSortedBinaryDocValues(values);
     }
 
 }
diff --git a/server/src/main/java/org/elasticsearch/index/fielddata/plain/BytesBinaryDVLeafFieldData.java b/server/src/main/java/org/elasticsearch/index/fielddata/plain/BytesBinaryDVLeafFieldData.java
index 9bb6062fb08c9..1d99083ed355e 100644
--- a/server/src/main/java/org/elasticsearch/index/fielddata/plain/BytesBinaryDVLeafFieldData.java
+++ b/server/src/main/java/org/elasticsearch/index/fielddata/plain/BytesBinaryDVLeafFieldData.java
@@ -10,16 +10,20 @@
 package org.elasticsearch.index.fielddata.plain;
 
 import org.apache.lucene.index.BinaryDocValues;
-import org.elasticsearch.script.field.BinaryDocValuesField;
+import org.elasticsearch.index.fielddata.SortedBinaryDocValues;
 import org.elasticsearch.script.field.DocValuesScriptFieldFactory;
+import org.elasticsearch.script.field.ToScriptFieldFactory;
 
 final class BytesBinaryDVLeafFieldData extends AbstractBinaryDVLeafFieldData {
-    BytesBinaryDVLeafFieldData(BinaryDocValues values) {
+    private final ToScriptFieldFactory<SortedBinaryDocValues> toScriptFieldFactory;
+
+    BytesBinaryDVLeafFieldData(BinaryDocValues values, ToScriptFieldFactory<SortedBinaryDocValues> toScriptFieldFactory) {
         super(values);
+        this.toScriptFieldFactory = toScriptFieldFactory;
     }
 
     @Override
     public DocValuesScriptFieldFactory getScriptFieldFactory(String name) {
-        return new BinaryDocValuesField(getBytesValues(), name);
+        return toScriptFieldFactory.getScriptFieldFactory(getBytesValues(), name);
     }
 }
diff --git a/server/src/main/java/org/elasticsearch/index/fielddata/plain/BytesBinaryIndexFieldData.java b/server/src/main/java/org/elasticsearch/index/fielddata/plain/BytesBinaryIndexFieldData.java
index f5d4bf837f062..cc3469a9dcb44 100644
--- a/server/src/main/java/org/elasticsearch/index/fielddata/plain/BytesBinaryIndexFieldData.java
+++ b/server/src/main/java/org/elasticsearch/index/fielddata/plain/BytesBinaryIndexFieldData.java
@@ -17,7 +17,9 @@
 import org.elasticsearch.index.fielddata.IndexFieldData;
 import org.elasticsearch.index.fielddata.IndexFieldData.XFieldComparatorSource.Nested;
 import org.elasticsearch.index.fielddata.IndexFieldDataCache;
+import org.elasticsearch.index.fielddata.SortedBinaryDocValues;
 import org.elasticsearch.indices.breaker.CircuitBreakerService;
+import org.elasticsearch.script.field.ToScriptFieldFactory;
 import org.elasticsearch.search.DocValueFormat;
 import org.elasticsearch.search.MultiValueMode;
 import org.elasticsearch.search.aggregations.support.ValuesSourceType;
@@ -30,10 +32,16 @@ public class BytesBinaryIndexFieldData implements IndexFieldData<BytesBinaryDVLe
 
     protected final String fieldName;
     protected final ValuesSourceType valuesSourceType;
+    protected final ToScriptFieldFactory<SortedBinaryDocValues> toScriptFieldFactory;
 
-    public BytesBinaryIndexFieldData(String fieldName, ValuesSourceType valuesSourceType) {
+    public BytesBinaryIndexFieldData(
+        String fieldName,
+        ValuesSourceType valuesSourceType,
+        ToScriptFieldFactory<SortedBinaryDocValues> toScriptFieldFactory
+    ) {
         this.fieldName = fieldName;
         this.valuesSourceType = valuesSourceType;
+        this.toScriptFieldFactory = toScriptFieldFactory;
     }
 
     @Override
@@ -68,7 +76,7 @@ public BucketedSort newBucketedSort(
     @Override
     public BytesBinaryDVLeafFieldData load(LeafReaderContext context) {
         try {
-            return new BytesBinaryDVLeafFieldData(DocValues.getBinary(context.reader(), fieldName));
+            return new BytesBinaryDVLeafFieldData(DocValues.getBinary(context.reader(), fieldName), toScriptFieldFactory);
         } catch (IOException e) {
             throw new IllegalStateException("Cannot load doc values", e);
         }
@@ -81,17 +89,19 @@ public BytesBinaryDVLeafFieldData loadDirect(LeafReaderContext context) {
 
     public static class Builder implements IndexFieldData.Builder {
         private final String name;
+        private final ToScriptFieldFactory<SortedBinaryDocValues> toScriptFieldFactory;
         private final ValuesSourceType valuesSourceType;
 
-        public Builder(String name, ValuesSourceType valuesSourceType) {
+        public Builder(String name, ValuesSourceType valuesSourceType, ToScriptFieldFactory<SortedBinaryDocValues> toScriptFieldFactory) {
             this.name = name;
             this.valuesSourceType = valuesSourceType;
+            this.toScriptFieldFactory = toScriptFieldFactory;
         }
 
         @Override
         public IndexFieldData<?> build(IndexFieldDataCache cache, CircuitBreakerService breakerService) {
             // Ignore breaker
-            return new BytesBinaryIndexFieldData(name, valuesSourceType);
+            return new BytesBinaryIndexFieldData(name, valuesSourceType, toScriptFieldFactory);
         }
     }
 }
diff --git a/server/src/main/java/org/elasticsearch/index/mapper/BinaryDocValuesSyntheticFieldLoaderLayer.java b/server/src/main/java/org/elasticsearch/index/mapper/BinaryDocValuesSyntheticFieldLoaderLayer.java
new file mode 100644
index 0000000000000..cfab076d41e9f
--- /dev/null
+++ b/server/src/main/java/org/elasticsearch/index/mapper/BinaryDocValuesSyntheticFieldLoaderLayer.java
@@ -0,0 +1,70 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the "Elastic License
+ * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
+ * Public License v 1"; you may not use this file except in compliance with, at
+ * your election, the "Elastic License 2.0", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+package org.elasticsearch.index.mapper;
+
+import org.apache.lucene.index.LeafReader;
+import org.apache.lucene.util.BytesRef;
+import org.elasticsearch.index.fielddata.MultiValuedSortedBinaryDocValues;
+import org.elasticsearch.index.fielddata.SortedBinaryDocValues;
+import org.elasticsearch.xcontent.XContentBuilder;
+
+import java.io.IOException;
+
+public abstract class BinaryDocValuesSyntheticFieldLoaderLayer implements CompositeSyntheticFieldLoader.DocValuesLayer {
+
+    private final String name;
+    private SortedBinaryDocValues bytesValues;
+    private boolean hasValue;
+
+    protected BinaryDocValuesSyntheticFieldLoaderLayer(String name) {
+        this.name = name;
+    }
+
+    protected abstract void writeValue(XContentBuilder b, BytesRef value) throws IOException;
+
+    @Override
+    public long valueCount() {
+        return bytesValues.docValueCount();
+    }
+
+    @Override
+    public DocValuesLoader docValuesLoader(LeafReader leafReader, int[] docIdsInLeaf) throws IOException {
+        var docValues = leafReader.getBinaryDocValues(name);
+        if (docValues == null) {
+            return null;
+        }
+
+        bytesValues = new MultiValuedSortedBinaryDocValues(docValues);
+
+        return docId -> {
+            hasValue = bytesValues.advanceExact(docId);
+            return hasValue;
+        };
+    }
+
+    @Override
+    public boolean hasValue() {
+        return hasValue;
+    }
+
+    @Override
+    public void write(XContentBuilder b) throws IOException {
+        if (hasValue == false) {
+            return;
+        }
+
+        writeValue(b, bytesValues.nextValue());
+    }
+
+    @Override
+    public String fieldName() {
+        return name;
+    }
+}
diff --git a/server/src/main/java/org/elasticsearch/index/mapper/BinaryFieldMapper.java b/server/src/main/java/org/elasticsearch/index/mapper/BinaryFieldMapper.java
index 01daf1bf6d392..6db6a5b00755c 100644
--- a/server/src/main/java/org/elasticsearch/index/mapper/BinaryFieldMapper.java
+++ b/server/src/main/java/org/elasticsearch/index/mapper/BinaryFieldMapper.java
@@ -22,6 +22,7 @@
 import org.elasticsearch.index.fielddata.IndexFieldData;
 import org.elasticsearch.index.fielddata.plain.BytesBinaryIndexFieldData;
 import org.elasticsearch.index.query.SearchExecutionContext;
+import org.elasticsearch.script.field.BinaryDocValuesField;
 import org.elasticsearch.search.DocValueFormat;
 import org.elasticsearch.search.aggregations.support.CoreValuesSourceType;
 import org.elasticsearch.xcontent.XContentBuilder;
@@ -127,7 +128,7 @@ public BytesReference valueForDisplay(Object value) {
         @Override
         public IndexFieldData.Builder fielddataBuilder(FieldDataContext fieldDataContext) {
             failIfNoDocValues();
-            return new BytesBinaryIndexFieldData.Builder(name(), CoreValuesSourceType.KEYWORD);
+            return new BytesBinaryIndexFieldData.Builder(name(), CoreValuesSourceType.KEYWORD, BinaryDocValuesField::new);
         }
 
         @Override
diff --git a/server/src/main/java/org/elasticsearch/index/mapper/KeywordFieldMapper.java b/server/src/main/java/org/elasticsearch/index/mapper/KeywordFieldMapper.java
index 0e97677c58532..b4862ed8fd592 100644
--- a/server/src/main/java/org/elasticsearch/index/mapper/KeywordFieldMapper.java
+++ b/server/src/main/java/org/elasticsearch/index/mapper/KeywordFieldMapper.java
@@ -40,10 +40,13 @@
 import org.apache.lucene.util.automaton.CompiledAutomaton;
 import org.apache.lucene.util.automaton.CompiledAutomaton.AUTOMATON_TYPE;
 import org.apache.lucene.util.automaton.Operations;
+import org.elasticsearch.ElasticsearchException;
+import org.elasticsearch.common.io.stream.BytesStreamOutput;
 import org.elasticsearch.common.lucene.BytesRefs;
 import org.elasticsearch.common.lucene.Lucene;
 import org.elasticsearch.common.lucene.search.AutomatonQueries;
 import org.elasticsearch.common.unit.Fuzziness;
+import org.elasticsearch.common.util.CollectionUtils;
 import org.elasticsearch.core.Nullable;
 import org.elasticsearch.index.IndexMode;
 import org.elasticsearch.index.IndexSettings;
@@ -58,6 +61,7 @@
 import org.elasticsearch.index.fielddata.IndexFieldData;
 import org.elasticsearch.index.fielddata.SourceValueFetcherSortedBinaryIndexFieldData;
 import org.elasticsearch.index.fielddata.StoredFieldSortedBinaryIndexFieldData;
+import org.elasticsearch.index.fielddata.plain.BytesBinaryIndexFieldData;
 import org.elasticsearch.index.fielddata.plain.SortedSetOrdinalsIndexFieldData;
 import org.elasticsearch.index.mapper.blockloader.BlockLoaderFunctionConfig;
 import org.elasticsearch.index.mapper.blockloader.docvalues.BytesRefsFromOrdsBlockLoader;
@@ -110,7 +114,7 @@ public final class KeywordFieldMapper extends FieldMapper {
     public static final String CONTENT_TYPE = "keyword";
     private static final String HOST_NAME = "host.name";
 
-    private static final DocValuesParameter.Values DEFAULT_DOC_VALUES_PARAMS = new DocValuesParameter.Values(
+    public static final DocValuesParameter.Values DEFAULT_DOC_VALUES_PARAMS = new DocValuesParameter.Values(
         true,
         DocValuesParameter.Values.Cardinality.LOW
     );
@@ -382,6 +386,17 @@ protected Parameter<?>[] getParameters() {
                 dimension };
         }
 
+        private IndexType buildIndexType(FieldType fieldType) {
+            if (fieldType.indexOptions() == IndexOptions.NONE && fieldType.docValuesType() == DocValuesType.NONE) {
+                var docValuesParameters = docValuesParameters();
+                if (docValuesParameters.enabled() && docValuesParameters.cardinality() == DocValuesParameter.Values.Cardinality.HIGH) {
+                    return IndexType.docValuesOnly();
+                }
+            }
+
+            return IndexType.terms(fieldType);
+        }
+
         private KeywordFieldType buildFieldType(MapperBuilderContext context, FieldType fieldType) {
             NamedAnalyzer normalizer = Lucene.KEYWORD_ANALYZER;
             NamedAnalyzer searchAnalyzer = Lucene.KEYWORD_ANALYZER;
@@ -412,7 +427,7 @@ private KeywordFieldType buildFieldType(MapperBuilderContext context, FieldType
             }
             return new KeywordFieldType(
                 context.buildFullName(leafName()),
-                IndexType.terms(fieldType),
+                buildIndexType(fieldType),
                 new TextSearchInfo(fieldType, similarity.get(), searchAnalyzer, quoteAnalyzer),
                 normalizer,
                 this,
@@ -429,7 +444,7 @@ public KeywordFieldMapper build(MapperBuilderContext context) {
             String offsetsFieldName = getOffsetsFieldName(
                 context,
                 indexSettings.sourceKeepMode(),
-                docValuesParameters.get().enabled(),
+                fieldtype.docValuesType() == DocValuesType.SORTED_SET,
                 stored.getValue(),
                 this,
                 indexCreatedVersion,
@@ -454,13 +469,10 @@ private FieldType resolveFieldType(final boolean forceDocValuesSkipper, final St
             fieldtype.setStored(this.stored.getValue());
 
             DocValuesParameter.Values docValuesParameters = this.docValuesParameters.get();
-            if (docValuesParameters.enabled() == false) {
-                fieldtype.setDocValuesType(DocValuesType.NONE);
-            } else if (docValuesParameters.cardinality() == DocValuesParameter.Values.Cardinality.HIGH) {
-                fieldtype.setDocValuesType(DocValuesType.BINARY);
-            } else {
-                assert docValuesParameters.cardinality() == DocValuesParameter.Values.Cardinality.LOW;
+            if (docValuesParameters.enabled() && docValuesParameters.cardinality() == DocValuesParameter.Values.Cardinality.LOW) {
                 fieldtype.setDocValuesType(DocValuesType.SORTED_SET);
+            } else {
+                fieldtype.setDocValuesType(DocValuesType.NONE);
             }
 
             if (fieldtype.equals(Defaults.FIELD_TYPE_WITH_SKIP_DOC_VALUES) == false) {
@@ -509,6 +521,7 @@ public static final class KeywordFieldType extends TextFamilyFieldType {
         private final boolean eagerGlobalOrdinals;
         private final FieldValues<String> scriptValues;
         private final boolean isDimension;
+        private final DocValuesParameter.Values docValuesParameters;
 
         public KeywordFieldType(
             String name,
@@ -537,6 +550,7 @@ public KeywordFieldType(
             this.nullValue = builder.nullValue.getValue();
             this.scriptValues = builder.scriptValues();
             this.isDimension = builder.dimension.getValue();
+            this.docValuesParameters = builder.docValuesParameters();
         }
 
         public KeywordFieldType(String name) {
@@ -551,6 +565,7 @@ public KeywordFieldType(String name, boolean isIndexed, boolean hasDocValues, Ma
             this.eagerGlobalOrdinals = false;
             this.scriptValues = null;
             this.isDimension = false;
+            this.docValuesParameters = DEFAULT_DOC_VALUES_PARAMS;
         }
 
         public KeywordFieldType(String name, FieldType fieldType, boolean isSyntheticSource) {
@@ -569,6 +584,7 @@ public KeywordFieldType(String name, FieldType fieldType, boolean isSyntheticSou
             this.eagerGlobalOrdinals = false;
             this.scriptValues = null;
             this.isDimension = false;
+            this.docValuesParameters = DEFAULT_DOC_VALUES_PARAMS;
         }
 
         public KeywordFieldType(String name, NamedAnalyzer analyzer) {
@@ -587,6 +603,7 @@ public KeywordFieldType(String name, NamedAnalyzer analyzer) {
             this.eagerGlobalOrdinals = false;
             this.scriptValues = null;
             this.isDimension = false;
+            this.docValuesParameters = DEFAULT_DOC_VALUES_PARAMS;
         }
 
         @Override
@@ -739,6 +756,10 @@ public String typeName() {
             return CONTENT_TYPE;
         }
 
+        public String binaryDocValuesName() {
+            return name() + "._dv";
+        }
+
         @Override
         public boolean eagerGlobalOrdinals() {
             return eagerGlobalOrdinals;
@@ -883,12 +904,19 @@ protected BytesRef storedToBytesRef(Object stored) {
             );
         }
 
-        private SortedSetOrdinalsIndexFieldData.Builder fieldDataFromDocValues() {
-            return new SortedSetOrdinalsIndexFieldData.Builder(
-                name(),
-                CoreValuesSourceType.KEYWORD,
-                (dv, n) -> new KeywordDocValuesField(FieldData.toString(dv), n)
-            );
+        private IndexFieldData.Builder fieldDataFromDocValues() {
+            return switch (docValuesParameters.cardinality()) {
+                case LOW -> new SortedSetOrdinalsIndexFieldData.Builder(
+                    name(),
+                    CoreValuesSourceType.KEYWORD,
+                    (dv, n) -> new KeywordDocValuesField(FieldData.toString(dv), n)
+                );
+                case HIGH -> new BytesBinaryIndexFieldData.Builder(
+                    binaryDocValuesName(),
+                    CoreValuesSourceType.KEYWORD,
+                    KeywordDocValuesField::new
+                );
+            };
         }
 
         @Override
@@ -1217,6 +1245,16 @@ private boolean indexValue(DocumentParserContext context, XContentString value)
             throw new IllegalArgumentException(msg);
         }
 
+        if (docValuesParameters.enabled() && docValuesParameters.cardinality() == DocValuesParameter.Values.Cardinality.HIGH) {
+            assert fieldType.docValuesType() == DocValuesType.NONE;
+            KeywordBinaryDocValuesField field = (KeywordBinaryDocValuesField) context.doc().getField(fieldType().binaryDocValuesName());
+            if (field == null) {
+                field = new KeywordBinaryDocValuesField(fieldType().binaryDocValuesName());
+                context.doc().addWithKey(fieldType().binaryDocValuesName(), field);
+            }
+            field.add(binaryValue);
+        }
+
         Field field = buildKeywordField(binaryValue);
         context.doc().add(field);
 
@@ -1300,7 +1338,9 @@ protected SyntheticSourceSupport syntheticSourceSupport() {
             return SyntheticSourceSupport.FALLBACK;
         }
 
-        if (fieldType.stored() || docValuesParameters.enabled()) {
+        if (fieldType.stored()
+            || offsetsFieldName != null
+            || (indexSettings.sourceKeepMode() == SourceKeepMode.NONE && fieldType.docValuesType() != DocValuesType.NONE)) {
             return new SyntheticSourceSupport.Native(() -> syntheticFieldLoader(fullPath(), leafName()));
         }
 
@@ -1320,20 +1360,31 @@ protected void writeValue(Object value, XContentBuilder b) throws IOException {
                 }
             });
         } else if (docValuesParameters.enabled()) {
-            if (offsetsFieldName != null) {
-                layers.add(new SortedSetWithOffsetsDocValuesSyntheticFieldLoaderLayer(fullPath(), offsetsFieldName));
+            if (docValuesParameters.cardinality() == DocValuesParameter.Values.Cardinality.LOW) {
+                if (offsetsFieldName != null) {
+                    layers.add(new SortedSetWithOffsetsDocValuesSyntheticFieldLoaderLayer(fullPath(), offsetsFieldName));
+                } else {
+                    layers.add(new SortedSetDocValuesSyntheticFieldLoaderLayer(fullPath()) {
+
+                        @Override
+                        protected BytesRef convert(BytesRef value) {
+                            return value;
+                        }
+
+                        @Override
+                        protected BytesRef preserve(BytesRef value) {
+                            // Preserve must make a deep copy because convert gets a shallow copy from the iterator
+                            return BytesRef.deepCopyOf(value);
+                        }
+                    });
+                }
             } else {
-                layers.add(new SortedSetDocValuesSyntheticFieldLoaderLayer(fullPath()) {
-
+                assert offsetsFieldName == null;
+                assert indexSettings.sourceKeepMode() == SourceKeepMode.NONE;
+                layers.add(new BinaryDocValuesSyntheticFieldLoaderLayer(fieldType().binaryDocValuesName()) {
                     @Override
-                    protected BytesRef convert(BytesRef value) {
-                        return value;
-                    }
-
-                    @Override
-                    protected BytesRef preserve(BytesRef value) {
-                        // Preserve must make a deep copy because convert gets a shallow copy from the iterator
-                        return BytesRef.deepCopyOf(value);
+                    protected void writeValue(XContentBuilder b, BytesRef value) throws IOException {
+                        b.utf8Value(value.bytes, value.offset, value.length);
                     }
                 });
             }
@@ -1354,4 +1405,35 @@ protected void writeValue(Object value, XContentBuilder b) throws IOException {
 
         return new CompositeSyntheticFieldLoader(leafFieldName, fullFieldName, layers);
     }
+
+    private static class KeywordBinaryDocValuesField extends CustomDocValuesField {
+        private final List<BytesRef> bytesList;
+
+        KeywordBinaryDocValuesField(String name) {
+            super(name);
+            bytesList = new ArrayList<>();
+        }
+
+        public void add(BytesRef value) {
+            bytesList.add(value);
+        }
+
+        @Override
+        public BytesRef binaryValue() {
+            try {
+                bytesList.sort(BytesRef::compareTo);
+                CollectionUtils.uniquify(bytesList, BytesRef::compareTo);
+                int bytesSize = bytesList.stream().map(a -> a.length).reduce(0, Integer::sum);
+                int n = bytesList.size();
+                BytesStreamOutput out = new BytesStreamOutput(bytesSize + (n + 1) * 5);
+                out.writeVInt(n);
+                for (var value : bytesList) {
+                    out.writeBytesRef(value);
+                }
+                return out.bytes().toBytesRef();
+            } catch (IOException e) {
+                throw new ElasticsearchException("Failed to get binary value", e);
+            }
+        }
+    }
 }
diff --git a/test/framework/src/main/java/org/elasticsearch/datageneration/queries/LeafQueryGenerator.java b/test/framework/src/main/java/org/elasticsearch/datageneration/queries/LeafQueryGenerator.java
index cb102e185c9b5..6a47d2af336bf 100644
--- a/test/framework/src/main/java/org/elasticsearch/datageneration/queries/LeafQueryGenerator.java
+++ b/test/framework/src/main/java/org/elasticsearch/datageneration/queries/LeafQueryGenerator.java
@@ -42,11 +42,22 @@ static LeafQueryGenerator buildForType(String type, MappingPredicates mappingPre
         };
     }
 
+    private static boolean extendedDocValuesEnabled(Map<String, Object> fieldMapping) {
+        Object configuredValue = fieldMapping.getOrDefault("doc_values", true);
+        if (configuredValue instanceof Boolean b) {
+            return b;
+        } else if (configuredValue instanceof Map) {
+            return true;
+        } else {
+            throw new IllegalArgumentException("Unexpected value [" + configuredValue + "] for mapping parameter [doc_values]");
+        }
+    }
+
     class KeywordQueryGenerator implements LeafQueryGenerator {
         public List<QueryBuilder> generate(Map<String, Object> fieldMapping, String path, Object value) {
             if (fieldMapping != null) {
                 boolean isIndexed = (Boolean) fieldMapping.getOrDefault("index", true);
-                boolean hasDocValues = (Boolean) fieldMapping.getOrDefault("doc_values", true);
+                boolean hasDocValues = LeafQueryGenerator.extendedDocValuesEnabled(fieldMapping);
                 if (isIndexed == false && hasDocValues == false) {
                     return List.of();
                 }
diff --git a/test/framework/src/main/java/org/elasticsearch/index/mapper/KeywordFieldSyntheticSourceSupport.java b/test/framework/src/main/java/org/elasticsearch/index/mapper/KeywordFieldSyntheticSourceSupport.java
index 770b4dffbae27..931ba021ae80b 100644
--- a/test/framework/src/main/java/org/elasticsearch/index/mapper/KeywordFieldSyntheticSourceSupport.java
+++ b/test/framework/src/main/java/org/elasticsearch/index/mapper/KeywordFieldSyntheticSourceSupport.java
@@ -24,15 +24,21 @@ public class KeywordFieldSyntheticSourceSupport implements MapperTestCase.Synthe
     private final Integer ignoreAbove;
     private final boolean allIgnored;
     private final boolean store;
-    private final boolean docValues;
+    private final FieldMapper.DocValuesParameter.Values docValues;
     private final String nullValue;
 
-    KeywordFieldSyntheticSourceSupport(Integer ignoreAbove, boolean store, String nullValue, boolean useFallbackSyntheticSource) {
+    KeywordFieldSyntheticSourceSupport(Integer ignoreAbove, boolean store, String nullValue, boolean allowIgnoredSource) {
         this.ignoreAbove = ignoreAbove;
         this.allIgnored = ignoreAbove != null && LuceneTestCase.rarely();
         this.store = store;
         this.nullValue = nullValue;
-        this.docValues = useFallbackSyntheticSource == false || ESTestCase.randomBoolean();
+
+        this.docValues = switch (ESTestCase.randomInt(allowIgnoredSource ? 2 : 1)) {
+            case 0 -> new FieldMapper.DocValuesParameter.Values(true, FieldMapper.DocValuesParameter.Values.Cardinality.LOW);
+            case 1 -> new FieldMapper.DocValuesParameter.Values(true, FieldMapper.DocValuesParameter.Values.Cardinality.HIGH);
+            case 2 -> FieldMapper.DocValuesParameter.Values.DISABLED;
+            default -> throw new IllegalStateException();
+        };
     }
 
     @Override
@@ -44,7 +50,8 @@ public boolean ignoreAbove() {
     public boolean preservesExactSource() {
         // We opt in into fallback synthetic source implementation
         // if there is nothing else to use, and it preserves exact source data.
-        return store == false && docValues == false;
+        return store == false
+            && (docValues.enabled() == false || docValues.cardinality() == FieldMapper.DocValuesParameter.Values.Cardinality.HIGH);
     }
 
     @Override
@@ -111,8 +118,13 @@ private void mapping(XContentBuilder b) throws IOException {
         if (store) {
             b.field("store", true);
         }
-        if (docValues == false) {
+
+        if (docValues.enabled() == false) {
             b.field("doc_values", false);
+        } else {
+            b.startObject("doc_values");
+            b.field("cardinality", docValues.cardinality().toString());
+            b.endObject();
         }
     }
 

From 5d5c63a206938b5b1409a31733b566d7f0a7ae40 Mon Sep 17 00:00:00 2001
From: Jordan Powers <jordan.powers@elastic.co>
Date: Mon, 24 Nov 2025 15:39:35 -0800
Subject: [PATCH 04/14] Fix queries

---
 .../test/search/390_doc_values_search.yml     |  60 ++++++++
 .../index/mapper/KeywordFieldMapper.java      | 139 +++++++++++++++---
 ...ortedBinaryDocValuesStringFieldScript.java |  59 ++++++++
 3 files changed, 236 insertions(+), 22 deletions(-)
 create mode 100644 server/src/main/java/org/elasticsearch/script/SortedBinaryDocValuesStringFieldScript.java

diff --git a/rest-api-spec/src/yamlRestTest/resources/rest-api-spec/test/search/390_doc_values_search.yml b/rest-api-spec/src/yamlRestTest/resources/rest-api-spec/test/search/390_doc_values_search.yml
index aa8323edaa6e3..0fa9478b7b070 100644
--- a/rest-api-spec/src/yamlRestTest/resources/rest-api-spec/test/search/390_doc_values_search.yml
+++ b/rest-api-spec/src/yamlRestTest/resources/rest-api-spec/test/search/390_doc_values_search.yml
@@ -39,6 +39,11 @@ setup:
               keyword:
                 type: keyword
                 index: false
+              keyword_high_cardinality:
+                type: keyword
+                index: false
+                doc_values:
+                  cardinality: high
               boolean:
                 type: boolean
                 index: false
@@ -63,6 +68,7 @@ setup:
           short: 1
           date: "2017/01/01"
           keyword: "key1"
+          keyword_high_cardinality: "key1"
           boolean: "false"
           ip: "192.168.0.1"
           geo_point: [13.5, 34.89]
@@ -81,6 +87,7 @@ setup:
           short: 2
           date: "2017/01/02"
           keyword: "key2"
+          keyword_high_cardinality: "key2"
           boolean: "true"
           ip: "192.168.0.2"
           geo_point : [-63.24, 31.0]
@@ -271,6 +278,12 @@ setup:
         body: { query: { match: { keyword: { query: "key1" } } } }
   - length:   { hits.hits: 1  }
 
+  - do:
+      search:
+        index: test
+        body: { query: { match: { keyword_high_cardinality: { "query": "key1" } } } }
+  - length: { hits.hits: 1 }
+
 ---
 "Test terms query on keyword field where only doc values are enabled":
 
@@ -280,6 +293,11 @@ setup:
         body: { query: { terms: { keyword: [ "key1", "key2" ] } } }
   - length:   { hits.hits: 2  }
 
+  - do:
+      search:
+        index: test
+        body: { query: { terms: { keyword_high_cardinality: [ "key1", "key2" ] } } }
+
 ---
 "Test range query on keyword field where only doc values are enabled":
 
@@ -289,6 +307,12 @@ setup:
         body: { query: { range: { keyword: { gte: "key1" } } } }
   - length:   { hits.hits: 2  }
 
+  - do:
+      search:
+        index: test
+        body: { query: { range: { keyword_high_cardinality: { gte: "key1" } } } }
+  - length:   { hits.hits: 2  }
+
 ---
 "Test fuzzy query on keyword field where only doc values are enabled":
 
@@ -298,6 +322,12 @@ setup:
         body: { query: { fuzzy: { keyword: { value: "kay1", fuzziness: 1 } } } }
   - length:   { hits.hits: 1  }
 
+  - do:
+      search:
+        index: test
+        body: { query: { fuzzy: { keyword_high_cardinality: { value: "kay1", fuzziness: 1 } } } }
+  - length:   { hits.hits: 1  }
+
 ---
 "Test prefix query on keyword field where only doc values are enabled":
 
@@ -307,6 +337,12 @@ setup:
         body: { query: { prefix: { keyword: { value: "key" } } } }
   - length:   { hits.hits: 2  }
 
+  - do:
+      search:
+        index: test
+        body: { query: { prefix: { keyword_high_cardinality: { value: "key" } } } }
+  - length:   { hits.hits: 2  }
+
 ---
 "Test case insensitive term query on keyword field where only doc values are enabled":
 
@@ -316,6 +352,12 @@ setup:
         body: { query: { term: { keyword: { value: "KeY1", case_insensitive: true } } } }
   - length:   { hits.hits: 1  }
 
+  - do:
+      search:
+        index: test
+        body: { query: { term: { keyword_high_cardinality: { value: "KeY1", case_insensitive: true } } } }
+  - length:   { hits.hits: 1  }
+
 ---
 "Test wildcard query on keyword field where only doc values are enabled":
 
@@ -325,6 +367,12 @@ setup:
         body: { query: { wildcard: { keyword: { value: "k*1" } } } }
   - length:   { hits.hits: 1  }
 
+  - do:
+      search:
+        index: test
+        body: { query: { wildcard: { keyword_high_cardinality: { value: "k*1" } } } }
+  - length:   { hits.hits: 1  }
+
 ---
 "Test case insensitive wildcard query on keyword field where only doc values are enabled":
 
@@ -334,6 +382,12 @@ setup:
         body: { query: { wildcard: { keyword: { value: "K*1", case_insensitive: true } } } }
   - length:   { hits.hits: 1  }
 
+  - do:
+      search:
+        index: test
+        body: { query: { wildcard: { keyword_high_cardinality: { value: "K*1", case_insensitive: true } } } }
+  - length:   { hits.hits: 1  }
+
 ---
 "Test regexp query on keyword field where only doc values are enabled":
 
@@ -343,6 +397,12 @@ setup:
         body: { query: { regexp: { keyword: { value: "k.*1" } } } }
   - length:   { hits.hits: 1  }
 
+  - do:
+      search:
+        index: test
+        body: { query: { regexp: { keyword_high_cardinality: { value: "k.*1" } } } }
+  - length: { hits.hits: 1 }
+
 ---
 "Test match query on boolean field where only doc values are enabled":
 
diff --git a/server/src/main/java/org/elasticsearch/index/mapper/KeywordFieldMapper.java b/server/src/main/java/org/elasticsearch/index/mapper/KeywordFieldMapper.java
index b4862ed8fd592..06eacb025db5c 100644
--- a/server/src/main/java/org/elasticsearch/index/mapper/KeywordFieldMapper.java
+++ b/server/src/main/java/org/elasticsearch/index/mapper/KeywordFieldMapper.java
@@ -71,14 +71,19 @@
 import org.elasticsearch.index.similarity.SimilarityProvider;
 import org.elasticsearch.script.Script;
 import org.elasticsearch.script.ScriptCompiler;
+import org.elasticsearch.script.SortedBinaryDocValuesStringFieldScript;
 import org.elasticsearch.script.SortedSetDocValuesStringFieldScript;
 import org.elasticsearch.script.StringFieldScript;
 import org.elasticsearch.script.field.KeywordDocValuesField;
 import org.elasticsearch.search.aggregations.support.CoreValuesSourceType;
 import org.elasticsearch.search.lookup.FieldValues;
 import org.elasticsearch.search.lookup.SearchLookup;
+import org.elasticsearch.search.runtime.StringScriptFieldFuzzyQuery;
 import org.elasticsearch.search.runtime.StringScriptFieldPrefixQuery;
+import org.elasticsearch.search.runtime.StringScriptFieldRangeQuery;
+import org.elasticsearch.search.runtime.StringScriptFieldRegexpQuery;
 import org.elasticsearch.search.runtime.StringScriptFieldTermQuery;
+import org.elasticsearch.search.runtime.StringScriptFieldTermsQuery;
 import org.elasticsearch.search.runtime.StringScriptFieldWildcardQuery;
 import org.elasticsearch.xcontent.Text;
 import org.elasticsearch.xcontent.XContentBuilder;
@@ -97,6 +102,7 @@
 import java.util.Objects;
 import java.util.Set;
 import java.util.function.Supplier;
+import java.util.stream.Collectors;
 
 import static org.apache.lucene.index.IndexWriter.MAX_TERM_LENGTH;
 import static org.elasticsearch.core.Strings.format;
@@ -616,6 +622,14 @@ public Query termQuery(Object value, SearchExecutionContext context) {
             failIfNotIndexedNorDocValuesFallback(context);
             if (indexType.hasTerms()) {
                 return super.termQuery(value, context);
+            } else if (storedInBinaryDocValues()) {
+                return new StringScriptFieldTermQuery(
+                    new Script(""),
+                    ctx -> new SortedBinaryDocValuesStringFieldScript(binaryDocValuesName(), context.lookup(), ctx),
+                    name(),
+                    indexedValueForSearch(value).utf8ToString(),
+                    false
+                );
             } else {
                 return SortedSetDocValuesField.newSlowExactQuery(name(), indexedValueForSearch(value));
             }
@@ -626,6 +640,13 @@ public Query termsQuery(Collection<?> values, SearchExecutionContext context) {
             failIfNotIndexedNorDocValuesFallback(context);
             if (indexType.hasTerms()) {
                 return super.termsQuery(values, context);
+            } else if (storedInBinaryDocValues()) {
+                return new StringScriptFieldTermsQuery(
+                    new Script(""),
+                    ctx -> new SortedBinaryDocValuesStringFieldScript(binaryDocValuesName(), context.lookup(), ctx),
+                    name(),
+                    values.stream().map(this::indexedValueForSearch).map(BytesRef::utf8ToString).collect(Collectors.toSet())
+                );
             } else {
                 Collection<BytesRef> bytesRefs = values.stream().map(this::indexedValueForSearch).toList();
                 return SortedSetDocValuesField.newSlowSetQuery(name(), bytesRefs);
@@ -643,6 +664,16 @@ public Query rangeQuery(
             failIfNotIndexedNorDocValuesFallback(context);
             if (indexType.hasTerms()) {
                 return super.rangeQuery(lowerTerm, upperTerm, includeLower, includeUpper, context);
+            } else if (storedInBinaryDocValues()) {
+                return new StringScriptFieldRangeQuery(
+                    new Script(""),
+                    ctx -> new SortedBinaryDocValuesStringFieldScript(binaryDocValuesName(), context.lookup(), ctx),
+                    name(),
+                    lowerTerm == null ? null : indexedValueForSearch(lowerTerm).utf8ToString(),
+                    upperTerm == null ? null : indexedValueForSearch(upperTerm).utf8ToString(),
+                    includeLower,
+                    includeUpper
+                );
             } else {
                 return SortedSetDocValuesField.newSlowRangeQuery(
                     name(),
@@ -667,6 +698,16 @@ public Query fuzzyQuery(
             failIfNotIndexedNorDocValuesFallback(context);
             if (indexType.hasTerms()) {
                 return super.fuzzyQuery(value, fuzziness, prefixLength, maxExpansions, transpositions, context, rewriteMethod);
+            } else if (storedInBinaryDocValues()) {
+                return StringScriptFieldFuzzyQuery.build(
+                    new Script(""),
+                    ctx -> new SortedBinaryDocValuesStringFieldScript(binaryDocValuesName(), context.lookup(), ctx),
+                    name(),
+                    indexedValueForSearch(value).utf8ToString(),
+                    fuzziness.asDistance(BytesRefs.toString(value)),
+                    prefixLength,
+                    transpositions
+                );
             } else {
                 return new FuzzyQuery(
                     new Term(name(), indexedValueForSearch(value)),
@@ -689,6 +730,14 @@ public Query prefixQuery(
             failIfNotIndexedNorDocValuesFallback(context);
             if (indexType.hasTerms()) {
                 return super.prefixQuery(value, method, caseInsensitive, context);
+            } else if (storedInBinaryDocValues()) {
+                return new StringScriptFieldPrefixQuery(
+                    new Script(""),
+                    ctx -> new SortedBinaryDocValuesStringFieldScript(binaryDocValuesName(), context.lookup(), ctx),
+                    name(),
+                    indexedValueForSearch(value).utf8ToString(),
+                    caseInsensitive
+                );
             } else {
                 if (caseInsensitive == false) {
                     Term prefix = new Term(name(), indexedValueForSearch(value));
@@ -709,6 +758,14 @@ public Query termQueryCaseInsensitive(Object value, SearchExecutionContext conte
             failIfNotIndexedNorDocValuesFallback(context);
             if (indexType.hasTerms()) {
                 return super.termQueryCaseInsensitive(value, context);
+            } else if (storedInBinaryDocValues()) {
+                return new StringScriptFieldTermQuery(
+                    new Script(""),
+                    ctx -> new SortedBinaryDocValuesStringFieldScript(binaryDocValuesName(), context.lookup(), ctx),
+                    name(),
+                    indexedValueForSearch(value).utf8ToString(),
+                    true
+                );
             } else {
                 return new StringScriptFieldTermQuery(
                     new Script(""),
@@ -726,7 +783,11 @@ public TermsEnum getTerms(IndexReader reader, String prefix, boolean caseInsensi
             if (indexType.hasTerms()) {
                 terms = MultiTerms.getTerms(reader, name());
             } else if (hasDocValues()) {
-                terms = SortedSetDocValuesTerms.getTerms(reader, name());
+                if (storedInBinaryDocValues()) {
+                    throw new UnsupportedOperationException("TODO");
+                } else {
+                    terms = SortedSetDocValuesTerms.getTerms(reader, name());
+                }
             }
             if (terms == null) {
                 // Field does not exist on this shard.
@@ -756,6 +817,10 @@ public String typeName() {
             return CONTENT_TYPE;
         }
 
+        public boolean storedInBinaryDocValues() {
+            return docValuesParameters.enabled() && docValuesParameters.cardinality() == DocValuesParameter.Values.Cardinality.HIGH;
+        }
+
         public String binaryDocValuesName() {
             return name() + "._dv";
         }
@@ -772,6 +837,9 @@ NamedAnalyzer normalizer() {
         @Override
         public BlockLoader blockLoader(BlockLoaderContext blContext) {
             if (hasDocValues() && (blContext.fieldExtractPreference() != FieldExtractPreference.STORED || isSyntheticSourceEnabled())) {
+                if (storedInBinaryDocValues()) {
+                    throw new UnsupportedOperationException("TODO");
+                }
                 BlockLoaderFunctionConfig cfg = blContext.blockLoaderFunctionConfig();
                 if (cfg == null) {
                     return new BytesRefsFromOrdsBlockLoader(name());
@@ -997,17 +1065,17 @@ public Query wildcardQuery(
                 } else {
                     value = indexedValueForSearch(value).utf8ToString();
                 }
-                if (caseInsensitive == false) {
+
+                if (caseInsensitive == false && docValuesParameters.cardinality() == DocValuesParameter.Values.Cardinality.LOW) {
                     Term term = new Term(name(), value);
                     return new WildcardQuery(term, Operations.DEFAULT_DETERMINIZE_WORK_LIMIT, MultiTermQuery.DOC_VALUES_REWRITE);
                 }
-                return new StringScriptFieldWildcardQuery(
-                    new Script(""),
-                    ctx -> new SortedSetDocValuesStringFieldScript(name(), context.lookup(), ctx),
-                    name(),
-                    value,
-                    caseInsensitive
-                );
+
+                StringFieldScript.LeafFactory leafFactory = docValuesParameters.cardinality() == DocValuesParameter.Values.Cardinality.LOW
+                    ? ctx -> new SortedSetDocValuesStringFieldScript(name(), context.lookup(), ctx)
+                    : ctx -> new SortedBinaryDocValuesStringFieldScript(binaryDocValuesName(), context.lookup(), ctx);
+
+                return new StringScriptFieldWildcardQuery(new Script(""), leafFactory, name(), value, caseInsensitive);
             }
         }
 
@@ -1022,8 +1090,19 @@ public Query normalizedWildcardQuery(String value, MultiTermQuery.RewriteMethod
                 } else {
                     value = indexedValueForSearch(value).utf8ToString();
                 }
-                Term term = new Term(name(), value);
-                return new WildcardQuery(term, Operations.DEFAULT_DETERMINIZE_WORK_LIMIT, MultiTermQuery.DOC_VALUES_REWRITE);
+
+                if (storedInBinaryDocValues()) {
+                    return new StringScriptFieldWildcardQuery(
+                        new Script(""),
+                        ctx -> new SortedBinaryDocValuesStringFieldScript(binaryDocValuesName(), context.lookup(), ctx),
+                        name(),
+                        value,
+                        false
+                    );
+                } else {
+                    Term term = new Term(name(), value);
+                    return new WildcardQuery(term, Operations.DEFAULT_DETERMINIZE_WORK_LIMIT, MultiTermQuery.DOC_VALUES_REWRITE);
+                }
             }
         }
 
@@ -1043,14 +1122,27 @@ public Query regexpQuery(
                 if (matchFlags != 0) {
                     throw new IllegalArgumentException("Match flags not yet implemented [" + matchFlags + "]");
                 }
-                return new RegexpQuery(
-                    new Term(name(), indexedValueForSearch(value)),
-                    syntaxFlags,
-                    matchFlags,
-                    RegexpQuery.DEFAULT_PROVIDER,
-                    maxDeterminizedStates,
-                    MultiTermQuery.DOC_VALUES_REWRITE
-                );
+
+                if (storedInBinaryDocValues()) {
+                    return new StringScriptFieldRegexpQuery(
+                        new Script(""),
+                        ctx -> new SortedBinaryDocValuesStringFieldScript(binaryDocValuesName(), context.lookup(), ctx),
+                        name(),
+                        value,
+                        syntaxFlags,
+                        matchFlags,
+                        maxDeterminizedStates
+                    );
+                } else {
+                    return new RegexpQuery(
+                        new Term(name(), indexedValueForSearch(value)),
+                        syntaxFlags,
+                        matchFlags,
+                        RegexpQuery.DEFAULT_PROVIDER,
+                        maxDeterminizedStates,
+                        MultiTermQuery.DOC_VALUES_REWRITE
+                    );
+                }
             }
         }
 
@@ -1245,7 +1337,7 @@ private boolean indexValue(DocumentParserContext context, XContentString value)
             throw new IllegalArgumentException(msg);
         }
 
-        if (docValuesParameters.enabled() && docValuesParameters.cardinality() == DocValuesParameter.Values.Cardinality.HIGH) {
+        if (fieldType().storedInBinaryDocValues()) {
             assert fieldType.docValuesType() == DocValuesType.NONE;
             KeywordBinaryDocValuesField field = (KeywordBinaryDocValuesField) context.doc().getField(fieldType().binaryDocValuesName());
             if (field == null) {
@@ -1255,8 +1347,11 @@ private boolean indexValue(DocumentParserContext context, XContentString value)
             field.add(binaryValue);
         }
 
-        Field field = buildKeywordField(binaryValue);
-        context.doc().add(field);
+        // Skip adding the field if we're using binary doc values (cardinality is high) and the field is neither indexed nor stored.
+        if (fieldType.indexOptions() != IndexOptions.NONE || fieldType.docValuesType() != DocValuesType.NONE || fieldType.stored()) {
+            Field field = buildKeywordField(binaryValue);
+            context.doc().add(field);
+        }
 
         if (fieldType().hasDocValues() == false && fieldType.omitNorms()) {
             context.addToFieldNames(fieldType().name());
diff --git a/server/src/main/java/org/elasticsearch/script/SortedBinaryDocValuesStringFieldScript.java b/server/src/main/java/org/elasticsearch/script/SortedBinaryDocValuesStringFieldScript.java
new file mode 100644
index 0000000000000..b0b44e4e3884d
--- /dev/null
+++ b/server/src/main/java/org/elasticsearch/script/SortedBinaryDocValuesStringFieldScript.java
@@ -0,0 +1,59 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the "Elastic License
+ * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
+ * Public License v 1"; you may not use this file except in compliance with, at
+ * your election, the "Elastic License 2.0", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+package org.elasticsearch.script;
+
+import org.apache.lucene.index.DocValues;
+import org.apache.lucene.index.LeafReaderContext;
+import org.apache.lucene.util.BytesRef;
+import org.elasticsearch.index.fielddata.MultiValuedSortedBinaryDocValues;
+import org.elasticsearch.index.fielddata.SortedBinaryDocValues;
+import org.elasticsearch.index.mapper.OnScriptError;
+import org.elasticsearch.search.lookup.SearchLookup;
+
+import java.io.IOException;
+import java.util.Map;
+
+public class SortedBinaryDocValuesStringFieldScript extends StringFieldScript {
+    private final SortedBinaryDocValues sortedBinaryDocValues;
+    boolean hasValue = false;
+
+    public SortedBinaryDocValuesStringFieldScript(String fieldName, SearchLookup searchLookup, LeafReaderContext ctx) {
+        super(fieldName, Map.of(), searchLookup, OnScriptError.FAIL, ctx);
+        try {
+            var binaryDocValues = DocValues.getBinary(ctx.reader(), fieldName);
+            sortedBinaryDocValues = new MultiValuedSortedBinaryDocValues(binaryDocValues);
+        } catch (IOException e) {
+            throw new IllegalStateException("Cannot load doc values", e);
+        }
+    }
+
+    @Override
+    public void setDocument(int docID) {
+        try {
+            hasValue = sortedBinaryDocValues.advanceExact(docID);
+        } catch (IOException e) {
+            throw new IllegalStateException("Cannot load doc values", e);
+        }
+    }
+
+    @Override
+    public void execute() {
+        try {
+            if (hasValue) {
+                for (int i = 0; i < sortedBinaryDocValues.docValueCount(); i++) {
+                    BytesRef bytesRef = sortedBinaryDocValues.nextValue();
+                    emit(bytesRef.utf8ToString());
+                }
+            }
+        } catch (IOException e) {
+            throw new IllegalStateException("Cannot load doc values", e);
+        }
+    }
+}

From 36ffba469a9ec37ccb7d76df9d54a82ed51607cc Mon Sep 17 00:00:00 2001
From: Jordan Powers <jordan.powers@elastic.co>
Date: Mon, 24 Nov 2025 16:22:07 -0800
Subject: [PATCH 05/14] Fix blockloaders

---
 .../index/mapper/KeywordFieldMapper.java      | 25 +++++++++++--------
 .../KeywordFieldBlockLoaderTests.java         | 11 ++++++++
 2 files changed, 26 insertions(+), 10 deletions(-)

diff --git a/server/src/main/java/org/elasticsearch/index/mapper/KeywordFieldMapper.java b/server/src/main/java/org/elasticsearch/index/mapper/KeywordFieldMapper.java
index 06eacb025db5c..6383e4ddfef5f 100644
--- a/server/src/main/java/org/elasticsearch/index/mapper/KeywordFieldMapper.java
+++ b/server/src/main/java/org/elasticsearch/index/mapper/KeywordFieldMapper.java
@@ -64,6 +64,7 @@
 import org.elasticsearch.index.fielddata.plain.BytesBinaryIndexFieldData;
 import org.elasticsearch.index.fielddata.plain.SortedSetOrdinalsIndexFieldData;
 import org.elasticsearch.index.mapper.blockloader.BlockLoaderFunctionConfig;
+import org.elasticsearch.index.mapper.blockloader.docvalues.BytesRefsFromCustomBinaryBlockLoader;
 import org.elasticsearch.index.mapper.blockloader.docvalues.BytesRefsFromOrdsBlockLoader;
 import org.elasticsearch.index.mapper.blockloader.docvalues.fn.Utf8CodePointsFromOrdsBlockLoader;
 import org.elasticsearch.index.query.AutomatonQueryWithDescription;
@@ -393,11 +394,9 @@ protected Parameter<?>[] getParameters() {
         }
 
         private IndexType buildIndexType(FieldType fieldType) {
-            if (fieldType.indexOptions() == IndexOptions.NONE && fieldType.docValuesType() == DocValuesType.NONE) {
-                var docValuesParameters = docValuesParameters();
-                if (docValuesParameters.enabled() && docValuesParameters.cardinality() == DocValuesParameter.Values.Cardinality.HIGH) {
-                    return IndexType.docValuesOnly();
-                }
+            var docValuesParameters = docValuesParameters();
+            if (docValuesParameters.enabled() && docValuesParameters.cardinality() == DocValuesParameter.Values.Cardinality.HIGH) {
+                return IndexType.terms(fieldType.indexOptions() != IndexOptions.NONE, true);
             }
 
             return IndexType.terms(fieldType);
@@ -837,15 +836,21 @@ NamedAnalyzer normalizer() {
         @Override
         public BlockLoader blockLoader(BlockLoaderContext blContext) {
             if (hasDocValues() && (blContext.fieldExtractPreference() != FieldExtractPreference.STORED || isSyntheticSourceEnabled())) {
-                if (storedInBinaryDocValues()) {
-                    throw new UnsupportedOperationException("TODO");
-                }
                 BlockLoaderFunctionConfig cfg = blContext.blockLoaderFunctionConfig();
                 if (cfg == null) {
-                    return new BytesRefsFromOrdsBlockLoader(name());
+                    if (storedInBinaryDocValues()) {
+                        return new BytesRefsFromCustomBinaryBlockLoader(binaryDocValuesName());
+                    } else {
+                        return new BytesRefsFromOrdsBlockLoader(name());
+                    }
                 }
                 if (cfg.function() == BlockLoaderFunctionConfig.Function.LENGTH) {
-                    return new Utf8CodePointsFromOrdsBlockLoader(((BlockLoaderFunctionConfig.JustWarnings) cfg).warnings(), name());
+                    if (storedInBinaryDocValues()) {
+                        // TODO: Support the length-only optimization for binary doc values
+                        return new BytesRefsFromCustomBinaryBlockLoader(binaryDocValuesName());
+                    } else {
+                        return new Utf8CodePointsFromOrdsBlockLoader(((BlockLoaderFunctionConfig.JustWarnings) cfg).warnings(), name());
+                    }
                 }
                 throw new UnsupportedOperationException("unknown fusion config [" + cfg.function() + "]");
             }
diff --git a/server/src/test/java/org/elasticsearch/index/mapper/blockloader/KeywordFieldBlockLoaderTests.java b/server/src/test/java/org/elasticsearch/index/mapper/blockloader/KeywordFieldBlockLoaderTests.java
index 54004022c32b6..bf1fb264cf2c9 100644
--- a/server/src/test/java/org/elasticsearch/index/mapper/blockloader/KeywordFieldBlockLoaderTests.java
+++ b/server/src/test/java/org/elasticsearch/index/mapper/blockloader/KeywordFieldBlockLoaderTests.java
@@ -67,6 +67,17 @@ public static Object expectedValue(Map<String, Object> fieldMapping, Object valu
         return maybeFoldList(resultList);
     }
 
+    public static boolean hasDocValues(Map<String, Object> fieldMapping, boolean defaultValue) {
+        Object value = fieldMapping.getOrDefault("doc_values", defaultValue);
+        if (value instanceof Boolean b) {
+            return b;
+        } else if (value instanceof Map) {
+            return true;
+        } else {
+            throw new IllegalArgumentException("Unexpected value [" + value + "] for mapping parameter [doc_values]");
+        }
+    }
+
     private static BytesRef convert(String value, String nullValue, int ignoreAbove) {
         if (value == null) {
             if (nullValue != null) {

From 0db280f7a4a4be51265f2030b1f9dc0049cdadaa Mon Sep 17 00:00:00 2001
From: Jordan Powers <jordanpowers1227@gmail.com>
Date: Mon, 24 Nov 2025 16:34:41 -0800
Subject: [PATCH 06/14] Update docs/changelog/138548.yaml

---
 docs/changelog/138548.yaml | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 docs/changelog/138548.yaml

diff --git a/docs/changelog/138548.yaml b/docs/changelog/138548.yaml
new file mode 100644
index 0000000000000..f7787059385b4
--- /dev/null
+++ b/docs/changelog/138548.yaml
@@ -0,0 +1,5 @@
+pr: 138548
+summary: Store high-cardinality keyword fields in binary doc values
+area: Mapping
+type: feature
+issues: []

From 10f07cd3e6563443f5a321af6684566eb4c9ba9d Mon Sep 17 00:00:00 2001
From: Jordan Powers <jordan.powers@elastic.co>
Date: Wed, 26 Nov 2025 08:26:57 -0800
Subject: [PATCH 07/14] Fix parsing of doc values parameter

---
 .../java/org/elasticsearch/index/mapper/FieldMapper.java  | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/server/src/main/java/org/elasticsearch/index/mapper/FieldMapper.java b/server/src/main/java/org/elasticsearch/index/mapper/FieldMapper.java
index cea39b536e838..b235f837b6970 100644
--- a/server/src/main/java/org/elasticsearch/index/mapper/FieldMapper.java
+++ b/server/src/main/java/org/elasticsearch/index/mapper/FieldMapper.java
@@ -1444,6 +1444,14 @@ public void parse(String field, MappingParserContext context, Object value) {
                 } else {
                     setValue(Values.DISABLED);
                 }
+            } else if (value instanceof String) {
+                if (value.equals("true")) {
+                    setValue(getDefaultValue());
+                } else if (value.equals("false")) {
+                    setValue(Values.DISABLED);
+                } else {
+                    throw new IllegalArgumentException("Illegal value [" + value + "] for parameter [" + name + "]");
+                }
             } else if (value instanceof Map) {
                 @SuppressWarnings("unchecked")
                 Map<String, Object> valueMap = (Map<String, Object>) value;

From 9f60db7ec9988e0cd602c93be312380252e720d1 Mon Sep 17 00:00:00 2001
From: Jordan Powers <jordan.powers@elastic.co>
Date: Wed, 26 Nov 2025 10:29:23 -0800
Subject: [PATCH 08/14] Consolidate BinaryDVLeafFieldData

---
 .../plain/AbstractBinaryDVLeafFieldData.java  | 35 -------------------
 .../plain/BytesBinaryIndexFieldData.java      |  8 ++---
 ... => MultiValuedBinaryDVLeafFieldData.java} | 21 +++++++++--
 .../plain/StringBinaryDVLeafFieldData.java    | 31 ----------------
 .../plain/StringBinaryIndexFieldData.java     |  8 ++---
 5 files changed, 26 insertions(+), 77 deletions(-)
 delete mode 100644 server/src/main/java/org/elasticsearch/index/fielddata/plain/AbstractBinaryDVLeafFieldData.java
 rename server/src/main/java/org/elasticsearch/index/fielddata/plain/{BytesBinaryDVLeafFieldData.java => MultiValuedBinaryDVLeafFieldData.java} (63%)
 delete mode 100644 server/src/main/java/org/elasticsearch/index/fielddata/plain/StringBinaryDVLeafFieldData.java

diff --git a/server/src/main/java/org/elasticsearch/index/fielddata/plain/AbstractBinaryDVLeafFieldData.java b/server/src/main/java/org/elasticsearch/index/fielddata/plain/AbstractBinaryDVLeafFieldData.java
deleted file mode 100644
index ce332e28d2508..0000000000000
--- a/server/src/main/java/org/elasticsearch/index/fielddata/plain/AbstractBinaryDVLeafFieldData.java
+++ /dev/null
@@ -1,35 +0,0 @@
-/*
- * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
- * or more contributor license agreements. Licensed under the "Elastic License
- * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
- * Public License v 1"; you may not use this file except in compliance with, at
- * your election, the "Elastic License 2.0", the "GNU Affero General Public
- * License v3.0 only", or the "Server Side Public License, v 1".
- */
-
-package org.elasticsearch.index.fielddata.plain;
-
-import org.apache.lucene.index.BinaryDocValues;
-import org.elasticsearch.index.fielddata.LeafFieldData;
-import org.elasticsearch.index.fielddata.MultiValuedSortedBinaryDocValues;
-import org.elasticsearch.index.fielddata.SortedBinaryDocValues;
-
-abstract class AbstractBinaryDVLeafFieldData implements LeafFieldData {
-    private final BinaryDocValues values;
-
-    AbstractBinaryDVLeafFieldData(BinaryDocValues values) {
-        super();
-        this.values = values;
-    }
-
-    @Override
-    public long ramBytesUsed() {
-        return 0; // not exposed by Lucene
-    }
-
-    @Override
-    public SortedBinaryDocValues getBytesValues() {
-        return new MultiValuedSortedBinaryDocValues(values);
-    }
-
-}
diff --git a/server/src/main/java/org/elasticsearch/index/fielddata/plain/BytesBinaryIndexFieldData.java b/server/src/main/java/org/elasticsearch/index/fielddata/plain/BytesBinaryIndexFieldData.java
index cc3469a9dcb44..043857ae0a0fc 100644
--- a/server/src/main/java/org/elasticsearch/index/fielddata/plain/BytesBinaryIndexFieldData.java
+++ b/server/src/main/java/org/elasticsearch/index/fielddata/plain/BytesBinaryIndexFieldData.java
@@ -28,7 +28,7 @@
 
 import java.io.IOException;
 
-public class BytesBinaryIndexFieldData implements IndexFieldData<BytesBinaryDVLeafFieldData> {
+public class BytesBinaryIndexFieldData implements IndexFieldData<MultiValuedBinaryDVLeafFieldData> {
 
     protected final String fieldName;
     protected final ValuesSourceType valuesSourceType;
@@ -74,16 +74,16 @@ public BucketedSort newBucketedSort(
     }
 
     @Override
-    public BytesBinaryDVLeafFieldData load(LeafReaderContext context) {
+    public MultiValuedBinaryDVLeafFieldData load(LeafReaderContext context) {
         try {
-            return new BytesBinaryDVLeafFieldData(DocValues.getBinary(context.reader(), fieldName), toScriptFieldFactory);
+            return new MultiValuedBinaryDVLeafFieldData(DocValues.getBinary(context.reader(), fieldName), toScriptFieldFactory);
         } catch (IOException e) {
             throw new IllegalStateException("Cannot load doc values", e);
         }
     }
 
     @Override
-    public BytesBinaryDVLeafFieldData loadDirect(LeafReaderContext context) {
+    public MultiValuedBinaryDVLeafFieldData loadDirect(LeafReaderContext context) {
         return load(context);
     }
 
diff --git a/server/src/main/java/org/elasticsearch/index/fielddata/plain/BytesBinaryDVLeafFieldData.java b/server/src/main/java/org/elasticsearch/index/fielddata/plain/MultiValuedBinaryDVLeafFieldData.java
similarity index 63%
rename from server/src/main/java/org/elasticsearch/index/fielddata/plain/BytesBinaryDVLeafFieldData.java
rename to server/src/main/java/org/elasticsearch/index/fielddata/plain/MultiValuedBinaryDVLeafFieldData.java
index 1d99083ed355e..eb73e423c1c42 100644
--- a/server/src/main/java/org/elasticsearch/index/fielddata/plain/BytesBinaryDVLeafFieldData.java
+++ b/server/src/main/java/org/elasticsearch/index/fielddata/plain/MultiValuedBinaryDVLeafFieldData.java
@@ -10,20 +10,35 @@
 package org.elasticsearch.index.fielddata.plain;
 
 import org.apache.lucene.index.BinaryDocValues;
+import org.elasticsearch.index.fielddata.LeafFieldData;
+import org.elasticsearch.index.fielddata.MultiValuedSortedBinaryDocValues;
 import org.elasticsearch.index.fielddata.SortedBinaryDocValues;
 import org.elasticsearch.script.field.DocValuesScriptFieldFactory;
 import org.elasticsearch.script.field.ToScriptFieldFactory;
 
-final class BytesBinaryDVLeafFieldData extends AbstractBinaryDVLeafFieldData {
+public final class MultiValuedBinaryDVLeafFieldData implements LeafFieldData {
+    private final BinaryDocValues values;
     private final ToScriptFieldFactory<SortedBinaryDocValues> toScriptFieldFactory;
 
-    BytesBinaryDVLeafFieldData(BinaryDocValues values, ToScriptFieldFactory<SortedBinaryDocValues> toScriptFieldFactory) {
-        super(values);
+    MultiValuedBinaryDVLeafFieldData(BinaryDocValues values, ToScriptFieldFactory<SortedBinaryDocValues> toScriptFieldFactory) {
+        super();
+        this.values = values;
         this.toScriptFieldFactory = toScriptFieldFactory;
     }
 
+    @Override
+    public long ramBytesUsed() {
+        return 0; // not exposed by Lucene
+    }
+
+    @Override
+    public SortedBinaryDocValues getBytesValues() {
+        return new MultiValuedSortedBinaryDocValues(values);
+    }
+
     @Override
     public DocValuesScriptFieldFactory getScriptFieldFactory(String name) {
         return toScriptFieldFactory.getScriptFieldFactory(getBytesValues(), name);
     }
+
 }
diff --git a/server/src/main/java/org/elasticsearch/index/fielddata/plain/StringBinaryDVLeafFieldData.java b/server/src/main/java/org/elasticsearch/index/fielddata/plain/StringBinaryDVLeafFieldData.java
deleted file mode 100644
index 032ea2a022b25..0000000000000
--- a/server/src/main/java/org/elasticsearch/index/fielddata/plain/StringBinaryDVLeafFieldData.java
+++ /dev/null
@@ -1,31 +0,0 @@
-/*
- * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
- * or more contributor license agreements. Licensed under the "Elastic License
- * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
- * Public License v 1"; you may not use this file except in compliance with, at
- * your election, the "Elastic License 2.0", the "GNU Affero General Public
- * License v3.0 only", or the "Server Side Public License, v 1".
- */
-
-package org.elasticsearch.index.fielddata.plain;
-
-import org.apache.lucene.index.BinaryDocValues;
-import org.elasticsearch.index.fielddata.SortedBinaryDocValues;
-import org.elasticsearch.script.field.DocValuesScriptFieldFactory;
-import org.elasticsearch.script.field.ToScriptFieldFactory;
-
-final class StringBinaryDVLeafFieldData extends AbstractBinaryDVLeafFieldData {
-
-    protected final ToScriptFieldFactory<SortedBinaryDocValues> toScriptFieldFactory;
-
-    StringBinaryDVLeafFieldData(BinaryDocValues values, ToScriptFieldFactory<SortedBinaryDocValues> toScriptFieldFactory) {
-        super(values);
-
-        this.toScriptFieldFactory = toScriptFieldFactory;
-    }
-
-    @Override
-    public DocValuesScriptFieldFactory getScriptFieldFactory(String name) {
-        return toScriptFieldFactory.getScriptFieldFactory(getBytesValues(), name);
-    }
-}
diff --git a/server/src/main/java/org/elasticsearch/index/fielddata/plain/StringBinaryIndexFieldData.java b/server/src/main/java/org/elasticsearch/index/fielddata/plain/StringBinaryIndexFieldData.java
index 7c8b058cb01f1..012697e750227 100644
--- a/server/src/main/java/org/elasticsearch/index/fielddata/plain/StringBinaryIndexFieldData.java
+++ b/server/src/main/java/org/elasticsearch/index/fielddata/plain/StringBinaryIndexFieldData.java
@@ -26,7 +26,7 @@
 
 import java.io.IOException;
 
-public class StringBinaryIndexFieldData implements IndexFieldData<StringBinaryDVLeafFieldData> {
+public class StringBinaryIndexFieldData implements IndexFieldData<MultiValuedBinaryDVLeafFieldData> {
 
     protected final String fieldName;
     protected final ValuesSourceType valuesSourceType;
@@ -59,9 +59,9 @@ public SortField sortField(Object missingValue, MultiValueMode sortMode, Nested
     }
 
     @Override
-    public StringBinaryDVLeafFieldData load(LeafReaderContext context) {
+    public MultiValuedBinaryDVLeafFieldData load(LeafReaderContext context) {
         try {
-            return new StringBinaryDVLeafFieldData(DocValues.getBinary(context.reader(), fieldName), toScriptFieldFactory);
+            return new MultiValuedBinaryDVLeafFieldData(DocValues.getBinary(context.reader(), fieldName), toScriptFieldFactory);
         } catch (IOException e) {
             throw new IllegalStateException("Cannot load doc values", e);
         }
@@ -82,7 +82,7 @@ public BucketedSort newBucketedSort(
     }
 
     @Override
-    public StringBinaryDVLeafFieldData loadDirect(LeafReaderContext context) {
+    public MultiValuedBinaryDVLeafFieldData loadDirect(LeafReaderContext context) {
         return load(context);
     }
 }

From c5123a0f4e876003e1d3304266c6976f7e4236be Mon Sep 17 00:00:00 2001
From: Jordan Powers <jordan.powers@elastic.co>
Date: Wed, 26 Nov 2025 10:48:10 -0800
Subject: [PATCH 09/14] Gate binary doc values search tests behind node feature

---
 .../test/search/390_doc_values_search.yml     |  60 ---------
 .../search/395_binary_doc_values_search.yml   | 115 ++++++++++++++++++
 .../index/mapper/MapperFeatures.java          |   6 +-
 .../KeywordFieldSyntheticSourceSupport.java   |   5 +-
 4 files changed, 124 insertions(+), 62 deletions(-)
 create mode 100644 rest-api-spec/src/yamlRestTest/resources/rest-api-spec/test/search/395_binary_doc_values_search.yml

diff --git a/rest-api-spec/src/yamlRestTest/resources/rest-api-spec/test/search/390_doc_values_search.yml b/rest-api-spec/src/yamlRestTest/resources/rest-api-spec/test/search/390_doc_values_search.yml
index 0fa9478b7b070..aa8323edaa6e3 100644
--- a/rest-api-spec/src/yamlRestTest/resources/rest-api-spec/test/search/390_doc_values_search.yml
+++ b/rest-api-spec/src/yamlRestTest/resources/rest-api-spec/test/search/390_doc_values_search.yml
@@ -39,11 +39,6 @@ setup:
               keyword:
                 type: keyword
                 index: false
-              keyword_high_cardinality:
-                type: keyword
-                index: false
-                doc_values:
-                  cardinality: high
               boolean:
                 type: boolean
                 index: false
@@ -68,7 +63,6 @@ setup:
           short: 1
           date: "2017/01/01"
           keyword: "key1"
-          keyword_high_cardinality: "key1"
           boolean: "false"
           ip: "192.168.0.1"
           geo_point: [13.5, 34.89]
@@ -87,7 +81,6 @@ setup:
           short: 2
           date: "2017/01/02"
           keyword: "key2"
-          keyword_high_cardinality: "key2"
           boolean: "true"
           ip: "192.168.0.2"
           geo_point : [-63.24, 31.0]
@@ -278,12 +271,6 @@ setup:
         body: { query: { match: { keyword: { query: "key1" } } } }
   - length:   { hits.hits: 1  }
 
-  - do:
-      search:
-        index: test
-        body: { query: { match: { keyword_high_cardinality: { "query": "key1" } } } }
-  - length: { hits.hits: 1 }
-
 ---
 "Test terms query on keyword field where only doc values are enabled":
 
@@ -293,11 +280,6 @@ setup:
         body: { query: { terms: { keyword: [ "key1", "key2" ] } } }
   - length:   { hits.hits: 2  }
 
-  - do:
-      search:
-        index: test
-        body: { query: { terms: { keyword_high_cardinality: [ "key1", "key2" ] } } }
-
 ---
 "Test range query on keyword field where only doc values are enabled":
 
@@ -307,12 +289,6 @@ setup:
         body: { query: { range: { keyword: { gte: "key1" } } } }
   - length:   { hits.hits: 2  }
 
-  - do:
-      search:
-        index: test
-        body: { query: { range: { keyword_high_cardinality: { gte: "key1" } } } }
-  - length:   { hits.hits: 2  }
-
 ---
 "Test fuzzy query on keyword field where only doc values are enabled":
 
@@ -322,12 +298,6 @@ setup:
         body: { query: { fuzzy: { keyword: { value: "kay1", fuzziness: 1 } } } }
   - length:   { hits.hits: 1  }
 
-  - do:
-      search:
-        index: test
-        body: { query: { fuzzy: { keyword_high_cardinality: { value: "kay1", fuzziness: 1 } } } }
-  - length:   { hits.hits: 1  }
-
 ---
 "Test prefix query on keyword field where only doc values are enabled":
 
@@ -337,12 +307,6 @@ setup:
         body: { query: { prefix: { keyword: { value: "key" } } } }
   - length:   { hits.hits: 2  }
 
-  - do:
-      search:
-        index: test
-        body: { query: { prefix: { keyword_high_cardinality: { value: "key" } } } }
-  - length:   { hits.hits: 2  }
-
 ---
 "Test case insensitive term query on keyword field where only doc values are enabled":
 
@@ -352,12 +316,6 @@ setup:
         body: { query: { term: { keyword: { value: "KeY1", case_insensitive: true } } } }
   - length:   { hits.hits: 1  }
 
-  - do:
-      search:
-        index: test
-        body: { query: { term: { keyword_high_cardinality: { value: "KeY1", case_insensitive: true } } } }
-  - length:   { hits.hits: 1  }
-
 ---
 "Test wildcard query on keyword field where only doc values are enabled":
 
@@ -367,12 +325,6 @@ setup:
         body: { query: { wildcard: { keyword: { value: "k*1" } } } }
   - length:   { hits.hits: 1  }
 
-  - do:
-      search:
-        index: test
-        body: { query: { wildcard: { keyword_high_cardinality: { value: "k*1" } } } }
-  - length:   { hits.hits: 1  }
-
 ---
 "Test case insensitive wildcard query on keyword field where only doc values are enabled":
 
@@ -382,12 +334,6 @@ setup:
         body: { query: { wildcard: { keyword: { value: "K*1", case_insensitive: true } } } }
   - length:   { hits.hits: 1  }
 
-  - do:
-      search:
-        index: test
-        body: { query: { wildcard: { keyword_high_cardinality: { value: "K*1", case_insensitive: true } } } }
-  - length:   { hits.hits: 1  }
-
 ---
 "Test regexp query on keyword field where only doc values are enabled":
 
@@ -397,12 +343,6 @@ setup:
         body: { query: { regexp: { keyword: { value: "k.*1" } } } }
   - length:   { hits.hits: 1  }
 
-  - do:
-      search:
-        index: test
-        body: { query: { regexp: { keyword_high_cardinality: { value: "k.*1" } } } }
-  - length: { hits.hits: 1 }
-
 ---
 "Test match query on boolean field where only doc values are enabled":
 
diff --git a/rest-api-spec/src/yamlRestTest/resources/rest-api-spec/test/search/395_binary_doc_values_search.yml b/rest-api-spec/src/yamlRestTest/resources/rest-api-spec/test/search/395_binary_doc_values_search.yml
new file mode 100644
index 0000000000000..8f98e460d583f
--- /dev/null
+++ b/rest-api-spec/src/yamlRestTest/resources/rest-api-spec/test/search/395_binary_doc_values_search.yml
@@ -0,0 +1,115 @@
+---
+setup:
+  - requires:
+      cluster_features: ["mapper.keyword.store_high_cardinality_in_binary_doc_values"]
+      reason: "testing binary doc values search"
+
+  - do:
+      indices.create:
+        index:  test
+        body:
+          mappings:
+            dynamic: false
+            properties:
+              keyword:
+                type: keyword
+                index: false
+                doc_values:
+                  cardinality: high
+
+  - do:
+      index:
+        index: test
+        id: "1"
+        body:
+          keyword: "key1"
+
+  - do:
+      index:
+        index: test
+        id: "2"
+        body:
+          keyword: "key2"
+  - do:
+      indices.refresh: {}
+
+---
+"Test match query on keyword field where only binary doc values are enabled":
+
+  - do:
+      search:
+        index: test
+        body: { query: { match: { keyword: { query: "key1" } } } }
+  - length:   { hits.hits: 1  }
+
+---
+"Test terms query on keyword field where only binary doc values are enabled":
+
+  - do:
+      search:
+        index: test
+        body: { query: { terms: { keyword: [ "key1", "key2" ] } } }
+  - length:   { hits.hits: 2  }
+
+---
+"Test range query on keyword field where only binary doc values are enabled":
+
+  - do:
+      search:
+        index: test
+        body: { query: { range: { keyword: { gte: "key1" } } } }
+  - length:   { hits.hits: 2  }
+
+---
+"Test fuzzy query on keyword field where only binary doc values are enabled":
+
+  - do:
+      search:
+        index: test
+        body: { query: { fuzzy: { keyword: { value: "kay1", fuzziness: 1 } } } }
+  - length:   { hits.hits: 1  }
+
+---
+"Test prefix query on keyword field where only binary doc values are enabled":
+
+  - do:
+      search:
+        index: test
+        body: { query: { prefix: { keyword: { value: "key" } } } }
+  - length:   { hits.hits: 2  }
+
+---
+"Test case insensitive term query on keyword field where only binary doc values are enabled":
+
+  - do:
+      search:
+        index: test
+        body: { query: { term: { keyword: { value: "KeY1", case_insensitive: true } } } }
+  - length:   { hits.hits: 1  }
+
+---
+"Test wildcard query on keyword field where only binary doc values are enabled":
+
+  - do:
+      search:
+        index: test
+        body: { query: { wildcard: { keyword: { value: "k*1" } } } }
+  - length:   { hits.hits: 1  }
+
+---
+"Test case insensitive wildcard query on keyword field where only binary doc values are enabled":
+
+  - do:
+      search:
+        index: test
+        body: { query: { wildcard: { keyword: { value: "K*1", case_insensitive: true } } } }
+  - length:   { hits.hits: 1  }
+
+---
+"Test regexp query on keyword field where only binary doc values are enabled":
+
+  - do:
+      search:
+        index: test
+        body: { query: { regexp: { keyword: { value: "k.*1" } } } }
+  - length:   { hits.hits: 1  }
diff --git a/server/src/main/java/org/elasticsearch/index/mapper/MapperFeatures.java b/server/src/main/java/org/elasticsearch/index/mapper/MapperFeatures.java
index 00bc261960941..f6e0536c7188d 100644
--- a/server/src/main/java/org/elasticsearch/index/mapper/MapperFeatures.java
+++ b/server/src/main/java/org/elasticsearch/index/mapper/MapperFeatures.java
@@ -63,6 +63,9 @@ public class MapperFeatures implements FeatureSpecification {
     static final NodeFeature BASE64_DENSE_VECTORS = new NodeFeature("mapper.base64_dense_vectors");
     public static final NodeFeature GENERIC_VECTOR_FORMAT = new NodeFeature("mapper.vectors.generic_vector_format");
     public static final NodeFeature FIX_DENSE_VECTOR_WRONG_FIELDS = new NodeFeature("mapper.fix_dense_vector_wrong_fields");
+    static final NodeFeature STORE_HIGH_CARDINALITY_KEYWORDS_IN_BINARY_DOC_VALUES = new NodeFeature(
+        "mapper.keyword.store_high_cardinality_in_binary_doc_values"
+    );
 
     @Override
     public Set<NodeFeature> getTestFeatures() {
@@ -106,7 +109,8 @@ public Set<NodeFeature> getTestFeatures() {
             INDEX_MAPPING_IGNORE_DYNAMIC_BEYOND_FIELD_NAME_LIMIT,
             EXCLUDE_VECTORS_DOCVALUE_BUGFIX,
             BASE64_DENSE_VECTORS,
-            FIX_DENSE_VECTOR_WRONG_FIELDS
+            FIX_DENSE_VECTOR_WRONG_FIELDS,
+            STORE_HIGH_CARDINALITY_KEYWORDS_IN_BINARY_DOC_VALUES
         );
         if (ES93GenericFlatVectorsFormat.GENERIC_VECTOR_FORMAT.isEnabled()) {
             features = new HashSet<>(features);
diff --git a/test/framework/src/main/java/org/elasticsearch/index/mapper/KeywordFieldSyntheticSourceSupport.java b/test/framework/src/main/java/org/elasticsearch/index/mapper/KeywordFieldSyntheticSourceSupport.java
index 931ba021ae80b..2b600d961d62c 100644
--- a/test/framework/src/main/java/org/elasticsearch/index/mapper/KeywordFieldSyntheticSourceSupport.java
+++ b/test/framework/src/main/java/org/elasticsearch/index/mapper/KeywordFieldSyntheticSourceSupport.java
@@ -26,12 +26,14 @@ public class KeywordFieldSyntheticSourceSupport implements MapperTestCase.Synthe
     private final boolean store;
     private final FieldMapper.DocValuesParameter.Values docValues;
     private final String nullValue;
+    private final boolean allowIgnoredSource;
 
     KeywordFieldSyntheticSourceSupport(Integer ignoreAbove, boolean store, String nullValue, boolean allowIgnoredSource) {
         this.ignoreAbove = ignoreAbove;
         this.allIgnored = ignoreAbove != null && LuceneTestCase.rarely();
         this.store = store;
         this.nullValue = nullValue;
+        this.allowIgnoredSource = allowIgnoredSource;
 
         this.docValues = switch (ESTestCase.randomInt(allowIgnoredSource ? 2 : 1)) {
             case 0 -> new FieldMapper.DocValuesParameter.Values(true, FieldMapper.DocValuesParameter.Values.Cardinality.LOW);
@@ -50,7 +52,8 @@ public boolean ignoreAbove() {
     public boolean preservesExactSource() {
         // We opt in into fallback synthetic source implementation
         // if there is nothing else to use, and it preserves exact source data.
-        return store == false
+        return allowIgnoredSource
+            && store == false
             && (docValues.enabled() == false || docValues.cardinality() == FieldMapper.DocValuesParameter.Values.Cardinality.HIGH);
     }
 

From 6c3b14b961a1f2129dab39e12db1624633e094ea Mon Sep 17 00:00:00 2001
From: Jordan Powers <jordan.powers@elastic.co>
Date: Wed, 26 Nov 2025 11:16:52 -0800
Subject: [PATCH 10/14] Add javadoc

---
 .../index/fielddata/MultiValuedSortedBinaryDocValues.java     | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/server/src/main/java/org/elasticsearch/index/fielddata/MultiValuedSortedBinaryDocValues.java b/server/src/main/java/org/elasticsearch/index/fielddata/MultiValuedSortedBinaryDocValues.java
index cb48b900b3bc4..2b6293b584bb5 100644
--- a/server/src/main/java/org/elasticsearch/index/fielddata/MultiValuedSortedBinaryDocValues.java
+++ b/server/src/main/java/org/elasticsearch/index/fielddata/MultiValuedSortedBinaryDocValues.java
@@ -15,6 +15,10 @@
 
 import java.io.IOException;
 
+/**
+ * Wrapper around {@link BinaryDocValues} to decode the typical multivalued encoding used by
+ * {@link org.elasticsearch.index.mapper.BinaryFieldMapper.CustomBinaryDocValuesField}.
+ */
 public class MultiValuedSortedBinaryDocValues extends SortedBinaryDocValues {
 
     BinaryDocValues values;

From c1965a123d0de1138b5fbe5645f0c0bdb8c36552 Mon Sep 17 00:00:00 2001
From: Jordan Powers <jordan.powers@elastic.co>
Date: Wed, 26 Nov 2025 11:20:44 -0800
Subject: [PATCH 11/14] Fix compile error

---
 .../xpack/wildcard/mapper/WildcardFieldMapper.java         | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/x-pack/plugin/wildcard/src/main/java/org/elasticsearch/xpack/wildcard/mapper/WildcardFieldMapper.java b/x-pack/plugin/wildcard/src/main/java/org/elasticsearch/xpack/wildcard/mapper/WildcardFieldMapper.java
index 6dbf619e0c140..ec41abedca76e 100644
--- a/x-pack/plugin/wildcard/src/main/java/org/elasticsearch/xpack/wildcard/mapper/WildcardFieldMapper.java
+++ b/x-pack/plugin/wildcard/src/main/java/org/elasticsearch/xpack/wildcard/mapper/WildcardFieldMapper.java
@@ -1104,7 +1104,12 @@ public FieldMapper.Builder getMergeBuilder() {
     protected SyntheticSourceSupport syntheticSourceSupport() {
         return new SyntheticSourceSupport.Native(() -> {
             var layers = new ArrayList<CompositeSyntheticFieldLoader.Layer>();
-            layers.add(new BinaryDocValuesSyntheticFieldLoaderLayer(fullPath()));
+            layers.add(new BinaryDocValuesSyntheticFieldLoaderLayer(fullPath()) {
+                @Override
+                protected void writeValue(XContentBuilder b, BytesRef value) throws IOException {
+                    b.utf8Value(value.bytes, value.offset, value.length);
+                }
+            });
             if (ignoreAbove.valuesPotentiallyIgnored()) {
                 layers.add(new CompositeSyntheticFieldLoader.StoredFieldLayer(originalName()) {
                     @Override

From 1111dce77b1997bd44ed987b90f316b5ea540ce1 Mon Sep 17 00:00:00 2001
From: Jordan Powers <jordan.powers@elastic.co>
Date: Wed, 26 Nov 2025 12:02:45 -0800
Subject: [PATCH 12/14] Fix BinaryDocValuesSyntheticFieldLoaderLayer#valueCount

---
 .../index/mapper/BinaryDocValuesSyntheticFieldLoaderLayer.java | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/server/src/main/java/org/elasticsearch/index/mapper/BinaryDocValuesSyntheticFieldLoaderLayer.java b/server/src/main/java/org/elasticsearch/index/mapper/BinaryDocValuesSyntheticFieldLoaderLayer.java
index cfab076d41e9f..039ac053806da 100644
--- a/server/src/main/java/org/elasticsearch/index/mapper/BinaryDocValuesSyntheticFieldLoaderLayer.java
+++ b/server/src/main/java/org/elasticsearch/index/mapper/BinaryDocValuesSyntheticFieldLoaderLayer.java
@@ -31,13 +31,14 @@ protected BinaryDocValuesSyntheticFieldLoaderLayer(String name) {
 
     @Override
     public long valueCount() {
-        return bytesValues.docValueCount();
+        return bytesValues == null ? 0 : bytesValues.docValueCount();
     }
 
     @Override
     public DocValuesLoader docValuesLoader(LeafReader leafReader, int[] docIdsInLeaf) throws IOException {
         var docValues = leafReader.getBinaryDocValues(name);
         if (docValues == null) {
+            bytesValues = null;
             return null;
         }
 

From 05a2dce84207478c6d8fa73d4d210571befb1ff6 Mon Sep 17 00:00:00 2001
From: Jordan Powers <jordan.powers@elastic.co>
Date: Wed, 26 Nov 2025 13:44:53 -0800
Subject: [PATCH 13/14] Fix ClassCastException in blockloader tests

---
 .../blockloader/KeywordFieldBlockLoaderTests.java     | 11 -----------
 .../index/mapper/BlockLoaderTestCase.java             |  9 ++++++++-
 2 files changed, 8 insertions(+), 12 deletions(-)

diff --git a/server/src/test/java/org/elasticsearch/index/mapper/blockloader/KeywordFieldBlockLoaderTests.java b/server/src/test/java/org/elasticsearch/index/mapper/blockloader/KeywordFieldBlockLoaderTests.java
index bf1fb264cf2c9..54004022c32b6 100644
--- a/server/src/test/java/org/elasticsearch/index/mapper/blockloader/KeywordFieldBlockLoaderTests.java
+++ b/server/src/test/java/org/elasticsearch/index/mapper/blockloader/KeywordFieldBlockLoaderTests.java
@@ -67,17 +67,6 @@ public static Object expectedValue(Map<String, Object> fieldMapping, Object valu
         return maybeFoldList(resultList);
     }
 
-    public static boolean hasDocValues(Map<String, Object> fieldMapping, boolean defaultValue) {
-        Object value = fieldMapping.getOrDefault("doc_values", defaultValue);
-        if (value instanceof Boolean b) {
-            return b;
-        } else if (value instanceof Map) {
-            return true;
-        } else {
-            throw new IllegalArgumentException("Unexpected value [" + value + "] for mapping parameter [doc_values]");
-        }
-    }
-
     private static BytesRef convert(String value, String nullValue, int ignoreAbove) {
         if (value == null) {
             if (nullValue != null) {
diff --git a/test/framework/src/main/java/org/elasticsearch/index/mapper/BlockLoaderTestCase.java b/test/framework/src/main/java/org/elasticsearch/index/mapper/BlockLoaderTestCase.java
index 3b6c4ec5e0123..421133db82c18 100644
--- a/test/framework/src/main/java/org/elasticsearch/index/mapper/BlockLoaderTestCase.java
+++ b/test/framework/src/main/java/org/elasticsearch/index/mapper/BlockLoaderTestCase.java
@@ -275,6 +275,13 @@ private void processLevel(Map<String, Object> level, String field, ArrayList<Obj
     }
 
     public static boolean hasDocValues(Map<String, Object> fieldMapping, boolean defaultValue) {
-        return (boolean) fieldMapping.getOrDefault("doc_values", defaultValue);
+        Object value = fieldMapping.getOrDefault("doc_values", defaultValue);
+        if (value instanceof Boolean b) {
+            return b;
+        } else if (value instanceof Map) {
+            return true;
+        } else {
+            throw new IllegalArgumentException("Unexpected value [" + value + "] for mapping parameter [doc_values]");
+        }
     }
 }

From 91ea2ad95b8b82a1e24a241bdc57f6c4e100955c Mon Sep 17 00:00:00 2001
From: Jordan Powers <jordan.powers@elastic.co>
Date: Wed, 26 Nov 2025 14:21:02 -0800
Subject: [PATCH 14/14] Fix multivalued fields

---
 .../BinaryDocValuesSyntheticFieldLoaderLayer.java  | 11 ++++++-----
 .../index/mapper/KeywordFieldMapper.java           | 14 ++------------
 .../xpack/wildcard/mapper/WildcardFieldMapper.java |  7 +------
 3 files changed, 9 insertions(+), 23 deletions(-)

diff --git a/server/src/main/java/org/elasticsearch/index/mapper/BinaryDocValuesSyntheticFieldLoaderLayer.java b/server/src/main/java/org/elasticsearch/index/mapper/BinaryDocValuesSyntheticFieldLoaderLayer.java
index 039ac053806da..ac0f102094146 100644
--- a/server/src/main/java/org/elasticsearch/index/mapper/BinaryDocValuesSyntheticFieldLoaderLayer.java
+++ b/server/src/main/java/org/elasticsearch/index/mapper/BinaryDocValuesSyntheticFieldLoaderLayer.java
@@ -17,18 +17,16 @@
 
 import java.io.IOException;
 
-public abstract class BinaryDocValuesSyntheticFieldLoaderLayer implements CompositeSyntheticFieldLoader.DocValuesLayer {
+public final class BinaryDocValuesSyntheticFieldLoaderLayer implements CompositeSyntheticFieldLoader.DocValuesLayer {
 
     private final String name;
     private SortedBinaryDocValues bytesValues;
     private boolean hasValue;
 
-    protected BinaryDocValuesSyntheticFieldLoaderLayer(String name) {
+    public BinaryDocValuesSyntheticFieldLoaderLayer(String name) {
         this.name = name;
     }
 
-    protected abstract void writeValue(XContentBuilder b, BytesRef value) throws IOException;
-
     @Override
     public long valueCount() {
         return bytesValues == null ? 0 : bytesValues.docValueCount();
@@ -61,7 +59,10 @@ public void write(XContentBuilder b) throws IOException {
             return;
         }
 
-        writeValue(b, bytesValues.nextValue());
+        for (int i = 0; i < bytesValues.docValueCount(); ++i) {
+            BytesRef value = bytesValues.nextValue();
+            b.utf8Value(value.bytes, value.offset, value.length);
+        }
     }
 
     @Override
diff --git a/server/src/main/java/org/elasticsearch/index/mapper/KeywordFieldMapper.java b/server/src/main/java/org/elasticsearch/index/mapper/KeywordFieldMapper.java
index 16916ac241d52..f7f37e8727def 100644
--- a/server/src/main/java/org/elasticsearch/index/mapper/KeywordFieldMapper.java
+++ b/server/src/main/java/org/elasticsearch/index/mapper/KeywordFieldMapper.java
@@ -1497,12 +1497,7 @@ protected BytesRef preserve(BytesRef value) {
             } else {
                 assert offsetsFieldName == null;
                 assert indexSettings.sourceKeepMode() == SourceKeepMode.NONE;
-                layers.add(new BinaryDocValuesSyntheticFieldLoaderLayer(fieldType().binaryDocValuesName()) {
-                    @Override
-                    protected void writeValue(XContentBuilder b, BytesRef value) throws IOException {
-                        b.utf8Value(value.bytes, value.offset, value.length);
-                    }
-                });
+                layers.add(new BinaryDocValuesSyntheticFieldLoaderLayer(fieldType().binaryDocValuesName()));
             }
         }
 
@@ -1510,12 +1505,7 @@ protected void writeValue(XContentBuilder b, BytesRef value) throws IOException
         // extra copy of the field for supporting synthetic source. This layer will check that copy.
         if (fieldType().ignoreAbove.valuesPotentiallyIgnored()) {
             final String fieldName = fieldType().syntheticSourceFallbackFieldName();
-            layers.add(new BinaryDocValuesSyntheticFieldLoaderLayer(fieldName) {
-                @Override
-                public void writeValue(XContentBuilder b, BytesRef value) throws IOException {
-                    b.utf8Value(value.bytes, value.offset, value.length);
-                }
-            });
+            layers.add(new BinaryDocValuesSyntheticFieldLoaderLayer(fieldName));
         }
 
         return new CompositeSyntheticFieldLoader(leafFieldName, fullFieldName, layers);
diff --git a/x-pack/plugin/wildcard/src/main/java/org/elasticsearch/xpack/wildcard/mapper/WildcardFieldMapper.java b/x-pack/plugin/wildcard/src/main/java/org/elasticsearch/xpack/wildcard/mapper/WildcardFieldMapper.java
index ec41abedca76e..6dbf619e0c140 100644
--- a/x-pack/plugin/wildcard/src/main/java/org/elasticsearch/xpack/wildcard/mapper/WildcardFieldMapper.java
+++ b/x-pack/plugin/wildcard/src/main/java/org/elasticsearch/xpack/wildcard/mapper/WildcardFieldMapper.java
@@ -1104,12 +1104,7 @@ public FieldMapper.Builder getMergeBuilder() {
     protected SyntheticSourceSupport syntheticSourceSupport() {
         return new SyntheticSourceSupport.Native(() -> {
             var layers = new ArrayList<CompositeSyntheticFieldLoader.Layer>();
-            layers.add(new BinaryDocValuesSyntheticFieldLoaderLayer(fullPath()) {
-                @Override
-                protected void writeValue(XContentBuilder b, BytesRef value) throws IOException {
-                    b.utf8Value(value.bytes, value.offset, value.length);
-                }
-            });
+            layers.add(new BinaryDocValuesSyntheticFieldLoaderLayer(fullPath()));
             if (ignoreAbove.valuesPotentiallyIgnored()) {
                 layers.add(new CompositeSyntheticFieldLoader.StoredFieldLayer(originalName()) {
                     @Override