Skip to content

Parse one-dimensional arrays straight into a typed vector - #56

Merged
quinnj-bot[bot] merged 3 commits into
mainfrom
claude/array-parse
Nov 19, 2026
Merged

quinnj-bot[bot] merged 3 commits into
mainfrom
claude/array-parse

Conversation

@quinnj-bot

@quinnj-bot quinnj-bot Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Why

Array columns were the slowest columns to read. Reading a million five-element int4[] values into a Vector{Int32} field took 808 ms and about 2,800 client cycles per row, against 318-602 ms for psycopg 3 and 281 ms for the raw COPY transfer of the same rows. The parser copied each element through a growable UInt8[] buffer (two or three allocations per element), boxed every parsed value into a Vector{Any}, and then copied the values into the typed vector. An allocation profile counts 36 allocations per row, about 30 of them in the array parse.

What changed

  • parse_array first tries parse_flat_array, which reads a one-dimensional literal with no NULL, escape or nested array straight into a Vector{T}. Each element becomes one String and goes through the same parse_scalar as before.
  • Before it reads any element, needs_general_parser sends a literal with a nested array ({{), a backslash, or the bytes NULL straight to the general parser, using memchr scans. Those literals are parsed once, so they cost what they cost on main, with the same allocations. A quoted "NULL" or a word that contains NULL also goes to the general parser, which reads it the same way.
  • The fast path still gives up at a later nested array or a value that is not a T, and the general parser then reads the whole literal from the start. The server does not write such literals. Element splitting (whitespace, quotes, delimiters) is the general parser's, so results, result types and errors are unchanged.

Untyped results (Tables.columntable, row iteration) and typed Vector{T} fields both use parse_array, as do the date[], timestamp[], uuid[] and numeric[] decoders that split elements as String first.

Measurements

Reading 500,000 int4[5] rows into a Vector{Int32} field takes 0.46x the CPU time of main (152 vs 337 ms, median of 5 rounds), with 13 allocations per row instead of 35. Arrays the fast path does not take (NULL elements, escapes, 2-D) cost what they cost on main, with the same allocations.

Method: PostgreSQL 17.12 in Docker on one Mac, Julia 1.12.6 with one thread. Each process runs one case: it warms up on 2,000 rows, then times 3 full reads after a full GC and keeps the fastest. Five rounds alternate main, this branch, and this branch's previous head (1120060 merged with main) in rotating order. The machine was shared (1-minute load average 21 to 35), so the table gives ratios to main within each round, median [range], for the reading thread's CPU time and for wall time minus GC time. CPU time includes GC, which lands in some reads and not others (the 2-D case swings between about 320 and 450 ms on every side).

Case (rows) CPU, branch / main wall minus GC, branch / main same, previous head / main allocations, main -> branch
int4[5], typed Vector{Int32} (500k) 0.46 [0.45-0.48] 0.53 [0.52-0.56] 0.51 17.5M -> 6.5M
int4[5], untyped (500k) 0.50 [0.38-0.51] 0.54 [0.54-0.59] 0.55 18.5M -> 7.5M
text[4] without escapes, typed Vector{String} (300k) 0.34 [0.33-0.57] 0.71 [0.70-0.78] 0.72 8.1M -> 3.6M
int4[5] with NULL second, untyped (500k) 1.02 [0.97-1.06] 1.01 [0.98-1.04] 1.08 18.0M -> 18.0M
int4[5] with NULL last, untyped (500k) 0.99 [0.97-1.05] 1.01 [1.00-1.06] 1.22 18.0M -> 18.0M
text[4] with \" and \\ escapes, untyped (300k) 1.03 [0.97-1.06] 1.02 [0.94-1.26] 1.09 8.7M -> 8.7M
2-D int4[2][3], untyped (300k) 1.02 [0.96-1.38] 1.00 [0.99-1.01] 1.02 14.1M -> 14.1M
int4 scalar, untyped (1M), control 0.99 [0.97-1.66] 1.03 [0.94-1.05] 0.98 6.0M -> 6.0M

On the previous head, the NULL, escape and 2-D rows allocated 2M, 4M, 0.9M and 0.3M more than main, because the fast path parsed elements before it found the NULL, escape or nested array and then threw them away.

Against the previous head, the target cases are within noise: typed int4[5] CPU 1.02 [0.93-1.05], untyped 1.05 [0.97-1.10], text[4] 0.98 [0.98-1.00]. A single-process microbenchmark of parse_array (minimum of 7 batches of 100,000 calls, 3 fresh processes per side) puts the up-front check at about 3 ns per literal: int4[5] takes 158 ns, against 155 ns on the previous head and 396 ns on main. A literal with a NULL or an escape now costs main's time within 3%: 395 vs 390 ns with NULL second, 402 vs 396 ns with NULL last, 326 vs 319 ns escaped. The previous head took 440, 536 and 371 ns.

Verification

  • Differential check: 150,000 generated and random array literals across 14 element types (String, Int16/32/64, Float32/64, Bool, Date, Time, DateTime, UUID, Char, Timestamp, decimal), with NULLs, words containing NULL, quoting, escapes, nested arrays, dimension prefixes, truncation and trailing junk: 2.1M cases. This branch and the parser on main give the same value and type, or the same exception and message, for every case; 316,586 took the fast path. The same harness reports 3,059 mismatches in 70,000 cases against a copy of main's parser with NULL detection broken, so it can fail.
  • New tests pin the boundary: typed results for plain arrays, the general parser's results for NULLs, escapes, nested arrays and words containing NULL, and that a NULL, escaped or nested literal allocates no more than the general parser alone. On the previous head that last test fails (30 vs 22, 14 vs 11 and 24 vs 23 allocations).
  • Pkg.test() passes on Julia 1.12.6 (9,990 tests) and 1.10.11 (9,961), including the JuliaC --trim build of test/postgres_trim_queries.jl on 1.12 (0 package verifier errors, the 30 known stdlib ones).
  • Self-review: the fast path reads only within codeunits(str); unsafe_string copies bytes i:j-1 with j <= n + 1, under GC.@preserve str. needs_general_parser reads code[open + 1] only when open < length(code) and code[i + 1:i + 3] only when i + 3 <= length(code). With no backslash in the literal, a quoted element ends at the next quote, as in parse_quoted, and an unterminated one ends at the end of the text. With no NULL bytes, parse_scalar never returns missing, so the fast path keeps only the value isa T check. Text after the closing brace is ignored, as before.

🤖 Generated with Claude Code

The array parser copied each element through a growable byte buffer and
boxed every value into a Vector{Any} before narrowing it to the element
type. One-dimensional arrays without NULLs, escapes or nested arrays,
the common case, now go straight into a Vector{T}: each element is one
String and the same scalar parser as before. Any other literal still
goes through the general parser, so results are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@quinnj-bot
quinnj-bot Bot marked this pull request as ready for review November 19, 2026 20:45
quinnj and others added 2 commits November 19, 2026 14:55
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… front

The flat array reader parsed elements until it met a NULL, a backslash or
a nested array, then threw that work away and the general parser started
over. Literals with a NULL or an escape allocated more than on main and
ran up to 1.2x slower.

needs_general_parser now decides before any element is read, with a
check for `{{` and memchr scans for a backslash and the bytes NULL. Those
literals are parsed once and allocate exactly what they do on main. The
flat path's own backslash and NULL checks are gone, since neither can
occur once the scan passes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@quinnj-bot
quinnj-bot Bot merged commit ff5ee6f into main Nov 19, 2026
16 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant