Skip to content

Commit 242decf

Browse files
authored
feat(format): support Vortex file format (#376)
1 parent ff4194e commit 242decf

64 files changed

Lines changed: 4834 additions & 15 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/.rat-excludes‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ iwyu_tool\.py
1212
arrow\.diff
1313
jieba\.diff
1414
orc\.diff
15+
vortex\.diff
1516
licenses/*
1617
.codespell_ignore
1718
.gitignore

‎.github/workflows/build_and_test.yaml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,9 @@ jobs:
116116
run: |
117117
sudo apt-get update
118118
sudo apt-get install -y gdb libcurl4-openssl-dev libssl-dev
119+
- name: Install flatc and libclang (Vortex)
120+
shell: bash
121+
run: ci/scripts/setup_flatc.sh
119122
- name: Build Paimon
120123
shell: bash
121124
env:

‎.github/workflows/gcc8_test.yaml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,9 @@ jobs:
6767
uses: ./.github/actions/setup-ccache
6868
with:
6969
cache-key-prefix: ccache-gcc8-test
70+
- name: Install flatc and libclang (Vortex)
71+
shell: bash
72+
run: ci/scripts/setup_flatc.sh
7073
- name: Build Paimon
7174
shell: bash
7275
env:

‎.github/workflows/release_candidate.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -135,6 +135,10 @@ jobs:
135135
shell: bash
136136
run: ci/scripts/setup_rust.sh
137137

138+
- name: Install flatc and libclang (Vortex)
139+
shell: bash
140+
run: ci/scripts/setup_flatc.sh
141+
138142
- name: Install HTTP and TLS development dependencies
139143
run: |
140144
sudo apt-get update

‎CMakeLists.txt‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,7 @@ option(PAIMON_ENABLE_AVRO "Whether to enable avro file format" ON)
6262
option(PAIMON_ENABLE_ORC "Whether to enable orc file format" ON)
6363
option(PAIMON_ENABLE_MOSAIC "Whether to enable mosaic file format (Rust FFI)" OFF)
6464
option(PAIMON_ENABLE_LANCE "Whether to enable lance file format (Rust FFI)" OFF)
65+
option(PAIMON_ENABLE_VORTEX "Whether to enable vortex file format (Rust FFI)" OFF)
6566
option(PAIMON_ENABLE_JINDO "Whether to enable jindo file system" OFF)
6667
option(PAIMON_ENABLE_OSS "Whether to enable OSS SDK v2 file system" OFF)
6768
option(PAIMON_ENABLE_S3 "Whether to enable S3 file system" OFF)
@@ -97,6 +98,9 @@ endif()
9798
if(PAIMON_ENABLE_LANCE)
9899
add_definitions(-DPAIMON_ENABLE_LANCE)
99100
endif()
101+
if(PAIMON_ENABLE_VORTEX)
102+
add_definitions(-DPAIMON_ENABLE_VORTEX)
103+
endif()
100104
if(PAIMON_ENABLE_JINDO)
101105
add_definitions(-DPAIMON_ENABLE_JINDO)
102106
endif()
@@ -412,6 +416,10 @@ if(PAIMON_BUILD_TESTS OR PAIMON_BUILD_BENCHMARKS)
412416
paimon_link_libraries_whole_archive(PAIMON_LANCE_FILE_FORMAT_STATIC_LINK_LIBS
413417
paimon_lance_file_format_static)
414418
endif()
419+
if(PAIMON_ENABLE_VORTEX)
420+
paimon_link_libraries_whole_archive(PAIMON_VORTEX_FILE_FORMAT_STATIC_LINK_LIBS
421+
paimon_vortex_file_format_static)
422+
endif()
415423
416424
if(PAIMON_ENABLE_ORC)
417425
paimon_link_libraries_whole_archive(PAIMON_ORC_FILE_FORMAT_STATIC_LINK_LIBS
@@ -479,6 +487,13 @@ if(PAIMON_BUILD_TESTS)
479487
paimon_link_libraries_whole_archive(PAIMON_LANCE_FILE_FORMAT_STATIC_LINK_LIBS
480488
paimon_lance_file_format_static)
481489
endif()
490+
if(PAIMON_ENABLE_VORTEX)
491+
paimon_link_libraries_no_as_needed(TEST_PLUGIN_LINK_LIBS
492+
paimon_vortex_file_format_shared)
493+
list(APPEND TEST_STATIC_LINK_LIBS ${TEST_PLUGIN_LINK_LIBS})
494+
paimon_link_libraries_whole_archive(PAIMON_VORTEX_FILE_FORMAT_STATIC_LINK_LIBS
495+
paimon_vortex_file_format_static)
496+
endif()
482497
483498
if(PAIMON_ENABLE_ORC)
484499
paimon_link_libraries_no_as_needed(TEST_PLUGIN_LINK_LIBS
@@ -582,6 +597,9 @@ endif()
582597
if(PAIMON_ENABLE_LANCE)
583598
add_subdirectory(src/paimon/format/lance)
584599
endif()
600+
if(PAIMON_ENABLE_VORTEX)
601+
add_subdirectory(src/paimon/format/vortex)
602+
endif()
585603
if(PAIMON_ENABLE_LUMINA)
586604
add_subdirectory(src/paimon/indexer/lumina)
587605
endif()

‎build_support/lsan-suppressions.txt‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,3 +17,8 @@
1717

1818
# False positive from atexit() registration in libc
1919
leak:*__new_exitfn*
20+
21+
# Vortex links an un-instrumented Rust staticlib whose runtime keeps allocations alive at process
22+
# exit; these are not paimon leaks. Rust crate frames are prefixed vortex_<crate>, which does not
23+
# match paimon::vortex:: C++ frames, so genuine paimon leaks are still reported.
24+
leak:vortex_

‎build_support/tsan-suppressions.txt‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,3 +18,26 @@
1818
# Prebuilt shared libraries are not TSAN-instrumented. Suppress reports from the whole library.
1919
race:liblumina.so
2020
race:libjindosdk_c.so.6
21+
22+
# Vortex links an un-instrumented Rust staticlib. The handoff between its blocking-pool threads
23+
# (which invoke the paimon read/write callbacks) and the calling thread happens inside Rust, so
24+
# TSAN cannot see the happens-before edge and reports false data races on the shared buffers.
25+
# These patterns match only the Rust frames, so races confined to paimon C++ are still reported.
26+
race:vortex_buffer
27+
race:vortex_io
28+
race:CallbackReadAt
29+
# Vortex also deserializes its footer/dtype and drives segment reads from internal runtime threads;
30+
# that concurrency lives inside the same un-instrumented Rust staticlib (dtype flatbuffers decode,
31+
# shared-future polling, segment cache and mask handling), so TSAN reports false races whose only
32+
# non-paimon frames are these Rust modules. Patterns match Rust frames only.
33+
race:vortex_array
34+
race:vortex_error
35+
race:vortex_file
36+
race:vortex_layout
37+
race:vortex_mask
38+
# The Arrow C-bridge hands buffer ownership to/from the Rust side (arrow_buffer Allocation and
39+
# bytes::Bytes), and Vortex formats its error messages on its runtime threads; those
40+
# synchronizations also live in the un-instrumented Rust staticlib, so suppress those Rust frames.
41+
race:arrow_buffer
42+
race:bytes::bytes::Bytes
43+
race:alloc::string::String

‎ci/scripts/build_paimon.sh‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -160,6 +160,7 @@ CMAKE_ARGS=(
160160
"-DPAIMON_BUILD_TESTS=ON"
161161
"-DPAIMON_ENABLE_MOSAIC=ON"
162162
"-DPAIMON_ENABLE_LANCE=${ENABLE_LANCE}"
163+
"-DPAIMON_ENABLE_VORTEX=ON"
163164
"-DPAIMON_ENABLE_JINDO=ON"
164165
"-DPAIMON_ENABLE_OSS=ON"
165166
"-DPAIMON_ENABLE_S3=ON"

‎ci/scripts/setup_flatc.sh‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
#!/usr/bin/env bash
2+
# Licensed to the Apache Software Foundation (ASF) under one
3+
# or more contributor license agreements. See the NOTICE file
4+
# distributed with this work for additional information
5+
# regarding copyright ownership. The ASF licenses this file
6+
# to you under the Apache License, Version 2.0 (the
7+
# "License"); you may not use this file except in compliance
8+
# with the License. You may obtain a copy of the License at
9+
#
10+
# http://www.apache.org/licenses/LICENSE-2.0
11+
#
12+
# Unless required by applicable law or agreed to in writing, software
13+
# distributed under the License is distributed on an "AS IS" BASIS,
14+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
# See the License for the specific language governing permissions and
16+
# limitations under the License.
17+
#
18+
# Build and install flatc (the FlatBuffers compiler) at the version Vortex requires, and make sure
19+
# libclang is present.
20+
#
21+
# Vortex compiles its FlatBuffers schemas (.fbs) into Rust at build time, and
22+
# cmake_modules/ThirdpartyToolchain.cmake requires a flatc whose version matches Vortex's
23+
# flatbuffers crate (find_program(... flatc REQUIRED)). Distribution packages are too old, so the
24+
# pinned version is built from source. Separately, Vortex's native dependencies run bindgen in
25+
# their build scripts, which needs libclang at build time; some CI images do not ship it.
26+
# flatc and libclang are build-time tools only; neither is needed at runtime.
27+
#
28+
# The dev container (see .devcontainer/) already has these preinstalled; this script is for the
29+
# GitHub Actions runners and is called before ci/scripts/build_paimon.sh.
30+
#
31+
# Idempotent: a no-op when a matching flatc is already on PATH and libclang is already present.
32+
33+
set -eux
34+
35+
# Must match the flatbuffers crate version pinned by Vortex (see its Cargo.lock).
36+
FLATBUFFERS_VERSION=${FLATBUFFERS_VERSION:-25.12.19}
37+
FLATC_INSTALL_DIR=${FLATC_INSTALL_DIR:-"${HOME}/.local/bin"}
38+
39+
# Vortex's native dependencies invoke bindgen in their build scripts, which loads libclang at
40+
# build time. Images that only carry GCC (e.g. the gcc8 test container) may lack it.
41+
if ! ldconfig -p 2>/dev/null | grep -q 'libclang'; then
42+
if [[ "$(id -u)" -ne 0 ]] && command -v sudo >/dev/null 2>&1; then
43+
apt_prefix="sudo"
44+
else
45+
apt_prefix=""
46+
fi
47+
${apt_prefix} apt-get update -y
48+
${apt_prefix} apt-get install -y libclang-dev
49+
fi
50+
51+
# Skip when a matching flatc is already available.
52+
if command -v flatc >/dev/null 2>&1 &&
53+
[[ "$(flatc --version 2>/dev/null | awk '{print $NF}')" == "${FLATBUFFERS_VERSION}" ]]; then
54+
flatc --version
55+
exit 0
56+
fi
57+
58+
workdir="$(mktemp -d)"
59+
trap 'rm -rf "${workdir}"' EXIT
60+
61+
git clone --depth 1 --branch "v${FLATBUFFERS_VERSION}" \
62+
https://github.com/google/flatbuffers.git "${workdir}/flatbuffers"
63+
cmake -S "${workdir}/flatbuffers" -B "${workdir}/build" \
64+
-DCMAKE_BUILD_TYPE=Release \
65+
-DFLATBUFFERS_BUILD_TESTS=OFF
66+
cmake --build "${workdir}/build" --target flatc -j "$(nproc)"
67+
68+
mkdir -p "${FLATC_INSTALL_DIR}"
69+
install -m 0755 "${workdir}/build/flatc" "${FLATC_INSTALL_DIR}/flatc"
70+
71+
# Make flatc discoverable by later steps: on PATH for find_program, and via FLATC for build_vortex.
72+
export PATH="${FLATC_INSTALL_DIR}:${PATH}"
73+
echo "${FLATC_INSTALL_DIR}" >>"${GITHUB_PATH:-/dev/null}" || true
74+
echo "FLATC=${FLATC_INSTALL_DIR}/flatc" >>"${GITHUB_ENV:-/dev/null}" || true
75+
76+
"${FLATC_INSTALL_DIR}/flatc" --version

‎ci/scripts/setup_rust.sh‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,8 @@
1515
# See the License for the specific language governing permissions and
1616
# limitations under the License.
1717
#
18-
# Install the Rust toolchain used by the Lance, Mosaic, and full-text index FFI builds, plus
19-
# cbindgen required by Lance.
18+
# Install the Rust toolchain used by the Lance, Mosaic, Vortex and full-text index FFI builds,
19+
# plus cbindgen required by Lance.
2020
#
2121
# The dev container (see .devcontainer/) already has these preinstalled;
2222
# this script is for the GitHub Actions runners and is called before ci/scripts/build_paimon.sh.
@@ -76,6 +76,11 @@ if ! command -v protoc >/dev/null 2>&1 || \
7676
echo "${protoc_home}/bin" >> "${GITHUB_PATH:-/dev/null}" || true
7777
fi
7878

79+
# Vortex's FFI build pins rust-version >= 1.95 and is invoked with RUSTUP_TOOLCHAIN=stable (see
80+
# cmake_modules/ThirdpartyToolchain.cmake). Install the stable channel alongside the pinned default
81+
# so Vortex builds with it while Lance, Mosaic and tantivy-fts keep using the default toolchain.
82+
rustup toolchain install stable --profile minimal
83+
7984
# cbindgen is used by the crate's build.rs to emit the C header that the
8085
# C++ side includes. Corrosion will also run cbindgen at CMake configure
8186
# time; both paths need it available.

0 commit comments

Comments
 (0)