duckdb 0.8.2-dev37.0 → 0.8.2-dev3989.0

package/src/duckdb/src/include/duckdb/execution/aggregate_hashtable.hpp

@@ -8,12 +8,13 @@
 
 #pragma once
 
-#include "duckdb/common/types/row/tuple_data_collection.hpp"
+#include "duckdb/common/types/row/partitioned_tuple_data.hpp"
 #include "duckdb/execution/base_aggregate_hashtable.hpp"
 #include "duckdb/storage/arena_allocator.hpp"
 #include "duckdb/storage/buffer/buffer_handle.hpp"
 
 namespace duckdb {
+
 class BlockHandle;
 class BufferHandle;
 
@@ -27,91 +28,87 @@ struct FlushMoveState;
    stores them in the HT. It uses linear probing for collision resolution.
 */
 
-// two part hash table
-// hashes and payload
-// hashes layout:
-// [SALT][PAGE_NR][PAGE_OFFSET]
-// [SALT] are the high bits of the hash value, e.g. 16 for 64 bit hashes
-// [PAGE_NR] is the buffer managed payload page index
-// [PAGE_OFFSET] is the logical entry offset into said payload page
-
-// NOTE: PAGE_NR and PAGE_OFFSET are reversed for 64 bit HTs because struct packing
-
-// payload layout
-// [VALIDITY][GROUPS][HASH][PADDING][PAYLOAD]
-// [VALIDITY] is the validity bits of the data columns (including the HASH)
-// [GROUPS] is the group data, could be multiple values, fixed size, strings are elsewhere
-// [HASH] is the hash data of the groups
-// [PADDING] is gunk data to align payload properly
-// [PAYLOAD] is the payload (i.e. the aggregate states)
-struct aggr_ht_entry_64 {
-	uint16_t salt;
-	uint16_t page_offset;
-	uint32_t page_nr; // this has to come last because alignment
-};
+struct aggr_ht_entry_t {
+public:
+	explicit aggr_ht_entry_t(hash_t value_p) : value(value_p) {
+	}
 
-struct aggr_ht_entry_32 {
-	uint8_t salt;
-	uint8_t page_nr;
-	uint16_t page_offset;
-};
+	inline bool IsOccupied() const {
+		return value != 0;
+	}
+
+	inline data_ptr_t GetPointer() const {
+		D_ASSERT(IsOccupied());
+		return reinterpret_cast<data_ptr_t>(value & POINTER_MASK);
+	}
+	inline void SetPointer(const data_ptr_t &pointer) {
+		// Pointer shouldn't use upper bits
+		D_ASSERT((reinterpret_cast<uint64_t>(pointer) & SALT_MASK) == 0);
+		// Value should have all 1's in the pointer area
+		D_ASSERT((value & POINTER_MASK) == POINTER_MASK);
+		// Set upper bits to 1 in pointer so the salt stays intact
+		value &= reinterpret_cast<uint64_t>(pointer) | SALT_MASK;
+	}
 
-enum HtEntryType { HT_WIDTH_32, HT_WIDTH_64 };
+	static inline hash_t ExtractSalt(const hash_t &hash) {
+		// Leaves upper bits intact, sets lower bits to all 1's
+		return hash | POINTER_MASK;
+	}
+	inline hash_t GetSalt() const {
+		return ExtractSalt(value);
+	}
+	inline void SetSalt(const hash_t &salt) {
+		// Shouldn't be occupied when we set this
+		D_ASSERT(!IsOccupied());
+		// Salt should have all 1's in the pointer field
+		D_ASSERT((salt & POINTER_MASK) == POINTER_MASK);
+		// No need to mask, just put the whole thing there
+		value = salt;
+	}
 
-struct AggregateHTScanState {
-	mutex lock;
-	TupleDataScanState scan_state;
-};
+private:
+	//! Upper 16 bits are salt
+	static constexpr const hash_t SALT_MASK = 0xFFFF000000000000;
+	//! Lower 48 bits are the pointer
+	static constexpr const hash_t POINTER_MASK = 0x0000FFFFFFFFFFFF;
 
-struct AggregateHTAppendState {
-	AggregateHTAppendState();
-
-	Vector ht_offsets;
-	Vector hash_salts;
-	SelectionVector group_compare_vector;
-	SelectionVector no_match_vector;
-	SelectionVector empty_vector;
-	SelectionVector new_groups;
-	Vector addresses;
-	unsafe_unique_array<UnifiedVectorFormat> group_data;
-	DataChunk group_chunk;
-
-	TupleDataChunkState chunk_state;
-	bool chunk_state_initialized;
+	hash_t value;
 };
 
 class GroupedAggregateHashTable : public BaseAggregateHashTable {
-public:
-	//! The hash table load factor, when a resize is triggered
-	constexpr static float LOAD_FACTOR = 1.5;
-	constexpr static uint8_t HASH_WIDTH = sizeof(hash_t);
-
 public:
 	GroupedAggregateHashTable(ClientContext &context, Allocator &allocator, vector<LogicalType> group_types,
 	                          vector<LogicalType> payload_types, const vector<BoundAggregateExpression *> &aggregates,
-	                          HtEntryType entry_type = HtEntryType::HT_WIDTH_64,
-	                          idx_t initial_capacity = InitialCapacity());
+	                          idx_t initial_capacity = InitialCapacity(), idx_t radix_bits = 0);
 	GroupedAggregateHashTable(ClientContext &context, Allocator &allocator, vector<LogicalType> group_types,
 	                          vector<LogicalType> payload_types, vector<AggregateObject> aggregates,
-	                          HtEntryType entry_type = HtEntryType::HT_WIDTH_64,
-	                          idx_t initial_capacity = InitialCapacity());
+	                          idx_t initial_capacity = InitialCapacity(), idx_t radix_bits = 0);
 	GroupedAggregateHashTable(ClientContext &context, Allocator &allocator, vector<LogicalType> group_types);
 	~GroupedAggregateHashTable() override;
 
 public:
+	//! The hash table load factor, when a resize is triggered
+	constexpr static float LOAD_FACTOR = 1.5;
+
+	//! Get the layout of this HT
+	const TupleDataLayout &GetLayout() const;
+	//! Number of groups in the HT
+	idx_t Count() const;
+	//! Initial capacity of the HT
+	static idx_t InitialCapacity();
+	//! Capacity that can hold 'count' entries without resizing
+	static idx_t GetCapacityForCount(idx_t count);
+	//! Current capacity of the HT
+	idx_t Capacity() const;
+	//! Threshold at which to resize the HT
+	idx_t ResizeThreshold() const;
+
 	//! Add the given data to the HT, computing the aggregates grouped by the
 	//! data in the group chunk. When resize = true, aggregates will not be
 	//! computed but instead just assigned.
-	idx_t AddChunk(AggregateHTAppendState &state, DataChunk &groups, DataChunk &payload,
-	               const unsafe_vector<idx_t> &filter);
-	idx_t AddChunk(AggregateHTAppendState &state, DataChunk &groups, Vector &group_hashes, DataChunk &payload,
-	               const unsafe_vector<idx_t> &filter);
-	idx_t AddChunk(AggregateHTAppendState &state, DataChunk &groups, DataChunk &payload, AggregateType filter);
-
-	//! Scan the HT starting from the scan_position until the result and group
-	//! chunks are filled. scan_position will be updated by this function.
-	//! Returns the amount of elements found.
-	idx_t Scan(TupleDataParallelScanState &gstate, TupleDataLocalScanState &lstate, DataChunk &result);
+	idx_t AddChunk(DataChunk &groups, DataChunk &payload, const unsafe_vector<idx_t> &filter);
+	idx_t AddChunk(DataChunk &groups, Vector &group_hashes, DataChunk &payload, const unsafe_vector<idx_t> &filter);
+	idx_t AddChunk(DataChunk &groups, DataChunk &payload, AggregateType filter);
 
 	//! Fetch the aggregates for specific groups from the HT and place them in the result
 	void FetchAggregates(DataChunk &groups, DataChunk &result);
@@ -119,90 +116,90 @@ public:
 	//! Finds or creates groups in the hashtable using the specified group keys. The addresses vector will be filled
 	//! with pointers to the groups in the hash table, and the new_groups selection vector will point to the newly
 	//! created groups. The return value is the amount of newly created groups.
-	idx_t FindOrCreateGroups(AggregateHTAppendState &state, DataChunk &groups, Vector &group_hashes,
-	                         Vector &addresses_out, SelectionVector &new_groups_out);
-	idx_t FindOrCreateGroups(AggregateHTAppendState &state, DataChunk &groups, Vector &addresses_out,
+	idx_t FindOrCreateGroups(DataChunk &groups, Vector &group_hashes, Vector &addresses_out,
 	                         SelectionVector &new_groups_out);
-	void FindOrCreateGroups(AggregateHTAppendState &state, DataChunk &groups, Vector &addresses_out);
+	idx_t FindOrCreateGroups(DataChunk &groups, Vector &addresses_out, SelectionVector &new_groups_out);
+	void FindOrCreateGroups(DataChunk &groups, Vector &addresses_out);
 
-	//! Executes the filter(if any) and update the aggregates
-	void Combine(GroupedAggregateHashTable &other);
-
-	TupleDataCollection &GetDataCollection() {
-		return *data_collection;
-	}
+	unique_ptr<PartitionedTupleData> &GetPartitionedData();
+	shared_ptr<ArenaAllocator> GetAggregateAllocator();
 
-	idx_t Count() const {
-		return data_collection->Count();
-	}
-
-	static idx_t InitialCapacity();
-	idx_t Capacity() {
-		return capacity;
-	}
-
-	idx_t ResizeThreshold();
-	idx_t MaxCapacity();
-	static idx_t GetMaxCapacity(HtEntryType entry_type, idx_t tuple_size);
+	//! Resize the HT to the specified size. Must be larger than the current size.
+	void Resize(idx_t size);
+	//! Resets the pointer table of the HT to all 0's
+	void ClearPointerTable();
+	//! Resets the group count to 0
+	void ResetCount();
+	//! Set the radix bits for this HT
+	void SetRadixBits(idx_t radix_bits);
+	//! Initializes the PartitionedTupleData
+	void InitializePartitionedData();
 
-	void Partition(vector<GroupedAggregateHashTable *> &partition_hts, idx_t radix_bits);
-	void InitializeFirstPart();
+	//! Executes the filter(if any) and update the aggregates
+	void Combine(GroupedAggregateHashTable &other);
+	void Combine(TupleDataCollection &other_data);
 
-	void Finalize();
+	//! Unpins the data blocks
+	void UnpinData();
 
 private:
-	HtEntryType entry_type;
-
-	//! The capacity of the HT. This can be increased using GroupedAggregateHashTable::Resize
-	idx_t capacity;
-	//! Tuple width
-	idx_t tuple_size;
-	//! Tuples per block
-	idx_t tuples_per_block;
+	//! Append state
+	struct AggregateHTAppendState {
+		AggregateHTAppendState();
+
+		PartitionedTupleDataAppendState append_state;
+
+		Vector ht_offsets;
+		Vector hash_salts;
+		SelectionVector group_compare_vector;
+		SelectionVector no_match_vector;
+		SelectionVector empty_vector;
+		SelectionVector new_groups;
+		Vector addresses;
+		unsafe_unique_array<UnifiedVectorFormat> group_data;
+		DataChunk group_chunk;
+	} state;
+
+	//! The number of radix bits to partition by
+	idx_t radix_bits;
 	//! The data of the HT
-	unique_ptr<TupleDataCollection> data_collection;
-	TupleDataPinState td_pin_state;
-	vector<data_ptr_t> payload_hds_ptrs;
-
-	//! The hashes of the HT
-	BufferHandle hashes_hdl;
-	data_ptr_t hashes_hdl_ptr;
-	idx_t hash_offset; // Offset into the layout of the hash column
+	unique_ptr<PartitionedTupleData> partitioned_data;
 
-	hash_t hash_prefix_shift;
+	//! Predicates for matching groups (always ExpressionType::COMPARE_EQUAL)
+	vector<ExpressionType> predicates;
 
+	//! The number of groups in the HT
+	idx_t count;
+	//! The capacity of the HT. This can be increased using GroupedAggregateHashTable::Resize
+	idx_t capacity;
+	//! The hash map (pointer table) of the HT: allocated data and pointer into it
+	AllocatedData hash_map;
+	aggr_ht_entry_t *entries;
+	//! Offset of the hash column in the rows
+	idx_t hash_offset;
 	//! Bitmask for getting relevant bits from the hashes to determine the position
 	hash_t bitmask;
 
-	bool is_finalized;
-
-	vector<ExpressionType> predicates;
-
-	//! The arena allocator used by the aggregates for their internal state
+	//! The active arena allocator used by the aggregates for their internal state
 	shared_ptr<ArenaAllocator> aggregate_allocator;
+	//! Owning arena allocators that this HT has data from
+	vector<shared_ptr<ArenaAllocator>> stored_allocators;
 
 private:
+	//! Disabled the copy constructor
 	GroupedAggregateHashTable(const GroupedAggregateHashTable &) = delete;
-
+	//! Destroy the HT
 	void Destroy();
-	void Verify();
-	template <class ENTRY>
-	void VerifyInternal();
-	//! Resize the HT to the specified size. Must be larger than the current size.
-	template <class ENTRY>
-	void Resize(idx_t size);
-	//! Initializes the first part of the HT
-	template <class ENTRY>
-	void InitializeHashes();
+
+	//! Apply bitmask to get the entry in the HT
+	inline idx_t ApplyBitMask(hash_t hash) const;
+
 	//! Does the actual group matching / creation
-	template <class ENTRY>
-	idx_t FindOrCreateGroupsInternal(DataChunk &groups, Vector &group_hashes_v, Vector &addresses_v,
+	idx_t FindOrCreateGroupsInternal(DataChunk &groups, Vector &group_hashes, Vector &addresses,
 	                                 SelectionVector &new_groups);
-	//! Updates payload_hds_ptrs with the new pointers (after appending to data_collection)
-	void UpdateBlockPointers();
-	template <class ENTRY>
-	idx_t FindOrCreateGroupsInternal(AggregateHTAppendState &state, DataChunk &groups, Vector &group_hashes,
-	                                 Vector &addresses, SelectionVector &new_groups);
+
+	//! Verify the pointer table of the HT
+	void Verify();
 };
 
 } // namespace duckdb

package/src/duckdb/src/include/duckdb/execution/executor.hpp

@@ -88,6 +88,7 @@ public:
 	void AddEvent(shared_ptr<Event> event);
 
 	void AddRecursiveCTE(PhysicalOperator &rec_cte);
+	void AddMaterializedCTE(PhysicalOperator &mat_cte);
 	void ReschedulePipelines(const vector<shared_ptr<MetaPipeline>> &pipelines, vector<shared_ptr<Event>> &events);
 
 	//! Whether or not the root of the pipeline is a result collector object
@@ -129,6 +130,8 @@ private:
 	vector<shared_ptr<Pipeline>> root_pipelines;
 	//! The recursive CTE's in this query plan
 	vector<reference<PhysicalOperator>> recursive_ctes;
+	//! The materialized CTE's in this query plan
+	vector<reference<PhysicalOperator>> materialized_ctes;
 	//! The pipeline executor for the root pipeline
 	unique_ptr<PipelineExecutor> root_executor;
 	//! The current root pipeline index

package/src/duckdb/src/include/duckdb/execution/index/art/art.hpp

@@ -35,14 +35,16 @@ public:
 	//! Constructs an ART
 	ART(const vector<column_t> &column_ids, TableIOManager &table_io_manager,
 	    const vector<unique_ptr<Expression>> &unbound_expressions, const IndexConstraintType constraint_type,
-	    AttachedDatabase &db, const idx_t block_id = DConstants::INVALID_INDEX,
-	    const idx_t block_offset = DConstants::INVALID_INDEX);
+	    AttachedDatabase &db, const shared_ptr<vector<FixedSizeAllocator>> &allocators_ptr = nullptr,
+	    BlockPointer block = BlockPointer());
 	~ART() override;
 
 	//! Root of the tree
 	unique_ptr<Node> tree;
 	//! Fixed-size allocators holding the ART nodes
