be/src/exec/partitioner/partitioner.h

Source
// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License.  You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.  See the License for the
// specific language governing permissions and limitations
// under the License.

#pragma once

#include <algorithm>

#include "core/block/block.h"
#include "exprs/vexpr.h"
#include "exprs/vexpr_context.h"

namespace doris {

class PartitionerBase {
public:
    using HashValType = uint32_t;

    PartitionerBase(HashValType partition_count) : _partition_count(partition_count) {}
    virtual ~PartitionerBase() = default;

    virtual Status init(const std::vector<TExpr>& texprs) = 0;

    virtual Status prepare(RuntimeState* state, const RowDescriptor& row_desc) = 0;

    virtual Status open(RuntimeState* state) = 0;

    virtual Status close(RuntimeState* state) = 0;

    virtual Status do_partitioning(RuntimeState* state, Block* block) const = 0;

    virtual const std::vector<HashValType>& get_channel_ids() const = 0;

    virtual Status clone(RuntimeState* state, std::unique_ptr<PartitionerBase>& partitioner) = 0;

    // use _partition_count as invalid sentinel value. since modulo operation result is [0, partition_count-1]
    HashValType partition_count() const { return _partition_count; }
    // use a individual function to highlight its special meaning
    HashValType invalid_sentinel() const { return partition_count(); }

protected:
    const HashValType _partition_count;
};

class PartitionFunction {
public:
    using HashValType = PartitionerBase::HashValType;

    virtual ~PartitionFunction() = default;

    virtual Status init(const std::vector<TExpr>& texprs) = 0;

    virtual Status prepare(RuntimeState* state, const RowDescriptor& row_desc) = 0;

    virtual Status open(RuntimeState* state) = 0;

    virtual Status close(RuntimeState* state) = 0;

    virtual Status get_partitions(RuntimeState* state, Block* block, size_t partition_count,
                                  std::vector<HashValType>& partitions) const = 0;

    virtual HashValType partition_count() const = 0;

    virtual Status clone(RuntimeState* state,
                         std::unique_ptr<PartitionFunction>& function) const = 0;
};

enum class ShuffleHashMethod {
    CRC32,
    CRC32C,
};

template <typename ChannelIds>
class Crc32HashPartitioner : public PartitionerBase {
public:
    Crc32HashPartitioner(int partition_count) : PartitionerBase(partition_count) {}
    ~Crc32HashPartitioner() override = default;

    Status init(const std::vector<TExpr>& texprs) override {
        return VExpr::create_expr_trees(texprs, _partition_expr_ctxs);
    }

    Status prepare(RuntimeState* state, const RowDescriptor& row_desc) override {
        return VExpr::prepare(_partition_expr_ctxs, state, row_desc);
    }

    Status open(RuntimeState* state) override { return VExpr::open(_partition_expr_ctxs, state); }

    Status close(RuntimeState* state) override { return Status::OK(); }

    Status do_partitioning(RuntimeState* state, Block* block) const override;

    const std::vector<HashValType>& get_channel_ids() const override { return _hash_vals; }

    Status clone(RuntimeState* state, std::unique_ptr<PartitionerBase>& partitioner) override;

protected:
    Status _get_partition_column_result(Block* block, std::vector<int>& result) const {
        int counter = 0;
        for (auto ctx : _partition_expr_ctxs) {
            RETURN_IF_ERROR(ctx->execute(block, &result[counter++]));
        }
        return Status::OK();
    }

    Status _clone_expr_ctxs(RuntimeState* state, VExprContextSPtrs& new_partition_expr_ctxs) const {
        new_partition_expr_ctxs.resize(_partition_expr_ctxs.size());
        for (size_t i = 0; i < _partition_expr_ctxs.size(); i++) {
            RETURN_IF_ERROR(_partition_expr_ctxs[i]->clone(state, new_partition_expr_ctxs[i]));
        }
        return Status::OK();
    }

    virtual void _do_hash(const ColumnPtr& column, HashValType* __restrict result, int idx) const;
    virtual void _initialize_hash_vals(size_t rows) const {
        _hash_vals.resize(rows);
        std::ranges::fill(_hash_vals, 0);
    }

    VExprContextSPtrs _partition_expr_ctxs;
    mutable std::vector<HashValType> _hash_vals;
};

struct ShuffleChannelIds {
    using HashValType = PartitionerBase::HashValType;
    HashValType operator()(HashValType l, size_t r) { return l % r; }
};

struct SpillPartitionChannelIds {
    using HashValType = PartitionerBase::HashValType;
    // Default spill partition mapping used by level-0 partitioning:
    // rotate hash bits and apply modulo to get a channel id directly.
    HashValType operator()(HashValType l, size_t r) { return ((l >> 16) | (l << 16)) % r; }
};

struct SpillRePartitionChannelIds {
    using HashValType = PartitionerBase::HashValType;

    // Repartition mode: return the raw hash value without modulo.
    // The caller (SpillRepartitioner) will apply level-aware hash mixing and
    // final channel mapping, so repartition behavior can vary by level.
    HashValType operator()(HashValType l, size_t /*r*/) { return l; }
};

static inline PartitionerBase::HashValType crc32c_shuffle_mix(PartitionerBase::HashValType h) {
    // Step 1: fold high entropy into low bits
    h ^= h >> 16;
    // Step 2: odd multiplicative scramble (cheap avalanche)
    h *= 0xA5B35705U;
    // Step 3: final fold to break remaining linearity
    h ^= h >> 13;
    return h;
}

// use high 16 bits as channel id to avoid conflict with crc32c hash table
// shuffle hash function same with crc32c hash table(eg join hash table) will lead bad performance
// hash table offten use low 16 bits as bucket index, so we shift 16 bits to high bits to avoid conflict
struct ShiftChannelIds {
    using HashValType = PartitionerBase::HashValType;
    HashValType operator()(HashValType l, size_t r) { return crc32c_shuffle_mix(l) % r; }
};

class Crc32CHashPartitioner : public Crc32HashPartitioner<ShiftChannelIds> {
public:
    Crc32CHashPartitioner(int partition_count)
            : Crc32HashPartitioner<ShiftChannelIds>(partition_count) {}

    Status clone(RuntimeState* state, std::unique_ptr<PartitionerBase>& partitioner) override;

private:
    void _do_hash(const ColumnPtr& column, HashValType* __restrict result, int idx) const override;

    void _initialize_hash_vals(size_t rows) const override {
        _hash_vals.resize(rows);
        // use golden ratio to initialize hash values to avoid collision with hash table's hash function
        constexpr HashValType CRC32C_SHUFFLE_SEED = 0x9E3779B9U;
        std::ranges::fill(_hash_vals, CRC32C_SHUFFLE_SEED);
    }
};

/// Instantiated once in partitioner.cpp; suppresses per-TU implicit instantiation.
extern template class Crc32HashPartitioner<ShuffleChannelIds>;
extern template class Crc32HashPartitioner<SpillPartitionChannelIds>;
extern template class Crc32HashPartitioner<SpillRePartitionChannelIds>;

} // namespace doris

Coverage Report

Created: 2026-08-18 10:44