icydb-core 0.70.0

IcyDB — A type-safe, embedded ORM and schema system for the Internet Computer
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99

//! Module: db::executor::route::pushdown
//! Responsibility: secondary-index ORDER BY pushdown feasibility routing.
//! Does not own: logical ORDER BY validation semantics.
//! Boundary: route-owned capability assessment over validated logical+access plans.

use crate::{
    db::{
        access::PushdownApplicability,
        query::plan::{
            AccessPlannedQuery, LogicalPushdownEligibility, OrderSpec, ScalarPlan,
            secondary_order_contract_is_deterministic,
        },
    },
    model::entity::EntityModel,
};

fn validated_secondary_order_for_contract<'a>(
    model: &EntityModel,
    logical: &'a ScalarPlan,
    logical_pushdown_eligibility: LogicalPushdownEligibility,
) -> Option<&'a OrderSpec> {
    (secondary_order_contract_active(logical_pushdown_eligibility)
        && secondary_order_contract_is_deterministic(model, logical))
    .then_some(())?;

    logical.order.as_ref()
}

/// Derive route pushdown applicability from planner-owned logical eligibility and
/// route-owned access capabilities. Route must not re-derive logical shape policy.
pub(in crate::db) fn derive_secondary_pushdown_applicability_from_contract(
    model: &EntityModel,
    plan: &AccessPlannedQuery,
    logical_pushdown_eligibility: LogicalPushdownEligibility,
) -> PushdownApplicability {
    let Some(order) = validated_secondary_order_for_contract(
        model,
        plan.scalar_plan(),
        logical_pushdown_eligibility,
    ) else {
        return PushdownApplicability::NotApplicable;
    };

    let access_class = plan.access_strategy().class();

    access_class.secondary_order_pushdown_applicability(model, order)
}

/// Return whether planner logical pushdown eligibility allows route-level
/// secondary-order contracts to remain active.
pub(in crate::db::executor) const fn secondary_order_contract_active(
    logical_pushdown_eligibility: LogicalPushdownEligibility,
) -> bool {
    logical_pushdown_eligibility.secondary_order_allowed()
        && !logical_pushdown_eligibility.requires_full_materialization()
}

/// Return whether access traversal already satisfies the logical `ORDER BY`
/// contract under planner-owned pushdown eligibility decisions.
pub(in crate::db::executor) fn access_order_satisfied_by_route_contract_for_model(
    model: &EntityModel,
    plan: &AccessPlannedQuery,
) -> bool {
    let logical = plan.scalar_plan();
    let Some(order) = logical.order.as_ref() else {
        return false;
    };
    let access_class = plan.access_strategy().class();
    let logical_pushdown_eligibility = plan
        .planner_route_profile(model)
        .logical_pushdown_eligibility();
    let index_prefix_details = access_class.single_path_index_prefix_details();
    let index_range_details = access_class.single_path_index_range_details();
    let has_index_path = index_prefix_details.is_some() || index_range_details.is_some();
    let has_order_fields = !order.fields.is_empty();
    // `ORDER BY primary_key` is satisfied by access shapes whose final stream
    // order is already primary-key ordered. Secondary index paths stay ordered,
    // but that order is owned by the index key, so they must not claim PK-order
    // satisfaction merely because they are monotonic.
    let primary_key_order_satisfied = order.is_primary_key_only(model.primary_key.name)
        && access_class.ordered()
        && !has_index_path;
    let secondary_contract_active = secondary_order_contract_active(logical_pushdown_eligibility);
    let prefix_order_contract_safe =
        index_prefix_details.is_none() || access_class.prefix_order_contract_safe();
    let secondary_pushdown_eligible = derive_secondary_pushdown_applicability_from_contract(
        model,
        plan,
        logical_pushdown_eligibility,
    )
    .is_eligible();

    has_order_fields
        && (primary_key_order_satisfied
            || (secondary_contract_active
                && has_index_path
                && prefix_order_contract_safe
                && secondary_pushdown_eligible))
}