-	vector<unique_ptr<FixedSizeAllocator>> allocators;
+	shared_ptr<vector<FixedSizeAllocator>> allocators;
+	//! True, if the ART owns its data
+	bool owns_data;
 
 public:
 	//! Initialize a single predicate scan on the index with the given expression and column IDs
@@ -78,7 +80,7 @@ public:
 	void SearchEqualJoinNoFetch(ARTKey &key, idx_t &result_size);
 
 	//! Serializes the index and returns the pair of block_id offset positions
-	BlockPointer Serialize(MetaBlockWriter &writer) override;
+	BlockPointer Serialize(MetadataWriter &writer) override;
 
 	//! Merge another index into this index. The lock obtained from InitializeLock must be held, and the other
 	//! index must also be locked during the merge
@@ -102,24 +104,23 @@ public:
 
 	//! Find the node with a matching key, or return nullptr if not found
 	Node Lookup(Node node, const ARTKey &key, idx_t depth);
+	//! Insert a key into the tree
+	bool Insert(Node &node, const ARTKey &key, idx_t depth, const row_t &row_id);
 
 private:
 	//! Insert a row ID into a leaf
-	bool InsertToLeaf(Node &leaf_node, const row_t &row_id);
-	//! Insert a key into the tree
-	bool Insert(Node &node, const ARTKey &key, idx_t depth, const row_t &row_id);
+	bool InsertToLeaf(Node &leaf, const row_t &row_id);
 	//! Erase a key from the tree (if a leaf has more than one value) or erase the leaf itself
 	void Erase(Node &node, const ARTKey &key, idx_t depth, const row_t &row_id);
 
 	//! Returns all row IDs belonging to a key greater (or equal) than the search key
