feat(writer): type-aware global-dict cardinality cap for Utf8 (#299)

The global-dict admission cap was a single 2048 constant. It was kept low because
a global dict pessimizes high-cardinality F64/I64 columns (ALP/bitpacked beat U16
dict codes) — but that ceiling also excluded text columns with thousands of
repeated distinct values (nyc-311 street/place names, 9k-28k distinct), pushing
them into costlier per-chunk fallbacks.

Split the cap: numeric stays 2048; Utf8 rises to 32768, the positive ceiling of
the per-chunk short[] code buffer (codePTypeForSize already emits U16 codes above
256, so no wire change). Threaded through isUtf8DictCandidate and the mid-file
ingest gate via the column's type.

Note: on very wide, high-cardinality text files the aggregate retained-code budget
(WriteOptions.globalDictMaxRetainedBytes, default 1 GB) may evict/demote columns;
the ADR-0021 eviction keeps this safe (no OOM) but may cap the realized gain until
the budget is tuned — deferred to measurement on the full corpus.

Verified: an 8000-distinct Utf8 column now produces a global DICT layout and
round-trips (integration test); dict-decision unit tests updated for the raised cap.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: dfa1

integration/src/test/java/io/github/dfa1/vortex/integration/DictValuesPoolCompressionIntegrationTest.java

@@ -89,6 +89,52 @@ void globalDictUtf8_valuesPool_isFsstCompressed_andRoundTrips(@TempDir Path tmp)
         }
     }
 
