Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions docs/source/user_guide/manifest_cache.rst
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,8 @@ concurrent cache misses.

Cache implementations should use ``CacheValue::GetMemoryUsage()`` for admission
and eviction accounting. For manifest IPC, this reports the retained Arrow
buffer capacity, including unused space from growth. ``GetSegment().Size()``
continues to describe the valid IPC byte length. The built-in ``LruCache`` uses
buffer capacity, including unused space from growth.
``CacheValue::Get<const MemorySegment>(value)->Size()`` describes the valid IPC
byte length. The built-in ``LruCache`` uses
the memory usage value; existing cache values without an explicit allocation
size continue to charge their segment length.
90 changes: 78 additions & 12 deletions include/paimon/cache/cache.h
Original file line number Diff line number Diff line change
Expand Up @@ -18,11 +18,13 @@

#pragma once

#include <algorithm>
#include <cstddef>
#include <cstdint>
#include <functional>
#include <memory>
#include <string>
#include <utility>

#include "paimon/memory/memory_segment.h"
#include "paimon/result.h"
Expand All @@ -36,6 +38,7 @@ enum class CacheKind {
MANIFEST,
DATA_FILE_FOOTER,
SNAPSHOT_LIVE_MANIFEST,
INDEX_READER,
};

class PAIMON_EXPORT CacheKey {
Expand All @@ -44,6 +47,13 @@ class PAIMON_EXPORT CacheKey {
int32_t length, bool is_index);
static std::shared_ptr<CacheKey> ForKind(const std::string& file_path, int64_t position,
int32_t length, CacheKind kind);
/// Identifies one index type for a column of an immutable index file.
/// Store ObjectCacheValue<FileIndexReader> under this key.
/// Readers populated externally must keep their resources alive for the cached lifetime.
/// Paimon only looks up these entries; a miss creates a reader without populating the cache.
static std::shared_ptr<CacheKey> ForIndexReader(const std::string& uri,
const std::string& column_name,
const std::string& index_type);

public:
virtual ~CacheKey() = default;
Expand Down Expand Up @@ -88,28 +98,84 @@ class PAIMON_EXPORT Cache {

class PAIMON_EXPORT CacheValue {
public:
/// Charge the segment's logical size when no separate allocation size is supplied.
CacheValue(const MemorySegment& segment, CacheCallback callback);
virtual ~CacheValue();

/// @param memory_usage Retained allocation size in bytes, including unused capacity.
/// The charge is at least the segment's logical size.
CacheValue(const MemorySegment& segment, CacheCallback callback, int64_t memory_usage);
/// Returns the typed payload, retaining its owner; null for a null value or type mismatch.
template <typename T>
static std::shared_ptr<T> Get(const std::shared_ptr<CacheValue>& value);

~CacheValue();

const MemorySegment& GetSegment() const;

/// Bytes to charge against the cache budget. May exceed GetSegment().Size().
/// Bytes charged against the cache budget.
int64_t GetMemoryUsage() const;

void OnEvict(const std::shared_ptr<CacheKey>& key) const;

bool operator==(const CacheValue& other) const;
virtual bool operator==(const CacheValue& other) const = 0;

protected:
CacheValue(CacheCallback callback, int64_t memory_usage);

private:
MemorySegment segment_;
CacheCallback callback_;
int64_t memory_usage_;
};

template <typename T>
class PAIMON_EXPORT TypedCacheValue : public CacheValue {
protected:
using CacheValue::CacheValue;

private:
friend class CacheValue;
virtual T* GetValuePointer() = 0;
};

template <typename T>
std::shared_ptr<T> CacheValue::Get(const std::shared_ptr<CacheValue>& value) {
auto* typed_value = dynamic_cast<TypedCacheValue<T>*>(value.get());
if (typed_value) {
if (T* payload = typed_value->GetValuePointer()) {
return std::shared_ptr<T>(value, payload);
}
}
return nullptr;
}

class PAIMON_EXPORT MemorySegmentCacheValue final : public TypedCacheValue<const MemorySegment> {
public:
MemorySegmentCacheValue(const MemorySegment& segment, CacheCallback callback);

/// Charges retained allocation size, at least the segment's logical size.
MemorySegmentCacheValue(const MemorySegment& segment, CacheCallback callback,
int64_t memory_usage);

bool operator==(const CacheValue& other) const override;

private:
const MemorySegment* GetValuePointer() override {
return &segment_;
}

MemorySegment segment_;
};

template <typename T>
class PAIMON_EXPORT ObjectCacheValue final : public TypedCacheValue<T> {
public:
ObjectCacheValue(std::shared_ptr<T> value, CacheCallback callback, int64_t memory_usage)
: TypedCacheValue<T>(std::move(callback), std::max<int64_t>(1, memory_usage)),
value_(std::move(value)) {}

bool operator==(const CacheValue& other) const override {
const auto* rhs = dynamic_cast<const ObjectCacheValue<T>*>(&other);
return rhs && this->GetMemoryUsage() == rhs->GetMemoryUsage() && value_ == rhs->value_;
}

private:
T* GetValuePointer() override {
return value_.get();
}

std::shared_ptr<T> value_;
};

} // namespace paimon
7 changes: 7 additions & 0 deletions include/paimon/file_index/file_index_format.h
Original file line number Diff line number Diff line change
Expand Up @@ -108,6 +108,13 @@ class PAIMON_EXPORT FileIndexFormat::Writer {
class PAIMON_EXPORT FileIndexFormat::Reader {
public:
virtual ~Reader() = default;
/// Returns index types for a specific column from the parsed file metadata without opening
/// index readers.
/// @param column_name Name of the column to retrieve index types for.
/// @return A vector of index types, including empty and unregistered indexes; or an empty
/// vector if the column has no indexes.
virtual std::vector<std::string> GetIndexTypes(const std::string& column_name) const = 0;

/// Reads index data for a specific column from the index file.
/// @param column_name Name of the column to retrieve index data for.
/// @param arrow_schema Arrow schema that must contain a field corresponding to `column_name`.
Expand Down
12 changes: 10 additions & 2 deletions include/paimon/predicate/vector_search.h
Original file line number Diff line number Diff line change
Expand Up @@ -22,12 +22,15 @@
#include <memory>
#include <optional>
#include <string>
#include <utility>
#include <vector>

#include "paimon/predicate/predicate.h"
#include "paimon/visibility.h"

namespace paimon {
class MemoryPool;

/// `VectorSearch` to perform vector similarity search.
struct PAIMON_EXPORT VectorSearch {
/// `PreFilter`: A lightweight pre-filtering function applied **before** similarity scoring.
Expand Down Expand Up @@ -56,8 +59,9 @@ struct PAIMON_EXPORT VectorSearch {
options(_options) {}

std::shared_ptr<VectorSearch> ReplacePreFilter(PreFilter _pre_filter) const {
return std::make_shared<VectorSearch>(field_name, limit, query, _pre_filter, predicate,
distance_type, options);
auto search = std::make_shared<VectorSearch>(*this);
search->pre_filter = std::move(_pre_filter);
return search;
}

/// Search field name.
Expand Down Expand Up @@ -91,5 +95,9 @@ struct PAIMON_EXPORT VectorSearch {
/// A key-value map of query-specific runtime options.
/// Such as the size of candidate list in approximate search or parallelism for this query.
std::map<std::string, std::string> options;
/// Optional memory pool for temporary allocations during a Lumina search.
/// If null, the search uses the reader's pool. Must support concurrent allocations when
/// the search runs in parallel or the pool is shared by concurrent queries.
std::shared_ptr<MemoryPool> pool;
};
} // namespace paimon
12 changes: 12 additions & 0 deletions src/paimon/common/file_index/file_index_format.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,18 @@ class FileIndexFormatReaderImpl : public FileIndexFormat::Reader {
input_stream, std::move(header), pool, std::move(file_index_options)));
}

std::vector<std::string> GetIndexTypes(const std::string& column_name) const override {
std::vector<std::string> types;
auto iter = header_.find(column_name);
if (iter != header_.end()) {
types.reserve(iter->second.size());
for (const auto& entry : iter->second) {
types.push_back(entry.first);
}
}
return types;
}

Result<std::vector<std::shared_ptr<FileIndexReader>>> ReadColumnIndex(
const std::string& column_name, ::ArrowSchema* c_arrow_schema) const override {
PAIMON_ASSIGN_OR_RAISE_FROM_ARROW(std::shared_ptr<arrow::Schema> arrow_schema,
Expand Down
24 changes: 24 additions & 0 deletions src/paimon/common/file_index/file_index_format_test.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -180,6 +180,30 @@ class FileIndexFormatTest : public ::testing::Test {
std::shared_ptr<MemoryPool> pool_;
};

TEST_F(FileIndexFormatTest, TestGetIndexTypesFromMetadata) {
for (int32_t version : {FileIndexFormat::V_1, FileIndexFormat::V_2}) {
auto payload = std::make_shared<Bytes>(std::string("not an index payload"), pool_.get());
FileIndexFormat::ColumnIndexes indexes = {
{"embedding", {{"lumina", payload}}},
{"mixed", {{"bitmap", nullptr}, {"unregistered-index", payload}}}};
auto output = NewIndexOutput(pool_);
ASSERT_OK_AND_ASSIGN(auto writer, FileIndexFormat::CreateWriter(output, version, pool_));
ASSERT_OK(WriteIndexes(indexes, writer.get()));
ASSERT_OK(writer->Finish());
ASSERT_OK_AND_ASSIGN(auto bytes, output->Finish(pool_.get()));
auto input = std::make_shared<ByteArrayInputStream>(bytes->data(), bytes->size());
ASSERT_OK_AND_ASSIGN(auto reader,
FileIndexFormat::CreateReader(input, pool_, /*options=*/{}));
ASSERT_OK_AND_ASSIGN(int64_t position, input->GetPos());
ASSERT_EQ(reader->GetIndexTypes("embedding"), std::vector<std::string>({"lumina"}));
ASSERT_EQ(reader->GetIndexTypes("mixed"),
std::vector<std::string>({"bitmap", "unregistered-index"}));
ASSERT_TRUE(reader->GetIndexTypes("missing").empty());
ASSERT_OK_AND_ASSIGN(int64_t after, input->GetPos());
ASSERT_EQ(position, after);
}
}

TEST_F(FileIndexFormatTest, TestWriteAndReadEmptyIndexGoldenBytes) {
// the expected bytes are generated from Java Paimon
std::vector<char> expected = {0, 5, 78, 78, -48, 26, 53, -82, 0, 0, 0, 1, 0, 0, 0, 47,
Expand Down
31 changes: 15 additions & 16 deletions src/paimon/common/io/cache/cache.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -24,20 +24,11 @@

namespace paimon {

CacheValue::CacheValue(const MemorySegment& segment, CacheCallback callback)
: CacheValue(segment, std::move(callback), segment.Size()) {}

CacheValue::CacheValue(const MemorySegment& segment, CacheCallback callback, int64_t memory_usage)
: segment_(segment),
callback_(std::move(callback)),
memory_usage_(std::max<int64_t>(segment.Size(), memory_usage)) {}
CacheValue::CacheValue(CacheCallback callback, int64_t memory_usage)
: callback_(std::move(callback)), memory_usage_(memory_usage) {}

CacheValue::~CacheValue() = default;

const MemorySegment& CacheValue::GetSegment() const {
return segment_;
}

int64_t CacheValue::GetMemoryUsage() const {
return memory_usage_;
}
Expand All @@ -48,11 +39,19 @@ void CacheValue::OnEvict(const std::shared_ptr<CacheKey>& key) const {
}
}

bool CacheValue::operator==(const CacheValue& other) const {
if (this == &other) {
return true;
}
return segment_ == other.segment_;
MemorySegmentCacheValue::MemorySegmentCacheValue(const MemorySegment& segment,
CacheCallback callback)
: MemorySegmentCacheValue(segment, std::move(callback), segment.Size()) {}

MemorySegmentCacheValue::MemorySegmentCacheValue(const MemorySegment& segment,
CacheCallback callback, int64_t memory_usage)
: TypedCacheValue<const MemorySegment>(std::move(callback),
std::max<int64_t>(segment.Size(), memory_usage)),
segment_(segment) {}

bool MemorySegmentCacheValue::operator==(const CacheValue& other) const {
const auto* rhs = dynamic_cast<const MemorySegmentCacheValue*>(&other);
return rhs && GetMemoryUsage() == rhs->GetMemoryUsage() && segment_ == rhs->segment_;
}

} // namespace paimon
11 changes: 11 additions & 0 deletions src/paimon/common/io/cache/cache_key.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,8 @@

#include "paimon/common/io/cache/cache_key.h"

#include "fmt/format.h"

namespace paimon {

std::shared_ptr<CacheKey> CacheKey::ForPosition(const std::string& file_path, int64_t position,
Expand All @@ -33,6 +35,15 @@ std::shared_ptr<CacheKey> CacheKey::ForKind(const std::string& file_path, int64_
return key;
}

std::shared_ptr<CacheKey> CacheKey::ForIndexReader(const std::string& uri,
const std::string& column_name,
const std::string& index_type) {
std::string identity =
fmt::format("index-reader:{}:{}:{}:{}:{}:{}", uri.size(), uri, column_name.size(),
column_name, index_type.size(), index_type);
return ForKind(identity, 0, 0, CacheKind::INDEX_READER);
}

std::shared_ptr<CacheKey> SnapshotLiveManifestEntriesCacheKey::ForExplicit(
const std::string& table_path, const std::string& branch, int32_t bucket) {
return std::shared_ptr<CacheKey>(new SnapshotLiveManifestEntriesCacheKey(
Expand Down
8 changes: 6 additions & 2 deletions src/paimon/common/io/cache/cache_manager.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -28,10 +28,14 @@ Result<MemorySegment> CacheManager::GetPage(
auto supplier =
[&](const std::shared_ptr<CacheKey>& key) -> Result<std::shared_ptr<CacheValue>> {
PAIMON_ASSIGN_OR_RAISE(MemorySegment segment, reader(key));
return std::make_shared<CacheValue>(segment, std::move(eviction_callback));
return std::make_shared<MemorySegmentCacheValue>(segment, std::move(eviction_callback));
};
PAIMON_ASSIGN_OR_RAISE(std::shared_ptr<CacheValue> cache_value, cache->Get(key, supplier));
return cache_value->GetSegment();
auto segment = CacheValue::Get<const MemorySegment>(cache_value);
if (!segment) {
return Status::Invalid("Page cache returned an invalid value type");
}
return *segment;
}

void CacheManager::InvalidPage(const std::shared_ptr<CacheKey>& key) {
Expand Down
Loading
Loading