feat: add lance-c crate — C/C++ bindings for Lance (Phase 1)#6254
Open
jja725 wants to merge 3 commits intolance-format:mainfrom
Open
feat: add lance-c crate — C/C++ bindings for Lance (Phase 1)#6254jja725 wants to merge 3 commits intolance-format:mainfrom
jja725 wants to merge 3 commits intolance-format:mainfrom
Conversation
Implements Phase 1 (Core Read Path MVP) of the Lance C/C++ library RFC. This enables native integration with C++ query engines (Velox, DuckDB) and any language with C FFI capabilities. C API surface: - Dataset: open/close/version/count_rows/latest_version/schema/take - Scanner: builder pattern with column projection, SQL filters, limit/offset - Sync scan: ArrowArrayStream export, blocking batch iteration - Async scan: callback-based (for Presto/Trino), poll+waker (for Velox/folly) - Arrow C Data Interface for all data exchange (zero-copy) - Thread-local error handling (proven pattern from lance-duckdb) Includes: - lance.h: C header with full API - lance.hpp: header-only C++ RAII wrappers (Dataset, Scanner, Batch) - 13 integration tests covering all API paths Refs: lance-format#6035
Covers: schema field types, latest_version, batch_size control, combined filter+projection+limit, take with projection, multiple scanners on same dataset, open specific version, invalid filter/column errors, comprehensive NULL safety, error message lifecycle, large dataset scan (10k rows), equality filter verification, limit-only, offset-only, take empty indices, take value verification, async scan with filter, poll-based iteration, scan data values, reopen dataset, large dataset schema. Total: 35 tests (34 active + 1 ignored poll test).
Adds real C and C++ programs that compile against lance.h/lance.hpp and run end-to-end with a Lance dataset: - tests/cpp/test_c_api.c: C11 program testing open, scan, limit, errors - tests/cpp/test_cpp_api.cpp: C++17 program testing RAII wrappers, fluent scanner, take, move semantics, exception handling Also adds tests using checked-in historical test datasets: - test_historical_dataset_v0_27_1: reads test_data/v0.27.1/pq_in_schema - test_historical_dataset_open_specific_version: opens version 1 and 2 Run C/C++ tests with: cargo test -p lance-c -- --ignored Total: 39 tests (36 active + 3 ignored).
Xuanwo
reviewed
Mar 23, 2026
Author
|
Hi @Xuanwo , that sounds great, do you mind creating the repo? I can migrate the code there |
Collaborator
Sure! Will create one tomorrow |
Collaborator
|
Hi @jja725, I have created https://github.com/lance-format/lance-c, let's rock! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements Phase 1 (Core Read Path MVP) of the Lance C/C++ library RFC. This enables native integration with C++ query engines (Velox, DuckDB) and any language with C FFI capabilities.
C API surface
open/close/version/count_rows/latest_version/schema/take(all sync/blocking)ArrowArrayStreamexport, blocking batch iteration (lance_scanner_next)lance_scanner_scan_async) for Presto/Trino-style engineslance_scanner_poll_next) for cooperative async runtimes (Velox/folly)Remaining phases
Test plan
cargo check -p lance-ccompilescargo test -p lance-c— 13 tests pass (open/close, scan, filter, projection, limit/offset, take, error handling, async scan, ArrowArrayStream export)cargo clippy -p lance-c --tests -- -D warnings— cleancargo fmt -p lance-c -- --check— cleanRefs: #6035