+    @Test
+    void utf8_cardinalityAbovePriorCap_admittedToGlobalDict(@TempDir Path tmp) throws IOException {
+        // Given — 8 000 distinct values: above the old 2048 numeric-era cap (so previously demoted
+        // to per-chunk), below the 32768 Utf8 cap, with >50% dedup so the ratio gate admits it.
+        Path file = tmp.resolve("high_card.vortex");
+        int rowsPerChunk = 20_000;
+        int chunkCount = 4;
+        int distinct = 8_000;
+
+        List<String> expected = new ArrayList<>();
+        try (var ch = FileChannel.open(file, StandardOpenOption.CREATE, StandardOpenOption.WRITE);
+             var sut = VortexWriter.create(ch, SCHEMA, WriteOptions.cascading(3))) {
+            // When
+            for (int c = 0; c < chunkCount; c++) {
+                String[] data = redundantChunk(rowsPerChunk, distinct, c * 101);
+                expected.addAll(List.of(data));
+                sut.writeChunk(Map.of(COL, data));
+            }
+        }
+
+        // Then — the column is stored as one global dictionary (a DICT layout node), not a per-chunk
+        // fallback. Before the type-aware cap a 8 000-distinct column produced no DICT layout.
+        try (var vf = VortexReader.open(file, ReadRegistry.loadAll())) {
+            assertThat(hasDictLayout(InspectorTree.build(vf).root()))
+                    .as("8 000-distinct Utf8 column admitted to the global dictionary")
+                    .isTrue();
+        }
+
+        // And every value round-trips exactly.
+        try (var vf = VortexReader.open(file, ReadRegistry.loadAll())) {
+            assertThat(readAllStrings(vf)).isEqualTo(expected);
+        }
+    }
+
+    private static boolean hasDictLayout(InspectorTree.Node node) {
+        if (node.layout().isDict()) {
+            return true;
+        }
+        for (InspectorTree.Node child : node.children()) {
+            if (hasDictLayout(child)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
     private static List<String> readAllStrings(VortexReader vf) {
         List<String> out = new ArrayList<>();
         try (var iter = vf.scan(ScanOptions.columns("desc"))) {

writer/src/main/java/io/github/dfa1/vortex/writer/VortexWriter.java

@@ -104,8 +104,18 @@ public final class VortexWriter implements Closeable {
     private static final int STAT_NULL_COUNT = 6;
 
     // Columns with global cardinality below this threshold are dict-encoded across all chunks.
-    // Kept low: global dict hurts high-cardinality F64 columns (ALP codes beat U16 dict codes).
+    // The cap is type-aware. Numeric stays low: a global dict hurts high-cardinality F64/I64
+    // columns (ALP/bitpacked codes beat U16 dict codes). Utf8 is raised far higher — text columns
+    // with thousands of repeated distinct values (street/place names) dictionary-compress well
+    // (#299), and the per-chunk short[] code buffer holds codes 0..32767 (up to 32768 distinct)
+    // with no wider buffer; codePTypeForSize already emits U16 codes above 256.
     static final int GLOBAL_DICT_MAX_CARDINALITY = 2_048;
+    static final int GLOBAL_DICT_MAX_CARDINALITY_UTF8 = 32_768;
+
+    // The global-dict cardinality cap for a column, by whether it is Utf8 (see the constants above).
+    private static int dictMaxCardinality(boolean utf8) {
+        return utf8 ? GLOBAL_DICT_MAX_CARDINALITY_UTF8 : GLOBAL_DICT_MAX_CARDINALITY;
+    }
 
     private static final List<EncodingEncoder> DEFAULT_CODECS = List.of(
             new AlpEncodingEncoder(), new PrimitiveEncodingEncoder(), new BoolEncodingEncoder(),
@@ -1297,11 +1307,12 @@ private boolean ingestDictChunk(DictColumnState state, Object data) {
         Object values = nullable ? ((NullableData) data).values() : data;
         boolean[] validity = nullable ? ((NullableData) data).validity() : null;
         int len = state.utf8 ? ((String[]) values).length : primitiveArrayLen(values, state.ptype);
+        int cap = dictMaxCardinality(state.utf8);
 
         // First pass: would this chunk's fresh distinct values push the map past the cap? Count them
         // without mutating so the whole chunk is either ingested or rejected atomically — a partial
         // ingest would corrupt the dictionary when the caller demotes on rejection.
-        var pendingNew = new HashSet<>(GLOBAL_DICT_MAX_CARDINALITY + 1);
+        var pendingNew = new HashSet<>(Math.min(cap, len) + 1);
         for (int i = 0; i < len; i++) {
             if (validity != null && !validity[i]) {
                 continue;
@@ -1314,7 +1325,7 @@ private boolean ingestDictChunk(DictColumnState state, Object data) {
                 continue;
             }
             if (!state.valueToCode.containsKey(v) && pendingNew.add(v)
-                    && state.valueToCode.size() + pendingNew.size() > GLOBAL_DICT_MAX_CARDINALITY) {
+                    && state.valueToCode.size() + pendingNew.size() > cap) {
                 return false;
             }
         }
@@ -1667,13 +1678,13 @@ static boolean isUtf8DictCandidate(String[] data, boolean[] validity) {
         if (data.length == 0) {
             return false;
         }
-        var seen = new java.util.HashSet<String>(GLOBAL_DICT_MAX_CARDINALITY + 1);
+        var seen = new java.util.HashSet<String>(Math.min(GLOBAL_DICT_MAX_CARDINALITY_UTF8, data.length) + 1);
         for (int i = 0; i < data.length; i++) {
             if ((validity != null && !validity[i]) || data[i] == null) {
                 continue;
             }
             seen.add(data[i]);
-            if (seen.size() > GLOBAL_DICT_MAX_CARDINALITY) {
+            if (seen.size() > GLOBAL_DICT_MAX_CARDINALITY_UTF8) {
                 return false;
             }
         }

writer/src/test/java/io/github/dfa1/vortex/writer/VortexWriterDictDecisionTest.java

@@ -8,6 +8,7 @@
 import java.util.stream.Stream;
 
 import static io.github.dfa1.vortex.writer.VortexWriter.GLOBAL_DICT_MAX_CARDINALITY;
+import static io.github.dfa1.vortex.writer.VortexWriter.GLOBAL_DICT_MAX_CARDINALITY_UTF8;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.junit.jupiter.params.provider.Arguments.arguments;
 
@@ -96,8 +97,12 @@ static Stream<Arguments> utf8DictCandidateCases() {
                 arguments("empty", new String[0], false),
                 arguments("ratio exactly 50%", new String[]{"a", "b", "a", "b"}, false),
                 arguments("ratio under 50%", new String[]{"a", "b", "a", "b", "a"}, true),
-                arguments("cardinality at MAX", distinctStrings(GLOBAL_DICT_MAX_CARDINALITY), true),
-                arguments("cardinality over MAX", distinctStrings(GLOBAL_DICT_MAX_CARDINALITY + 1), false));
+                // Utf8 uses the raised type-aware cap (#299), not the numeric 2048.
+                arguments("Utf8 admitted above numeric cap",
+                        distinctStrings(GLOBAL_DICT_MAX_CARDINALITY + 1), true),
+                arguments("cardinality at Utf8 MAX", distinctStrings(GLOBAL_DICT_MAX_CARDINALITY_UTF8), true),
+                arguments("cardinality over Utf8 MAX",
+                        distinctStrings(GLOBAL_DICT_MAX_CARDINALITY_UTF8 + 1), false));
     }
 
     @ParameterizedTest(name = "{0}")