icydb-core 0.94.0

IcyDB — A schema-first typed query engine and persistence runtime for Internet Computer canisters
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
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

//! Module: query::plan::projection
//! Responsibility: planner-owned projection intent lowering into canonical semantic shape.
//! Does not own: expression evaluation or executor output materialization.
//! Boundary: converts logical query intent into `ProjectionSpec`.

use crate::{
    db::query::{
        builder::aggregate::AggregateExpr,
        plan::{
            FieldSlot, GroupAggregateSpec, LogicalPlan,
            expr::{
                Expr, FieldId, ProjectionField, ProjectionSelection, ProjectionSpec,
                collect_unique_direct_projection_slots, projection_field_direct_field_name,
            },
            semantics::group_aggregate_spec_expr,
        },
    },
    model::entity::EntityModel,
};

/// Lower one logical plan into the canonical planner-owned projection semantic shape.
#[must_use]
pub(crate) fn lower_projection_intent(
    model: &EntityModel,
    logical: &LogicalPlan,
    selection: &ProjectionSelection,
) -> ProjectionSpec {
    match logical {
        LogicalPlan::Scalar(_) => lower_scalar_projection(model, selection),
        LogicalPlan::Grouped(grouped) => match selection {
            ProjectionSelection::Exprs(fields) => ProjectionSpec::new(fields.clone()),
            ProjectionSelection::All | ProjectionSelection::Fields(_) => lower_grouped_projection(
                grouped.group.group_fields.as_slice(),
                grouped.group.aggregates.as_slice(),
            ),
        },
    }
}

/// Lower one already-validated global aggregate output field list into the
/// canonical planner-owned projection semantic shape.
#[must_use]
pub(crate) const fn lower_global_aggregate_projection(
    fields: Vec<ProjectionField>,
) -> ProjectionSpec {
    ProjectionSpec::new(fields)
}

/// Lower scalar plans to one explicit field projection per declared entity field.
fn lower_scalar_projection(model: &EntityModel, selection: &ProjectionSelection) -> ProjectionSpec {
    let fields = match selection {
        ProjectionSelection::All => model
            .fields
            .iter()
            .map(|field| direct_field_projection(FieldId::new(field.name)))
            .collect(),
        ProjectionSelection::Fields(field_ids) => field_ids
            .iter()
            .cloned()
            .map(direct_field_projection)
            .collect(),
        ProjectionSelection::Exprs(fields) => fields.clone(),
    };

    ProjectionSpec::new(fields)
}

/// Lower one logical plan into one direct slot projection layout when every
/// output remains a unique canonical field reference.
#[must_use]
pub(crate) fn lower_direct_projection_slots(
    model: &EntityModel,
    logical: &LogicalPlan,
    selection: &ProjectionSelection,
) -> Option<Vec<usize>> {
    match logical {
        LogicalPlan::Scalar(_) => match selection {
            ProjectionSelection::All => Some((0..model.fields.len()).collect()),
            ProjectionSelection::Fields(field_ids) => {
                collect_unique_direct_projection_slots(model, field_ids.iter().map(FieldId::as_str))
            }
            ProjectionSelection::Exprs(fields) => collect_unique_direct_projection_slots(
                model,
                fields
                    .iter()
                    .map(projection_field_direct_field_name)
                    .collect::<Option<Vec<_>>>()?,
            ),
        },
        LogicalPlan::Grouped(_) => None,
    }
}

/// Lower one logical plan into the identity projection used by hash/fingerprint
/// surfaces when a full schema model is not available at the call boundary.
#[must_use]
pub(crate) fn lower_projection_identity(logical: &LogicalPlan) -> ProjectionSpec {
    match logical {
        LogicalPlan::Scalar(_) => ProjectionSpec::new(vec![direct_field_projection(FieldId::new(
            "__icydb_scalar_projection_default_v1__",
        ))]),
        LogicalPlan::Grouped(grouped) => lower_grouped_projection(
            grouped.group.group_fields.as_slice(),
            grouped.group.aggregates.as_slice(),
        ),
    }
}

/// Lower grouped plans to one explicit projection of grouped keys followed by
/// grouped aggregates, preserving declaration order.
fn lower_grouped_projection(
    group_fields: &[FieldSlot],
    aggregates: &[GroupAggregateSpec],
) -> ProjectionSpec {
    let mut fields = Vec::with_capacity(group_fields.len().saturating_add(aggregates.len()));
    for group_field in group_fields {
        fields.push(direct_field_projection(FieldId::new(group_field.field())));
    }
    for aggregate in aggregates {
        fields.push(aggregate_projection(group_aggregate_spec_expr(aggregate)));
    }

    ProjectionSpec::new(fields)
}

// Build one direct-field projection node so scalar, grouped, and identity
// lowering keep the same projection-field shape in one place.
const fn direct_field_projection(field_id: FieldId) -> ProjectionField {
    ProjectionField::Scalar {
        expr: Expr::Field(field_id),
        alias: None,
    }
}

// Build one grouped aggregate projection node so grouped projection lowering
// does not restate the scalar aggregate projection envelope inline.
const fn aggregate_projection(aggregate_expr: AggregateExpr) -> ProjectionField {
    ProjectionField::Scalar {
        expr: Expr::Aggregate(aggregate_expr),
        alias: None,
    }
}