Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

8.8 KB
Raw Blame
//! Stage five: finish a [`Plan`] over the rows (or bins) the server returned.
//!
//! Pure: rows in, result rows out. Joins the relations, applies the residual
//! filter, groups and aggregates or projects, drops repeats for `DISTINCT`,
//! then sorts. SQL semantics where SQL has an opinion (`NULL` compares
//! false, `COUNT(column)` skips empty cells, `SUM` of nothing is `NULL`, a
//! join on a `NULL` matches nothing); Macro's where SQL does not (`LIKE`
//! ignores case, empty cells sort last, select values sort in option order,
//! a multi-valued join column matches by membership).

mod aggregate;
mod join;
mod predicate;
mod sort;
#[cfg(test)]
mod test;

use std::collections::{HashMap, HashSet};

use chrono::{DateTime, Utc};
use models_databases::position::Position;
use models_databases::{DateRange, OptionId, RowId};
use serde::{Deserialize, Serialize};
use specta::Type;
use uuid::Uuid;

use crate::catalog::Catalog;
use crate::resolve::{AggregateFunction, OrderKey, SelectItem};
use crate::run::RunError;
use crate::split::{Plan, Shape};

/// A cell as fetched. An absent cell is `NULL`; an absent multi-valued cell
/// is the empty set.
#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
#[cfg_attr(feature = "openapi", schema(as = SqlCell))]
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Type)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(tag = "type", content = "value", rename_all = "camelCase")]
pub enum Cell {
    /// Text or link.
    Text(String),
    /// A number.
    Number(f64),
    /// A checkbox.
    Bool(bool),
    /// A date-time.
    Date(DateTime<Utc>),
    /// A span from one date-time to another.
    DateRange(DateRange),
    /// The selected option ids; one for single-select columns.
    Options(Vec<OptionId>),
    /// The referenced entity ids; one for single-valued columns.
    Entities(Vec<String>),
    /// A table row's own id, the `row_id` column.
    Row(RowId),
}

impl Cell {
    /// A multi-valued cell with nothing in it, which reads as `NULL`.
    pub fn is_empty(&self) -> bool {
        matches!(self, Cell::Options(ids) if ids.is_empty())
            || matches!(self, Cell::Entities(ids) if ids.is_empty())
    }
}

/// A cell in a form that hashes, so equal cells share one key. A number is
/// keyed by its bits, with `-0` read as `0`.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub(crate) enum CellKey {
    Text(String),
    Number(u64),
    Bool(bool),
    Date(DateTime<Utc>),
    DateRange(DateRange),
    Options(Vec<OptionId>),
    Entities(Vec<String>),
    Row(RowId),
}

impl From<&Cell> for CellKey {
    fn from(cell: &Cell) -> Self {
        match cell {
            Cell::Text(text) => CellKey::Text(text.clone()),
            Cell::Number(number) if *number == 0.0 => CellKey::Number(0.0_f64.to_bits()),
            Cell::Number(number) => CellKey::Number(number.to_bits()),
            Cell::Bool(checked) => CellKey::Bool(*checked),
            Cell::Date(date) => CellKey::Date(*date),
            Cell::DateRange(range) => CellKey::DateRange(*range),
            Cell::Options(ids) => CellKey::Options(ids.clone()),
            Cell::Entities(ids) => CellKey::Entities(ids.clone()),
            Cell::Row(id) => CellKey::Row(*id),
        }
    }
}

/// One fetched row: the entity id and the cells the plan asked for. After
/// a join, the cells of every matched relation under their keys, with the
/// `FROM` row's id.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Type)]
pub struct Row {
    /// The row entity id.
    pub id: RowId,
    /// The row's place in its table, a fractional index that sorts as text;
    /// `None` for rows that are not table rows, such as people.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub position: Option<Position>,
    /// Cells by column; a missing column is an empty cell.
    pub cells: HashMap<Uuid, Cell>,
}

/// One `groupSoup` bin: the grouped value and how many rows it holds.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Type)]
pub struct Bin {
    /// The group's value; `None` for rows with an empty cell.
    pub key: Option<Cell>,
    /// Rows in the group.
    #[specta(type = u32)]
    pub count: u64,
}

/// The result: one `Vec` per row, one `Option<Cell>` per select item, in
/// select-list order.
pub type Table = Vec<Vec<Option<Cell>>>;