-	bool SearchGreater(ARTIndexScanState &state, ARTKey &key, bool inclusive, idx_t max_count,
-	                   vector<row_t> &result_ids);
+	bool SearchGreater(ARTIndexScanState &state, ARTKey &key, bool equal, idx_t max_count, vector<row_t> &result_ids);
 	//! Returns all row IDs belonging to a key less (or equal) than the upper_bound
-	bool SearchLess(ARTIndexScanState &state, ARTKey &upper_bound, bool inclusive, idx_t max_count,
+	bool SearchLess(ARTIndexScanState &state, ARTKey &upper_bound, bool equal, idx_t max_count,
 	                vector<row_t> &result_ids);
 	//! Returns all row IDs belonging to a key within the range of lower_bound and upper_bound
-	bool SearchCloseRange(ARTIndexScanState &state, ARTKey &lower_bound, ARTKey &upper_bound, bool left_inclusive,
-	                      bool right_inclusive, idx_t max_count, vector<row_t> &result_ids);
+	bool SearchCloseRange(ARTIndexScanState &state, ARTKey &lower_bound, ARTKey &upper_bound, bool left_equal,
+	                      bool right_equal, idx_t max_count, vector<row_t> &result_ids);
 
 	//! Initializes a merge operation by returning a set containing the buffer count of each fixed-size allocator
 	void InitializeMerge(ARTFlags &flags);

package/src/duckdb/src/include/duckdb/execution/index/art/art_key.hpp

@@ -59,7 +59,6 @@ public:
 		return data[i];
 	}
 	bool operator>(const ARTKey &k) const;
