Skip to content

refactor: Narrow message metadata API - #937

Merged
paleolimbot merged 2 commits into
apache:mainfrom
rustyconover:refactor/ipc-message-metadata-api
Sep 10, 2026
Merged

paleolimbot merged 2 commits into
apache:mainfrom
rustyconover:refactor/ipc-message-metadata-api

Conversation

@rustyconover

Copy link
Copy Markdown
Contributor

Follow-up to #924.

This removes ArrowIpcDecoderGetMessageMetadataValue() before the API ships in a release. Callers that need one key can use ArrowMetadataGetValue() with the packed metadata returned by ArrowIpcDecoderGetMessageMetadata(); callers that need zero-copy iteration can continue using ArrowIpcDecoderVisitMessageMetadata().

It also scopes the visitor callback type as ArrowIpcMessageMetadataVisitFunction and replaces the hand-generated keyless KeyValue FlatBuffer test fixture with a flatcc-built message.

Tests:

  • IPC-enabled CMake build
  • ctest: 365 tests passed (16 codec-dependent tests skipped)
  • git diff --check
  • clang-format on changed lines

…latcc

Address review feedback on the Message.custom_metadata support:

- Remove ArrowIpcDecoderGetMessageMetadataValue(). Get and Visit already
  cover the same ground, and every public function is permanent surface;
  callers who want one key use ArrowMetadataGetValue() on the buffer from
  ArrowIpcDecoderGetMessageMetadata(). This also removes the
  _NANOARROW_IPC_VISIT_STOP sentinel, which was not an errno and existed
  only to unwind that lookup.

- Rename ArrowIpcMetadataVisitFunction to
  ArrowIpcMessageMetadataVisitFunction, scoping the name to the one
  public entry point that accepts it.

- Build the keyless-KeyValue message in NanoarrowIpcDecodeMetadataWithoutKey
  with flatcc rather than embedding a hand-generated flatbuffer blob, so
  the test documents itself and survives a flatcc regeneration. Verified
  that it still segfaults when the strlen() it guards against is restored.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KYFwnKHTw7dhiJeDxy7APV
@codecov-commenter

codecov-commenter commented Sep 9, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 79.47%. Comparing base (6657945) to head (cd327f5).

Additional details and impacted files
@@            Coverage Diff             @@
##             main     #937      +/-   ##
==========================================
- Coverage   79.49%   79.47%   -0.03%     
==========================================
  Files         106      106              
  Lines       16564    16547      -17     
  Branches     1986     1982       -4     
==========================================
- Hits        13167    13150      -17     
  Misses       2164     2164              
  Partials     1233     1233              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@rustyconover

Copy link
Copy Markdown
Contributor Author

Fixed the bundled-build failure in cd327f5. The new test included the generated FlatBuffers header through the source include root, which is intentionally absent when NANOARROW_BUNDLE=ON. The header now uses a same-directory include, preserving the bundled include-path check while keeping the flatcc-built fixture. Reproduced locally with NANOARROW_BUNDLE=ON and NANOARROW_IPC=ON: build succeeded and all 365 tests passed (16 codec-dependent tests skipped).

@paleolimbot paleolimbot left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't particularly mind any of this, but I also didn't mind the hard-coded fixture or the special-cased ArrowIpcDecoderGetMessageMetadataValue() (I don't spend much time with message-level metadata but presumably this would be a reasonably common pattern, like fetching a geo key or something?). Is there a specific motivation for removing it?

@rustyconover

Copy link
Copy Markdown
Contributor Author

It was a commit I had in my tree and I think I forgot to push it as a cleanup.

@paleolimbot paleolimbot left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Works for me! We can always add the zero copy single key accessor later.

@paleolimbot paleolimbot changed the title refactor(ipc): Narrow message metadata API refactor: Narrow message metadata API Sep 10, 2026
@paleolimbot
paleolimbot merged commit e675fc7 into apache:main Sep 10, 2026
43 checks passed
@rustyconover
rustyconover deleted the refactor/ipc-message-metadata-api branch October 20, 2026 03:25
paleolimbot pushed a commit that referenced this pull request Oct 20, 2026
`ArrowIpcEncoderSetMessageMetadata()` (#924, narrowed in #937) attaches
`Message::custom_metadata` to the next message an encoder encodes. An
`ArrowIpcWriter` keeps its encoder private, though, so a caller using
the writer has no way to attach metadata to the RecordBatch messages it
writes. The only option is to drop down to the encoder and redo the
writer's framing, footer bookkeeping and dictionary handling by hand.

This PR adds `ArrowIpcWriterSetMessageMetadata(writer, metadata,
error)`. The writer holds the metadata and attaches it to the next
RecordBatch message written by `ArrowIpcWriterWriteArrayView()` or
`ArrowIpcWriterWriteArrayStream()`. The metadata applies to that one
message. Passing `NULL` clears metadata that has been set but not yet
written. Like the encoder function, it takes ownership of the buffer.

The metadata is held by the writer rather than set on the encoder right
away. Setting it on the encoder would attach it to whichever message is
encoded next, and that can be a DictionaryBatch written ahead of the
batch. This happens both with an explicit
`ArrowIpcWriterWriteDictionaryBatch()` call and inside
`ArrowIpcWriterWriteArrayStream()`. RecordBatch-level metadata belongs
on the RecordBatch, so the writer passes it to the encoder just before
encoding that batch.

Things worth a look in review:

- With `WriteArrayStream()` the metadata lands on the first RecordBatch
only. Per-batch metadata over a stream would need a callback or a
per-array side channel, which seemed out of scope. The batch-at-a-time
pattern is `SetMessageMetadata()` + `WriteArrayView()`.
- #928 makes encoder-level metadata apply to DictionaryBatch messages
too. The two compose: this PR never sets encoder metadata until right
before the RecordBatch is encoded. They touch neighbouring code in
`writer.c`, so whichever lands second will need a small rebase. I can do
that.

Motivation: I'm moving the IPC layer of a DuckDB extension from Arrow
C++ to nanoarrow. Its RPC protocol carries per-batch state in
RecordBatch `custom_metadata` (what Arrow C++ writes for
`RecordBatchWriter::WriteRecordBatch(batch, custom_metadata)`), and this
was the one thing the writer couldn't express.

Tests:
- `MessageMetadataAttachesToNextRecordBatch` sets metadata, writes a
DictionaryBatch and then a RecordBatch, and checks that only the
RecordBatch carries it. It also checks that the following batch doesn't
inherit the metadata, and that set-then-cleared metadata is never
written.
- `MessageMetadataWithArrayStream` covers `WriteArrayStream()` writing
its own dictionaries.

ctest passes locally (macOS arm64, Debug, ZSTD/LZ4, 390 tests). The IPC
writer, encoder and files tests are clean under ASan/UBSan.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
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.

3 participants