/// Finish a plan from the rows fetched for each relation, `FROM` first.
/// For a row shape, the second value is the `FROM` row behind each result
/// row, in result order.
pub fn fold_relations(
    catalog: &Catalog,
    plan: &Plan,
    fetched: Vec<Vec<Row>>,
) -> (Table, Vec<RowId>) {
    fold_joined(catalog, plan, join::join(plan, fetched))
}

/// Finish a plan over rows that are already joined (or come from one
/// relation).
#[cfg(test)]
pub(crate) fn fold_rows(catalog: &Catalog, plan: &Plan, rows: Vec<Row>) -> Table {
    fold_joined(catalog, plan, rows).0
}

fn fold_joined(catalog: &Catalog, plan: &Plan, rows: Vec<Row>) -> (Table, Vec<RowId>) {
    let rows: Vec<Row> = match &plan.residual {
        Some(filter) => rows
            .into_iter()
            .filter(|row| predicate::holds(filter, row))
            .collect(),
        None => rows,
    };

    match &plan.shape {
        Shape::Rows(columns) => {
            let mut rows = rows;
            sort::rows(catalog, plan, columns, &mut rows);
            let projected = rows.into_iter().map(|row| {
                let cells: Vec<Option<Cell>> = columns
                    .iter()
                    .map(|column| row.cells.get(column).cloned())
                    .collect();
                (row.id, cells)
            });
            let (ids, table): (Vec<RowId>, Table) = if plan.distinct {
                window(plan, distinct(projected, |(_, cells)| cells)).unzip()
            } else {
                window(plan, projected).unzip()
            };
            (table, ids)
        }
        Shape::Aggregate { group_by, items } => {
            let mut groups = aggregate::groups(rows, *group_by, items);
            sort::groups(catalog, plan, &mut groups, *group_by, items);
            let groups = if plan.distinct {
                distinct(groups.into_iter(), |group| &group.cells).collect()
            } else {
                groups
            };
            (
                window(plan, groups.into_iter().map(|group| group.cells)).collect(),
                Vec::new(),
            )
        }
    }
}

/// `OFFSET` then `LIMIT`, after ordering.
fn window<Item>(plan: &Plan, rows: impl Iterator<Item = Item>) -> impl Iterator<Item = Item> {
    rows.skip(plan.offset.unwrap_or(0) as usize)
        .take(plan.limit.map_or(usize::MAX, |limit| limit as usize))
}

/// Keep the first of every set of equal result rows, in order.
fn distinct<Item>(
    rows: impl Iterator<Item = Item>,
    cells: impl Fn(&Item) -> &[Option<Cell>],
) -> impl Iterator<Item = Item> {
    let mut seen: HashSet<Vec<Option<CellKey>>> = HashSet::new();
    rows.filter(move |row| {
        seen.insert(
            cells(row)
                .iter()
                .map(|cell| cell.as_ref().map(CellKey::from))
                .collect(),
        )
    })
}

/// Finish a `GroupSoup` plan from its bins, which answer only a group
/// column and `COUNT(*)`.
pub fn fold_bins(catalog: &Catalog, plan: &Plan, bins: Vec<Bin>) -> Result<Table, RunError> {
    let Shape::Aggregate { group_by, items } = &plan.shape else {
        return Err(RunError::NotAnsweredByBins);
    };
    let mut groups: Vec<aggregate::Group> = bins
        .into_iter()
        .map(|bin| {
            let cells = items
                .iter()
                .map(|item| match item {
                    SelectItem::Column(_) => Ok(bin.key.clone()),
                    SelectItem::Aggregate {
                        function: AggregateFunction::Count,
                        column: None,
                    } => Ok(Some(Cell::Number(bin.count as f64))),
                    SelectItem::Aggregate { .. } => Err(RunError::NotAnsweredByBins),
                })
                .collect::<Result<_, _>>()?;
            Ok(aggregate::Group {
                key: bin.key,
                cells,
            })
        })
        .collect::<Result<_, RunError>>()?;
    sort::groups(catalog, plan, &mut groups, *group_by, items);
    Ok(window(plan, groups.into_iter().map(|group| group.cells)).collect())
}

/// Where an `ORDER BY` key lives in a group's output.
fn group_order_index(
    key: &OrderKey,
    group_by: Option<Uuid>,
    items: &[SelectItem],
) -> Option<usize> {
    match key {
        OrderKey::Item(index) => Some(*index),
        OrderKey::Column(column) => {
            debug_assert_eq!(
                Some(*column),
                group_by,
                "resolve allows only the group column"
            );
            items
                .iter()
                .position(|item| *item == SelectItem::Column(*column))
        }
    }
}