From 52f2e70375363c8f02e1693cb96f63a33c2b2fa9 Mon Sep 17 00:00:00 2001 From: Davide Angelocola Date: Mon, 6 Jul 2026 07:58:29 +0200 Subject: [PATCH] docs: update chunk examples to ColumnName keys Follow-up to the writeChunk(Map) retype (#201) and the Chunk.put(ColumnName, ...) builder (#200): doc snippets still showed String keys and would not compile. DocsConsistencyTest is blind to them (the .put("x", ...) / writeChunk(Map<...>) forms have no dotted receiver its regex can match), so this was caught in review, not CI. - reference.md: writeChunk(Map) -> Map - README / tutorial / compatibility: .put("x", ...) -> .put(ColumnName.of("x"), ...) - tutorial: add the ColumnName import - JdbcImporter.toChunkMap: drop a pointless ColumnName -> String -> ColumnName round-trip (List names = schema.fieldNames()) Co-Authored-By: Claude Opus 4.8 --- README.md | 8 ++++---- docs/compatibility.md | 2 +- docs/reference.md | 2 +- docs/tutorial.md | 9 +++++---- .../java/io/github/dfa1/vortex/jdbc/JdbcImporter.java | 6 +++--- 5 files changed, 14 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 625dcc08..5c85e715 100644 --- a/README.md +++ b/README.md @@ -115,10 +115,10 @@ try (var ch = FileChannel.open(Path.of("data/example.vortex"), StandardOpenOption.CREATE, StandardOpenOption.WRITE); var writer = VortexWriter.create(ch, schema, WriteOptions.cascading(3))) { writer.writeChunk(c -> c - .put("timestamp", new long[] {1_700_000_000_000L, 1_700_000_001_000L}) - .put("symbol", new String[] {"AAPL", "AAPL"}) - .put("price", new double[] {189.95, 190.10}) - .put("volume", new Long[] {100L, null})); // null in nullable col + .put(ColumnName.of("timestamp"), new long[] {1_700_000_000_000L, 1_700_000_001_000L}) + .put(ColumnName.of("symbol"), new String[] {"AAPL", "AAPL"}) + .put(ColumnName.of("price"), new double[] {189.95, 190.10}) + .put(ColumnName.of("volume"), new Long[] {100L, null})); // null in nullable col } ``` diff --git a/docs/compatibility.md b/docs/compatibility.md index 7f05e861..ee13e7c1 100644 --- a/docs/compatibility.md +++ b/docs/compatibility.md @@ -177,7 +177,7 @@ End-to-end round-trip — write a `List`, read it back: var schema = DType.structBuilder() .field("birthdays", DateExtensionDecoder.INSTANCE.dtype(false)) .build(); -writer.writeChunk(c -> c.put("birthdays", dates)); // Collection auto-routed +writer.writeChunk(c -> c.put(ColumnName.of("birthdays"), dates)); // Collection auto-routed try (var iter = reader.scan(ScanOptions.all()); Chunk chunk = iter.next()) { diff --git a/docs/reference.md b/docs/reference.md index 06c732b0..00dcbd49 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -98,7 +98,7 @@ Writes a Vortex file. Implements `Closeable`. The file is complete and readable | `static create(WritableByteChannel, DType.Struct, WriteOptions)` | Default codec set | | `static create(WritableByteChannel, DType.Struct, WriteOptions, List)` | Custom codec set | | `writeChunk(Consumer)` | One batch of rows; typed builder validates column names + array types at each `.put`; missing columns throw `IllegalStateException` when the lambda returns. Preferred when columns are known at compile time. | -| `writeChunk(Map)` | One batch of rows by map. Validates that every schema column is present and that all columns share the same row count. Use when the column set is built dynamically (Parquet/JDBC importers, generic exporters). | +| `writeChunk(Map)` | One batch of rows by map. Validates that every schema column is present and that all columns share the same row count. Use when the column set is built dynamically (Parquet/JDBC importers, generic exporters). | | `close()` | Finalizes file (footer, postscript, trailer) | ### `Chunk` (`io.github.dfa1.vortex.writer.Chunk`) diff --git a/docs/tutorial.md b/docs/tutorial.md index e3bb62fa..923d9fca 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -46,6 +46,7 @@ A Vortex file is a typed struct — every column has a declared type before any ```java import io.github.dfa1.vortex.core.model.DType; +import io.github.dfa1.vortex.core.model.ColumnName; DType.Struct schema = DType.structBuilder() .field("timestamp", DType.I64) // unix epoch millis @@ -77,10 +78,10 @@ try (FileChannel ch = FileChannel.open(outPath, CREATE, WRITE, TRUNCATE_EXISTING VortexWriter writer = VortexWriter.create(ch, schema, WriteOptions.defaults())) { writer.writeChunk(c -> c - .put("timestamp", new long[] {1_700_000_000_000L, 1_700_000_001_000L, 1_700_000_002_000L}) - .put("symbol", new String[] {"AAPL", "AAPL", "MSFT"}) - .put("price", new double[] {189.95, 190.10, 374.20}) - .put("volume", new Long[] {100L, null, 175L})); // boxed → nullable column + .put(ColumnName.of("timestamp"), new long[] {1_700_000_000_000L, 1_700_000_001_000L, 1_700_000_002_000L}) + .put(ColumnName.of("symbol"), new String[] {"AAPL", "AAPL", "MSFT"}) + .put(ColumnName.of("price"), new double[] {189.95, 190.10, 374.20}) + .put(ColumnName.of("volume"), new Long[] {100L, null, 175L})); // boxed → nullable column } ``` diff --git a/jdbc/src/main/java/io/github/dfa1/vortex/jdbc/JdbcImporter.java b/jdbc/src/main/java/io/github/dfa1/vortex/jdbc/JdbcImporter.java index f1eb5d8b..11ab30eb 100644 --- a/jdbc/src/main/java/io/github/dfa1/vortex/jdbc/JdbcImporter.java +++ b/jdbc/src/main/java/io/github/dfa1/vortex/jdbc/JdbcImporter.java @@ -271,7 +271,7 @@ private static UUID toUuid(Object raw) { private static Map toChunkMap(DType.Struct schema, Object[] buffers, boolean[][] validity, boolean[] anyNull, int rows) { - List names = schema.fieldNames().stream().map(ColumnName::value).toList(); + List names = schema.fieldNames(); Map chunk = new LinkedHashMap<>(); for (int c = 0; c < names.size(); c++) { Object trimmed = trimBuffer(buffers[c], rows); @@ -279,10 +279,10 @@ private static Map toChunkMap(DType.Struct schema, Object[] boolean[] trimmedValidity = rows == validity[c].length ? validity[c] : Arrays.copyOf(validity[c], rows); - chunk.put(ColumnName.of(names.get(c)), + chunk.put(names.get(c), new io.github.dfa1.vortex.writer.encode.NullableData(trimmed, trimmedValidity)); } else { - chunk.put(ColumnName.of(names.get(c)), trimmed); + chunk.put(names.get(c), trimmed); } } return chunk;