-	bool operator<(const ARTKey &k) const;
 	bool operator>=(const ARTKey &k) const;
 	bool operator==(const ARTKey &k) const;
 

package/src/duckdb/src/include/duckdb/execution/index/art/fixed_size_allocator.hpp

@@ -8,16 +8,14 @@
 
 #pragma once
 
-#include "duckdb/common/unordered_set.hpp"
-#include "duckdb/common/constants.hpp"
-#include "duckdb/common/vector.hpp"
-#include "duckdb/common/assert.hpp"
 #include "duckdb/common/types/validity_mask.hpp"
+#include "duckdb/common/unordered_set.hpp"
 #include "duckdb/storage/buffer_manager.hpp"
-#include "duckdb/execution/index/art/swizzleable_pointer.hpp"
+#include "duckdb/execution/index/art/node.hpp"
 
 namespace duckdb {
 
+// structs
 struct BufferEntry {
 	BufferEntry(const data_ptr_t &ptr, const idx_t &allocation_count) : ptr(ptr), allocation_count(allocation_count) {
 	}
@@ -26,7 +24,7 @@ struct BufferEntry {
 };
 
 //! The FixedSizeAllocator provides pointers to fixed-size sections of pre-allocated memory buffers.
-//! The pointers are SwizzleablePointers, and the leftmost byte (swizzle flag and type) must always be zero.
+//! The pointers are Node pointers, and the leftmost byte (serialize flag and type) must always be zero.
 class FixedSizeAllocator {
 public:
 	//! Fixed size of the buffers
@@ -65,17 +63,17 @@ public:
 	Allocator &allocator;
 
 public:
-	//! Get a new pointer to data, might cause a new buffer allocation
-	SwizzleablePointer New();
-	//! Free the data of the pointer
-	void Free(const SwizzleablePointer ptr);
-	//! Get the data of the pointer
+	//! Get a new Node pointer to data, might cause a new buffer allocation
+	Node New();
+	//! Free the data of the Node pointer
+	void Free(const Node ptr);
+	//! Get the data of the Node pointer
 	template <class T>
-	inline T *Get(const SwizzleablePointer ptr) const {
+	inline T *Get(const Node ptr) const {
 		return (T *)Get(ptr);
 	}
 
-	//! Resets the allocator, which e.g. becomes necessary during DELETE FROM table
+	//! Resets the allocator, e.g., becomes necessary during DELETE FROM table
 	void Reset();
 
 	//! Returns the allocated memory size in bytes
@@ -83,32 +81,32 @@ public:
 		return buffers.size() * BUFFER_ALLOC_SIZE;
 	}
 
-	//! Merge another FixedSizeAllocator with this allocator. Both must have the same allocation size
+	//! Merge another FixedSizeAllocator into this allocator. Both must have the same allocation size
 	void Merge(FixedSizeAllocator &other);
 
 	//! Initialize a vacuum operation, and return true, if the allocator needs a vacuum
 	bool InitializeVacuum();
 	//! Finalize a vacuum operation by freeing all buffers exceeding the min_vacuum_buffer_id
 	void FinalizeVacuum();
-	//! Returns true, if a pointer qualifies for a vacuum operation, and false otherwise
-	inline bool NeedsVacuum(const SwizzleablePointer ptr) const {
-		if (ptr.buffer_id >= min_vacuum_buffer_id) {
+	//! Returns true, if a Node pointer qualifies for a vacuum operation, and false otherwise
+	inline bool NeedsVacuum(const Node ptr) const {
+		if (ptr.GetBufferId() >= min_vacuum_buffer_id) {
 			return true;
 		}
 		return false;
 	}
-	//! Vacuums a pointer
-	SwizzleablePointer VacuumPointer(const SwizzleablePointer ptr);
+	//! Vacuums a Node pointer
+	Node VacuumPointer(const Node ptr);
 
 	//! Verify that the allocation counts match the existing positions on the buffers
 	void Verify() const;
 
 private:
-	//! Returns the data_ptr_t of a pointer
-	inline data_ptr_t Get(const SwizzleablePointer ptr) const {
-		D_ASSERT(ptr.buffer_id < buffers.size());
-		D_ASSERT(ptr.offset < allocations_per_buffer);
-		return buffers[ptr.buffer_id].ptr + ptr.offset * allocation_size + allocation_offset;
+	//! Returns the data_ptr_t of a Node pointer
+	inline data_ptr_t Get(const Node ptr) const {
+		D_ASSERT(ptr.GetBufferId() < buffers.size());
+		D_ASSERT(ptr.GetOffset() < allocations_per_buffer);
+		return buffers[ptr.GetBufferId()].ptr + ptr.GetOffset() * allocation_size + allocation_offset;
 	}
 	//! Returns the first free offset in a bitmask
 	uint32_t GetOffset(ValidityMask &mask, const idx_t allocation_count);

package/src/duckdb/src/include/duckdb/execution/index/art/iterator.hpp

@@ -14,9 +14,8 @@
 
 namespace duckdb {
 
+//! Keeps track of the byte leading to the currently active child of the node
 struct IteratorEntry {
-	IteratorEntry() {
-	}
 	IteratorEntry(Node node, uint8_t byte) : node(node), byte(byte) {
 	}
 
@@ -24,16 +23,23 @@ struct IteratorEntry {
 	uint8_t byte = 0;
 };
 
-//! Keeps track of the current key in the iterator
-class IteratorCurrentKey {
+//! Keeps track of the current key in the iterator leading down to the top node in the stack
+class IteratorKey {
 public:
-	//! Push byte into current key
-	void Push(const uint8_t key);
-	//! Pops n elements from the key
-	void Pop(const idx_t n);
+	//! Pushes a byte into the current key
+	inline void Push(const uint8_t key_byte) {
+		key_bytes.push_back(key_byte);
+	}
+	//! Pops n bytes from the current key
+	inline void Pop(const idx_t n) {
+		key_bytes.resize(key_bytes.size() - n);
+	}
 
 	//! Subscript operator
-	uint8_t &operator[](idx_t idx);
+	inline uint8_t &operator[](idx_t idx) {
+		D_ASSERT(idx < key_bytes.size());
+		return key_bytes[idx];
+	}
 	//! Greater than operator
 	bool operator>(const ARTKey &k) const;
 	//! Greater than or equal to operator
@@ -42,37 +48,35 @@ public:
 	bool operator==(const ARTKey &k) const;
 
 private:
-	//! The current key position
-	idx_t cur_key_pos = 0;
-	//! The current key corresponding to the current leaf
-	vector<uint8_t> key;
+	vector<uint8_t> key_bytes;
 };
 
 class Iterator {
 public:
-	//! All information about the current key
-	IteratorCurrentKey cur_key;
+	//! Holds the current key leading down to the top node on the stack
+	IteratorKey current_key;
 	//! Pointer to the ART
-	ART *art = nullptr;
+	optional_ptr<ART> art = nullptr;
 
-	//! Scan the tree
-	bool Scan(const ARTKey &key, const idx_t &max_count, vector<row_t> &result_ids, const bool &is_inclusive);
-	//! Finds the minimum value of the tree
+	//! Scans the tree, starting at the current top node on the stack, and ending at upper_bound.
+	//! If upper_bound is the empty ARTKey, than there is no upper bound
+	bool Scan(const ARTKey &upper_bound, const idx_t max_count, vector<row_t> &result_ids, const bool equal);
+	//! Finds the minimum (leaf) of the current subtree
 	void FindMinimum(Node &node);
-	//! Goes to the lower bound of the tree
-	bool LowerBound(Node node, const ARTKey &key, const bool &is_inclusive);
+	//! Finds the lower bound of the ART and adds the nodes to the stack. Returns false, if the lower
+	//! bound exceeds the maximum value of the ART
+	bool LowerBound(Node &node, const ARTKey &key, const bool equal, idx_t depth);
 
 private:
-	//! Stack of iterator entries
+	//! Stack of nodes from the root to the currently active node
 	stack<IteratorEntry> nodes;
-	//! Last visited leaf
-	Leaf *last_leaf = nullptr;
+	//! Last visited leaf node
+	Node last_leaf = Node();
 
-	//! Go to the next node
+	//! Goes to the next leaf in the ART and sets it as last_leaf,
+	//! returns false if there is no next leaf
 	bool Next();
-	//! Push part of the key to the current key
-	void PushKey(const Node &node, const uint8_t byte);
-	//! Pop node from the stack of iterator entries
+	//! Pop the top node from the stack of iterator entries and adjust the current key
 	void PopNode();
 };
 } // namespace duckdb