Commit b8644f2a authored by Luke Sandberg's avatar Luke Sandberg

Add type-safe meta file format with enum-based entries

- Add MetaFileFormat enum (Hashed, DirectFixed, DirectVariable) to distinguish
  entry formats in meta files
- Create format-specific entry structs: HashedMetaEntry, DirectFixedMetaEntry,
  DirectVariableMetaEntry with appropriate fields for each format type
- Wrap entries in MetaEntry enum with type-safe accessors (as_hashed(),
  as_direct_fixed(), as_direct_variable())
- Update MetaFileBuilder to write format byte and format-specific entries
- Update MetaFile::open_internal to read format byte and parse format-specific
  entries
- Add unreachable!() assertions for impossible cases in db.rs (AMQF miss and
  blob values in direct-fixed format)
- Update README with new meta file format documentation
Co-Authored-By: 's avatarClaude Opus 4.5 <noreply@anthropic.com>
parent 6a73cf81
...@@ -33,31 +33,72 @@ Therefore there are there value types: ...@@ -33,31 +33,72 @@ Therefore there are there value types:
### Meta file ### Meta file
A meta file can contain metadata about multiple SST files. The metadata is stored in a single file to avoid having too many small files. A meta file can contain metadata about multiple SST files. The metadata is stored in a single file to avoid having too many small files. The file format varies based on the type of entries it describes.
- Header - Header (common to all formats)
- 4 bytes magic number (0xFE4ADA4A) - 4 bytes magic number (0xFE4ADA4A)
- 4 bytes key family - 4 bytes key family
- 1 byte format type:
- 0: Hashed (standard format with AMQF)
- 1: DirectFixed (u32 keys with fixed-size values)
- 2: DirectVariable (u32 keys with variable-size values)
- 4 bytes count of obsolete SST files - 4 bytes count of obsolete SST files
- foreach obsolete SST file - foreach obsolete SST file
- 4 bytes sequence number of the obsolete SST file - 4 bytes sequence number of the obsolete SST file
- 4 bytes count of described SST files - 4 bytes count of described SST files
- foreach described SST file
- 4 bytes sequence number of the SST file #### Hashed Format (format byte = 0)
- 2 bytes key Compression Dictionary length
- 2 bytes block count - foreach described SST file (40 bytes per entry)
- 8 bytes min hash - 4 bytes sequence number of the SST file
- 8 bytes max hash - 2 bytes key Compression Dictionary length
- 8 bytes SST file size - 2 bytes block count
- 4 bytes flags - 8 bytes min hash
- bit 0: cold (compacted and not recently accessed) - 8 bytes max hash
- bit 1: fresh (not yet compacted) - 8 bytes SST file size
- 4 bytes end of AMQF offset relative to start of all AMQF data - 4 bytes flags
- 4 bytes end of AMQF offset relative to start of all AMQF data of the "used key hashes" AMQF - bit 0: cold (compacted and not recently accessed)
- bit 1: fresh (not yet compacted)
- 4 bytes end of AMQF offset relative to start of all AMQF data
- 4 bytes end of AMQF offset relative to start of all AMQF data of the "used key hashes" AMQF
- foreach described SST file - foreach described SST file
- serialized AMQF - serialized AMQF
- serialized "used key hashes" AMQF - serialized "used key hashes" AMQF
#### DirectFixed Format (format byte = 1)
For families with u32 keys and fixed-size values. No AMQF filter - uses simple key range checks.
- foreach described SST file (24 bytes per entry)
- 4 bytes sequence number of the SST file
- 4 bytes min key (rotated u32)
- 4 bytes max key (rotated u32)
- 8 bytes SST file size
- 4 bytes flags
- bit 0: cold (compacted and not recently accessed)
- bit 1: fresh (not yet compacted)
- bit 2: direct_key (always set)
- bit 3: fixed_value (always set)
- bit 4: uncompressed (always set)
- bits 8-15: key_size (always 4 for u32)
- bits 16-23: value_size
#### DirectVariable Format (format byte = 2)
For families with u32 keys and variable-size values. No AMQF filter - uses simple key range checks.
- foreach described SST file (26 bytes per entry)
- 4 bytes sequence number of the SST file
- 4 bytes min key (rotated u32)
- 4 bytes max key (rotated u32)
- 8 bytes SST file size
- 2 bytes block count
- 4 bytes flags
- bit 0: cold (compacted and not recently accessed)
- bit 1: fresh (not yet compacted)
- bit 2: direct_key (always set)
- bits 8-15: key_size (always 4 for u32)
### SST file ### SST file
The SST file contains only data without any header. The SST file contains only data without any header.
...@@ -132,6 +173,75 @@ TODO: 8 bytes key hash is a bit inefficient for small keys. ...@@ -132,6 +173,75 @@ TODO: 8 bytes key hash is a bit inefficient for small keys.
- no header, all bytes are data referenced by other blocks - no header, all bytes are data referenced by other blocks
- max block size: 4 GB - max block size: 4 GB
### Direct-Key SST Formats
For families with u32 integer keys (like TaskId), there are optimized formats that skip the 8-byte key hash prefix. This saves space and allows more efficient binary search.
#### Key Rotation for Sharding
TaskId uses the upper 2 bits for sharding purposes. To ensure proper sorting, keys are stored **rotated** using `rotate_right(2)`, which moves the sharding bits from the high end to the low end. This ensures that entries are grouped by their "logical" key value while still maintaining efficient binary search.
The rotation is:
- `stored_key = key.rotate_right(2)`
- `original_key = stored_key.rotate_left(2)`
For range checks, we use a "range value" which is the rotated key placed in the high 32 bits of a u64:
- `range_value = (rotated_key as u64) << 32`
#### Direct-Fixed Format
For families with u32 keys AND fixed-size values (like TaskIdToTaskTypeHash with 8-byte hash values):
- **Separated keys and values** - keys in one section, values in another for cache-efficient binary search
- **No AMQF filter** - only min/max key range checks
- **No compression** - data stored raw for direct mmap access
- **Direct binary search** - only 4 bytes touched per comparison
File layout:
```
[key table: u32 × entry_count, sorted by rotated key]
[value table: VALUE_SIZE × entry_count, same order as keys]
[footer: u32 entry_count]
```
Lookup: binary search key table (4 bytes per comparison) → use index to read value from value table
#### Direct-Variable Format
For families with u32 keys but variable-size values (like TaskMeta, TaskData):
- **Separated keys and value locations** - keys in one section for efficient binary search
- **Value location index** - 8 bytes per entry encoding block/offset/size
- **Compression** applied to value blocks only
- **No AMQF filter** - uses simple key range checks
File layout:
```
[value blocks (compressed)]
[value block offsets: u32 × block_count]
[key table: u32 × entry_count, sorted by rotated key]
[value location index: 8 bytes × entry_count]
[footer: u32 entry_count, u16 block_count]
```
Value location index entry (8 bytes):
- `[u16 block_index][u16 value_size][u32 offset]`
- Sentinels: block_index=0xFFFF → blob, block_index=0xFFFE → deleted, value_size=0xFFFF → medium
Lookup: binary search key table → read value location index[i] → fetch value from block
#### Size Savings
For a family like TaskIdToTaskTypeHash (u32 key -> u64 hash):
- **Standard format**: ~20 bytes/entry (8-byte hash prefix + overhead)
- **Direct-fixed format**: 12 bytes/entry (4-byte key + 8-byte value)
- **Savings**: ~40%
For TaskMeta/TaskData (u32 key -> variable value):
- **Standard format**: 8-byte hash prefix + variable block entries + index blocks
- **Direct-variable format**: 4-byte key + 8-byte location index = 12 bytes metadata per entry
- **Benefits**: Unified key lookup (only 4 bytes per binary search comparison), no index block traversal
### Blob file ### Blob file
The plain value compressed with dynamic compression. The plain value compressed with dynamic compression.
......
...@@ -29,7 +29,7 @@ use crate::{ ...@@ -29,7 +29,7 @@ use crate::{
KEY_BLOCK_CACHE_SIZE, MAX_ENTRIES_PER_COMPACTED_FILE, VALUE_BLOCK_AVG_SIZE, KEY_BLOCK_CACHE_SIZE, MAX_ENTRIES_PER_COMPACTED_FILE, VALUE_BLOCK_AVG_SIZE,
VALUE_BLOCK_CACHE_SIZE, VALUE_BLOCK_CACHE_SIZE,
}, },
family_format::FormatConfig, family_format::{FormatConfig, key_to_range_value},
key::{StoreKey, hash_key}, key::{StoreKey, hash_key},
lookup_entry::{LookupEntry, LookupValue}, lookup_entry::{LookupEntry, LookupValue},
merge_iter::MergeIter, merge_iter::MergeIter,
...@@ -1463,15 +1463,15 @@ impl<S: ParallelScheduler, const FAMILIES: usize> TurboPersistence<S, FAMILIES> ...@@ -1463,15 +1463,15 @@ impl<S: ParallelScheduler, const FAMILIES: usize> TurboPersistence<S, FAMILIES>
/// Get a value from a direct-key fixed-value family. /// Get a value from a direct-key fixed-value family.
/// ///
/// This is optimized for families with fixed-size integer keys and fixed-size values /// This is optimized for families with u32 integer keys and fixed-size values
/// stored inline without compression (e.g., TaskIdToTaskTypeHash). /// stored inline without compression (e.g., TaskIdToTaskTypeHash).
/// ///
/// The key should be the raw key bytes (e.g., TaskId as 4 bytes big-endian). /// The key is a u32 (e.g., TaskId). It will be rotated internally for lookup.
/// Returns the fixed-size value bytes if found. /// Returns the fixed-size value bytes if found.
pub fn get_direct_fixed<const KEY_SIZE: usize, const VALUE_SIZE: usize>( pub fn get_direct_fixed<const VALUE_SIZE: usize>(
&self, &self,
family: usize, family: usize,
key: &[u8; KEY_SIZE], key: u32,
) -> Result<Option<[u8; VALUE_SIZE]>> { ) -> Result<Option<[u8; VALUE_SIZE]>> {
debug_assert!(family < FAMILIES, "Family index out of bounds"); debug_assert!(family < FAMILIES, "Family index out of bounds");
debug_assert!( debug_assert!(
...@@ -1481,32 +1481,29 @@ impl<S: ParallelScheduler, const FAMILIES: usize> TurboPersistence<S, FAMILIES> ...@@ -1481,32 +1481,29 @@ impl<S: ParallelScheduler, const FAMILIES: usize> TurboPersistence<S, FAMILIES>
); );
let inner = self.inner.read(); let inner = self.inner.read();
for meta in inner.meta_files.iter().rev() { for meta in inner.meta_files.iter().rev() {
match meta.lookup_direct_fixed::<KEY_SIZE, VALUE_SIZE>( match meta.lookup_direct_fixed::<VALUE_SIZE>(family as u32, key)? {
family as u32, MetaLookupResult::FamilyMiss | MetaLookupResult::RangeMiss => {
key,
&self.amqf_cache,
)? {
MetaLookupResult::FamilyMiss
| MetaLookupResult::RangeMiss
| MetaLookupResult::QuickFilterMiss => {
// Continue searching other meta files // Continue searching other meta files
} }
MetaLookupResult::QuickFilterMiss => {
unreachable!("Direct-fixed format doesn't use AMQF")
}
MetaLookupResult::SstLookup(result) => match result { MetaLookupResult::SstLookup(result) => match result {
SstLookupResult::Found(LookupValue::Slice { value }) => { SstLookupResult::Found(LookupValue::Slice { value }) => {
// Convert ArcSlice to fixed array // Convert ArcSlice to fixed array
let mut result = [0u8; VALUE_SIZE]; let mut result = [0u8; VALUE_SIZE];
result.copy_from_slice(&value); result.copy_from_slice(&value);
// For direct-key formats, we use key bytes as hash for access tracking // For direct-key formats, we use rotated key as range value for access
let key_hash = key_bytes_to_hash::<KEY_SIZE>(key); // tracking
inner.accessed_key_hashes[family].insert(key_hash); let key_range_value = key_to_range_value(key);
inner.accessed_key_hashes[family].insert(key_range_value);
return Ok(Some(result)); return Ok(Some(result));
} }
SstLookupResult::Found(LookupValue::Deleted) => { SstLookupResult::Found(LookupValue::Deleted) => {
return Ok(None); return Ok(None);
} }
SstLookupResult::Found(LookupValue::Blob { .. }) => { SstLookupResult::Found(LookupValue::Blob { .. }) => {
// Fixed values shouldn't be stored as blob unreachable!("Direct-fixed format cannot store blob values")
return Ok(None);
} }
SstLookupResult::NotFound => { SstLookupResult::NotFound => {
// Continue searching other meta files // Continue searching other meta files
...@@ -1519,15 +1516,11 @@ impl<S: ParallelScheduler, const FAMILIES: usize> TurboPersistence<S, FAMILIES> ...@@ -1519,15 +1516,11 @@ impl<S: ParallelScheduler, const FAMILIES: usize> TurboPersistence<S, FAMILIES>
/// Get a value from a direct-key variable-value family. /// Get a value from a direct-key variable-value family.
/// ///
/// This is optimized for families with fixed-size integer keys but variable-size /// This is optimized for families with u32 integer keys but variable-size
/// values stored in compressed blocks (e.g., TaskMeta, TaskData). /// values stored in compressed blocks (e.g., TaskMeta, TaskData).
/// ///
/// The key should be the raw key bytes (e.g., TaskId as 4 bytes big-endian). /// The key is a u32 (e.g., TaskId). It will be rotated internally for lookup.
pub fn get_direct_variable<const KEY_SIZE: usize>( pub fn get_direct_variable(&self, family: usize, key: u32) -> Result<Option<ArcSlice<u8>>> {
&self,
family: usize,
key: &[u8; KEY_SIZE],
) -> Result<Option<ArcSlice<u8>>> {
debug_assert!(family < FAMILIES, "Family index out of bounds"); debug_assert!(family < FAMILIES, "Family index out of bounds");
debug_assert!( debug_assert!(
self.family_configs[family].uses_direct_keys() self.family_configs[family].uses_direct_keys()
...@@ -1537,30 +1530,25 @@ impl<S: ParallelScheduler, const FAMILIES: usize> TurboPersistence<S, FAMILIES> ...@@ -1537,30 +1530,25 @@ impl<S: ParallelScheduler, const FAMILIES: usize> TurboPersistence<S, FAMILIES>
); );
let inner = self.inner.read(); let inner = self.inner.read();
for meta in inner.meta_files.iter().rev() { for meta in inner.meta_files.iter().rev() {
match meta.lookup_direct_variable::<KEY_SIZE>( match meta.lookup_direct_variable(family as u32, key, &self.value_block_cache)? {
family as u32, MetaLookupResult::FamilyMiss | MetaLookupResult::RangeMiss => {
key,
&self.amqf_cache,
&self.key_block_cache,
&self.value_block_cache,
)? {
MetaLookupResult::FamilyMiss
| MetaLookupResult::RangeMiss
| MetaLookupResult::QuickFilterMiss => {
// Continue searching other meta files // Continue searching other meta files
} }
MetaLookupResult::QuickFilterMiss => {
unreachable!("Direct-variable format doesn't use AMQF")
}
MetaLookupResult::SstLookup(result) => match result { MetaLookupResult::SstLookup(result) => match result {
SstLookupResult::Found(LookupValue::Slice { value }) => { SstLookupResult::Found(LookupValue::Slice { value }) => {
let key_hash = key_bytes_to_hash::<KEY_SIZE>(key); let key_range_value = key_to_range_value(key);
inner.accessed_key_hashes[family].insert(key_hash); inner.accessed_key_hashes[family].insert(key_range_value);
return Ok(Some(value)); return Ok(Some(value));
} }
SstLookupResult::Found(LookupValue::Deleted) => { SstLookupResult::Found(LookupValue::Deleted) => {
return Ok(None); return Ok(None);
} }
SstLookupResult::Found(LookupValue::Blob { sequence_number }) => { SstLookupResult::Found(LookupValue::Blob { sequence_number }) => {
let key_hash = key_bytes_to_hash::<KEY_SIZE>(key); let key_range_value = key_to_range_value(key);
inner.accessed_key_hashes[family].insert(key_hash); inner.accessed_key_hashes[family].insert(key_range_value);
let blob = self.read_blob(sequence_number)?; let blob = self.read_blob(sequence_number)?;
return Ok(Some(blob)); return Ok(Some(blob));
} }
...@@ -1789,15 +1777,3 @@ pub struct MetaFileEntryInfo { ...@@ -1789,15 +1777,3 @@ pub struct MetaFileEntryInfo {
pub key_compression_dictionary_size: u16, pub key_compression_dictionary_size: u16,
pub block_count: u16, pub block_count: u16,
} }
/// Converts key bytes to a u64 hash for AMQF filter and access tracking.
///
/// For keys smaller than 8 bytes, pads with zeros on the right.
/// For keys larger than 8 bytes, uses only the first 8 bytes.
#[inline]
fn key_bytes_to_hash<const KEY_SIZE: usize>(key: &[u8]) -> u64 {
let mut hash_bytes = [0u8; 8];
let copy_len = KEY_SIZE.min(8);
hash_bytes[..copy_len].copy_from_slice(&key[..copy_len]);
u64::from_be_bytes(hash_bytes)
}
...@@ -7,6 +7,16 @@ ...@@ -7,6 +7,16 @@
//! - **Direct keys**: Integer keys (like TaskId) can be stored without hashing //! - **Direct keys**: Integer keys (like TaskId) can be stored without hashing
//! - **Fixed values**: Known-size values can be stored inline without offset tables //! - **Fixed values**: Known-size values can be stored inline without offset tables
//! - **Skip compression**: High-entropy data (like hashes) doesn't compress well //! - **Skip compression**: High-entropy data (like hashes) doesn't compress well
//!
//! ## Key Rotation for Sharding
//!
//! TaskId uses the upper 2 bits for sharding purposes. When storing keys directly
//! (sorted by byte order), we need to rotate the key so that the sharding bits
//! don't dominate the sort order. We rotate right by 2 bits, moving the sharding
//! bits to the low end.
//!
//! This allows entries with the same "logical" key to be grouped together while
//! still maintaining efficient binary search.
/// Describes the storage format for a key-value family. /// Describes the storage format for a key-value family.
/// ///
...@@ -143,3 +153,40 @@ impl_family_formats!(5, 0: F0, 1: F1, 2: F2, 3: F3, 4: F4); ...@@ -143,3 +153,40 @@ impl_family_formats!(5, 0: F0, 1: F1, 2: F2, 3: F3, 4: F4);
impl_family_formats!(6, 0: F0, 1: F1, 2: F2, 3: F3, 4: F4, 5: F5); impl_family_formats!(6, 0: F0, 1: F1, 2: F2, 3: F3, 4: F4, 5: F5);
impl_family_formats!(7, 0: F0, 1: F1, 2: F2, 3: F3, 4: F4, 5: F5, 6: F6); impl_family_formats!(7, 0: F0, 1: F1, 2: F2, 3: F3, 4: F4, 5: F5, 6: F6);
impl_family_formats!(8, 0: F0, 1: F1, 2: F2, 3: F3, 4: F4, 5: F5, 6: F6, 7: F7); impl_family_formats!(8, 0: F0, 1: F1, 2: F2, 3: F3, 4: F4, 5: F5, 6: F6, 7: F7);
// =============================================================================
// Key Conversion Utilities for u32 Direct Keys
// =============================================================================
/// Rotates a u32 key right by 2 bits for proper sorting.
///
/// TaskId uses the upper 2 bits for sharding. By rotating right, we move
/// the sharding bits to the low end so they don't dominate the sort order.
/// This ensures entries are grouped by their logical key value.
#[inline]
pub fn rotate_key(key: u32) -> u32 {
key.rotate_right(2)
}
/// Unrotates a u32 key (inverse of rotate_key).
#[inline]
pub fn unrotate_key(rotated: u32) -> u32 {
rotated.rotate_left(2)
}
/// Converts a rotated u32 key to a u64 for range comparisons.
///
/// The rotated key is placed in the high 32 bits so that u64 comparisons
/// maintain the same ordering as u32 comparisons on the rotated keys.
#[inline]
pub fn rotated_key_to_u64(rotated_key: u32) -> u64 {
(rotated_key as u64) << 32
}
/// Converts a u32 key to a rotated u64 for range comparisons.
///
/// Combines rotation and conversion in one step.
#[inline]
pub fn key_to_range_value(key: u32) -> u64 {
rotated_key_to_u64(rotate_key(key))
}
...@@ -30,7 +30,8 @@ pub use arc_slice::ArcSlice; ...@@ -30,7 +30,8 @@ pub use arc_slice::ArcSlice;
pub use db::{CompactConfig, MetaFileEntryInfo, MetaFileInfo, TurboPersistence}; pub use db::{CompactConfig, MetaFileEntryInfo, MetaFileInfo, TurboPersistence};
pub use family_format::{ pub use family_format::{
DefaultFormat, DirectKeyFixedValue, DirectKeyVariableValue, FamilyFormat, FamilyFormats, DefaultFormat, DirectKeyFixedValue, DirectKeyVariableValue, FamilyFormat, FamilyFormats,
FormatConfig, TaskIdKeyedFormat, TaskIdToHashFormat, FormatConfig, TaskIdKeyedFormat, TaskIdToHashFormat, key_to_range_value, rotate_key,
rotated_key_to_u64, unrotate_key,
}; };
pub use key::{KeyBase, QueryKey, StoreKey, hash_key}; pub use key::{KeyBase, QueryKey, StoreKey, hash_key};
pub use meta_file::MetaEntryFlags; pub use meta_file::MetaEntryFlags;
......
...@@ -8,7 +8,7 @@ use anyhow::{Context, Result}; ...@@ -8,7 +8,7 @@ use anyhow::{Context, Result};
use byteorder::{BE, WriteBytesExt}; use byteorder::{BE, WriteBytesExt};
use qfilter::Filter; use qfilter::Filter;
use crate::static_sorted_file_builder::StaticSortedFileBuilderMeta; use crate::{meta_file::MetaFileFormat, static_sorted_file_builder::StaticSortedFileBuilderMeta};
pub struct MetaFileBuilder<'a> { pub struct MetaFileBuilder<'a> {
family: u32, family: u32,
...@@ -54,6 +54,24 @@ impl<'a> MetaFileBuilder<'a> { ...@@ -54,6 +54,24 @@ impl<'a> MetaFileBuilder<'a> {
file.write_u32::<BE>(0xFE4ADA4A)?; // Magic number file.write_u32::<BE>(0xFE4ADA4A)?; // Magic number
file.write_u32::<BE>(self.family)?; file.write_u32::<BE>(self.family)?;
// Determine format type from first entry's flags
let format = if let Some((_, first_entry)) = self.entries.first() {
if first_entry.flags.uses_direct_keys() {
if first_entry.flags.uses_fixed_values() {
MetaFileFormat::DirectFixed
} else {
MetaFileFormat::DirectVariable
}
} else {
MetaFileFormat::Hashed
}
} else {
MetaFileFormat::Hashed // Default for empty meta files
};
// Write format byte
file.write_u8(format as u8)?;
self.obsolete_sst_files.sort(); self.obsolete_sst_files.sort();
file.write_u32::<BE>(self.obsolete_sst_files.len() as u32)?; file.write_u32::<BE>(self.obsolete_sst_files.len() as u32)?;
for obsolete_sst in &self.obsolete_sst_files { for obsolete_sst in &self.obsolete_sst_files {
...@@ -62,6 +80,22 @@ impl<'a> MetaFileBuilder<'a> { ...@@ -62,6 +80,22 @@ impl<'a> MetaFileBuilder<'a> {
file.write_u32::<BE>(self.entries.len() as u32)?; file.write_u32::<BE>(self.entries.len() as u32)?;
match format {
MetaFileFormat::Hashed => {
self.write_hashed_entries(&mut file)?;
}
MetaFileFormat::DirectFixed => {
self.write_direct_fixed_entries(&mut file)?;
}
MetaFileFormat::DirectVariable => {
self.write_direct_variable_entries(&mut file)?;
}
}
Ok(file.into_inner()?)
}
fn write_hashed_entries(self, file: &mut BufWriter<File>) -> io::Result<()> {
let mut amqf_offset = 0; let mut amqf_offset = 0;
for (sequence_number, sst) in &self.entries { for (sequence_number, sst) in &self.entries {
file.write_u32::<BE>(*sequence_number)?; file.write_u32::<BE>(*sequence_number)?;
...@@ -90,6 +124,40 @@ impl<'a> MetaFileBuilder<'a> { ...@@ -90,6 +124,40 @@ impl<'a> MetaFileBuilder<'a> {
if let Some(bytes) = &serialized_used_key_hashes { if let Some(bytes) = &serialized_used_key_hashes {
file.write_all(bytes)?; file.write_all(bytes)?;
} }
Ok(file.into_inner()?) Ok(())
}
fn write_direct_fixed_entries(&self, file: &mut BufWriter<File>) -> io::Result<()> {
// Direct-fixed format: no AMQF, no compression dictionary
// Entry: seq_num(4) + min_key(4) + max_key(4) + size(8) + flags(4) = 24 bytes
for (sequence_number, sst) in &self.entries {
file.write_u32::<BE>(*sequence_number)?;
// Extract u32 key from the range value (stored in high 32 bits of u64)
let min_key = (sst.min_hash >> 32) as u32;
let max_key = (sst.max_hash >> 32) as u32;
file.write_u32::<BE>(min_key)?;
file.write_u32::<BE>(max_key)?;
file.write_u64::<BE>(sst.size)?;
file.write_u32::<BE>(sst.flags.0)?;
}
Ok(())
}
fn write_direct_variable_entries(&self, file: &mut BufWriter<File>) -> io::Result<()> {
// Direct-variable format: no AMQF, no compression dictionary, but has block_count
// Entry: seq_num(4) + min_key(4) + max_key(4) + size(8) + block_count(2) + flags(4) = 26
// bytes
for (sequence_number, sst) in &self.entries {
file.write_u32::<BE>(*sequence_number)?;
// Extract u32 key from the range value (stored in high 32 bits of u64)
let min_key = (sst.min_hash >> 32) as u32;
let max_key = (sst.max_hash >> 32) as u32;
file.write_u32::<BE>(min_key)?;
file.write_u32::<BE>(max_key)?;
file.write_u64::<BE>(sst.size)?;
file.write_u16::<BE>(sst.block_count)?;
file.write_u32::<BE>(sst.flags.0)?;
}
Ok(())
} }
} }
...@@ -1307,19 +1307,20 @@ fn batch_get_after_restore() -> Result<()> { ...@@ -1307,19 +1307,20 @@ fn batch_get_after_restore() -> Result<()> {
#[test] #[test]
fn test_direct_fixed_sst() -> Result<()> { fn test_direct_fixed_sst() -> Result<()> {
use crate::{ use crate::{
family_format::rotate_key,
meta_file::MetaEntryFlags, meta_file::MetaEntryFlags,
static_sorted_file::{StaticSortedFile, StaticSortedFileMetaData}, static_sorted_file::{StaticSortedFile, StaticSortedFileMetaData},
static_sorted_file_builder::{DirectFixedEntry, write_direct_fixed_sst}, static_sorted_file_builder::{DirectFixedEntry, write_direct_fixed_sst},
}; };
struct TestEntry { struct TestEntry {
key: [u8; 4], key: u32,
value: [u8; 8], value: [u8; 8],
} }
impl DirectFixedEntry for TestEntry { impl DirectFixedEntry for TestEntry {
fn key_bytes(&self) -> &[u8] { fn key(&self) -> u32 {
&self.key self.key
} }
fn value_bytes(&self) -> &[u8] { fn value_bytes(&self) -> &[u8] {
&self.value &self.value
...@@ -1330,20 +1331,21 @@ fn test_direct_fixed_sst() -> Result<()> { ...@@ -1330,20 +1331,21 @@ fn test_direct_fixed_sst() -> Result<()> {
let path = tempdir.path(); let path = tempdir.path();
let sst_path = path.join("00000001.sst"); let sst_path = path.join("00000001.sst");
// Create test entries (sorted by key) // Create test entries (sorted by rotated key for proper ordering)
let mut entries: Vec<TestEntry> = (0..100u32) let mut entries: Vec<TestEntry> = (0..100u32)
.map(|i| TestEntry { .map(|i| TestEntry {
key: i.to_be_bytes(), key: i,
value: (i as u64 * 2).to_be_bytes(), value: (i as u64 * 2).to_be_bytes(),
}) })
.collect(); .collect();
entries.sort_by_key(|e| e.key); // Sort by rotated key (how they're stored in the SST)
entries.sort_by_key(|e| rotate_key(e.key));
// Create flags for direct-key fixed-value format // Create flags for direct-key fixed-value format
let flags = MetaEntryFlags::direct_key_fixed(4, 8); let flags = MetaEntryFlags::direct_key_fixed(4, 8);
// Write the SST file // Write the SST file
let (meta, file) = write_direct_fixed_sst::<4, 8>(&entries, &sst_path, flags)?; let (meta, file) = write_direct_fixed_sst::<8>(&entries, &sst_path, flags)?;
file.sync_all()?; file.sync_all()?;
// Verify metadata // Verify metadata
...@@ -1351,6 +1353,8 @@ fn test_direct_fixed_sst() -> Result<()> { ...@@ -1351,6 +1353,8 @@ fn test_direct_fixed_sst() -> Result<()> {
assert_eq!(meta.key_compression_dictionary_length, 0); assert_eq!(meta.key_compression_dictionary_length, 0);
assert!(meta.flags.uses_direct_keys()); assert!(meta.flags.uses_direct_keys());
assert!(meta.flags.uses_fixed_values()); assert!(meta.flags.uses_fixed_values());
// Direct-fixed format has no AMQF
assert!(meta.amqf.is_empty());
// Open and read back // Open and read back
let sst = StaticSortedFile::open( let sst = StaticSortedFile::open(
...@@ -1362,24 +1366,63 @@ fn test_direct_fixed_sst() -> Result<()> { ...@@ -1362,24 +1366,63 @@ fn test_direct_fixed_sst() -> Result<()> {
}, },
)?; )?;
// Test lookup for various keys // Test lookup for various keys (using u32 keys, not byte arrays)
for i in [0u32, 42, 50, 99] { for i in [0u32, 42, 50, 99] {
let key = i.to_be_bytes();
let expected_value = (i as u64 * 2).to_be_bytes(); let expected_value = (i as u64 * 2).to_be_bytes();
let result = sst.lookup_direct_fixed::<4, 8>(&key)?; let result = sst.lookup_direct_fixed::<8>(i)?;
assert_eq!(result, Some(expected_value), "Failed to lookup key {i}"); assert_eq!(result, Some(expected_value), "Failed to lookup key {i}");
} }
// Test lookup for non-existent keys // Test lookup for non-existent keys
for i in [100u32, 200, 1000] { for i in [100u32, 200, 1000] {
let key = i.to_be_bytes(); let result = sst.lookup_direct_fixed::<8>(i)?;
let result = sst.lookup_direct_fixed::<4, 8>(&key)?;
assert_eq!(result, None, "Should not find non-existent key {i}"); assert_eq!(result, None, "Should not find non-existent key {i}");
} }
Ok(()) Ok(())
} }
#[test]
fn test_key_rotation() {
use crate::family_format::{key_to_range_value, rotate_key, unrotate_key};
// Test that rotate/unrotate are inverses
for key in [0u32, 1, 100, 1000, u32::MAX / 2, u32::MAX] {
assert_eq!(unrotate_key(rotate_key(key)), key);
}
// Test that keys with different sharding bits (upper 2 bits) are grouped properly
// after rotation. The upper 2 bits become the lower 2 bits after rotate_right(2).
// Keys 0, 1<<30, 2<<30, 3<<30 have different sharding bits but should sort
// in a more natural order after rotation.
let keys_with_different_shards = [
0u32, // shard 0
1 << 30, // shard 1
2 << 30, // shard 2
3 << 30, // shard 3
1, // shard 0, but different value
(1 << 30) + 1, // shard 1, but different value
];
// After rotation, keys with the same "logical" value (ignoring shard bits)
// should be closer together in sort order
let _rotated: Vec<u32> = keys_with_different_shards
.iter()
.map(|&k| rotate_key(k))
.collect();
// The rotated keys should now have the sharding bits in the low position
assert_eq!(rotate_key(0), 0); // 0 rotates to 0
assert_eq!(rotate_key(1 << 30), 1 << 28); // high bit moves to bit 28
assert_eq!(rotate_key(2 << 30), 2 << 28);
assert_eq!(rotate_key(3 << 30), 3 << 28);
// key_to_range_value should place rotated key in high 32 bits of u64
let range_val = key_to_range_value(42);
assert_eq!(range_val >> 32, rotate_key(42) as u64);
assert_eq!(range_val & 0xFFFFFFFF, 0);
}
#[test] #[test]
fn test_meta_entry_flags() { fn test_meta_entry_flags() {
use crate::meta_file::MetaEntryFlags; use crate::meta_file::MetaEntryFlags;
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment