Skip to main content

uqa_sql/params/
tensor.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Packed host tensors retain a validated dimension independently of their row count.
8
9use super::{vector_value, Produced, ProductionControl, ProductionVec, SQLError, SQLParam, Value};
10
11#[derive(Debug, Clone)]
12pub struct SQLTensor {
13    values: Vec<f32>,
14    dimensions: u32,
15}
16
17impl SQLTensor {
18    pub fn dimensions(&self) -> u32 {
19        self.dimensions
20    }
21
22    pub fn row_count(&self) -> usize {
23        self.values.len() / self.dimensions as usize
24    }
25
26    pub fn values(&self) -> &[f32] {
27        &self.values
28    }
29
30    /// Validate shape and finite float32 elements before retaining a copied row-major input. An empty tensor still has a positive declared dimension.
31    pub fn from_slice_with_control(
32        values: &[f32],
33        dimensions: u32,
34        control: &ProductionControl<'_>,
35    ) -> Result<Produced<Self>, SQLError> {
36        control.check()?;
37        Self::validate_dimension(dimensions)?;
38        if !values.len().is_multiple_of(dimensions as usize) {
39            return Err(SQLError::TypeMismatch(
40                "tensor element count must be a multiple of its dimension".into(),
41            ));
42        }
43        for value in values {
44            crate::expr::vector_element_with_control(&Value::Float(f64::from(*value)), control)?;
45        }
46        let mut output = ProductionVec::new(*control);
47        output.extend_from_slice(values)?;
48        let (values, memory) = output.finish()?.into_parts();
49        Ok(control.finish(Self { values, dimensions }, memory)?)
50    }
51
52    /// Observe a selected SQL tensor using the existing native numeric conversion, checking every row against its declared dimension under the caller's allowance.
53    pub fn from_value_with_control(
54        value: &Value,
55        dimensions: u32,
56        control: &ProductionControl<'_>,
57    ) -> Result<Produced<Self>, SQLError> {
58        control.check()?;
59        Self::validate_dimension(dimensions)?;
60        let rows = crate::expr::tensor_items(value)?;
61        let count = rows
62            .len()
63            .checked_mul(dimensions as usize)
64            .ok_or_else(|| SQLError::from(uqa_core::memory::MemoryError::SizeOverflow))?;
65        let mut output = ProductionVec::new(*control);
66        output.reserve(count)?;
67        for row in rows {
68            control.check()?;
69            let values = crate::expr::vector_items(row)?;
70            if values.len() != dimensions as usize {
71                return Err(SQLError::TypeMismatch(format!(
72                    "tensor row has {} elements, expected {dimensions}",
73                    values.len()
74                )));
75            }
76            for value in values {
77                output.push_copy(crate::expr::vector_element_with_control(value, control)?)?;
78            }
79        }
80        let (values, memory) = output.finish()?.into_parts();
81        Ok(control.finish(Self { values, dimensions }, memory)?)
82    }
83
84    pub fn copy_with_control(
85        &self,
86        control: &ProductionControl<'_>,
87    ) -> Result<Produced<Self>, SQLError> {
88        control.check()?;
89        let mut copy = ProductionVec::new(*control);
90        copy.extend_from_slice(&self.values)?;
91        let (values, memory) = copy.finish()?.into_parts();
92        Ok(control.finish(
93            Self {
94                values,
95                dimensions: self.dimensions,
96            },
97            memory,
98        )?)
99    }
100
101    pub(super) fn to_value_with_control(
102        &self,
103        control: &ProductionControl<'_>,
104    ) -> Result<Produced<Value>, SQLError> {
105        let mut output = ProductionVec::new(*control);
106        output.reserve(self.row_count())?;
107        for row in self.values.chunks_exact(self.dimensions as usize) {
108            output.push_produced(vector_value(row, control)?)?;
109        }
110        let (rows, memory) = output.finish()?.into_parts();
111        Ok(control.finish(Value::List(rows), memory)?)
112    }
113
114    fn validate_dimension(dimensions: u32) -> Result<(), SQLError> {
115        if dimensions == 0 {
116            Err(SQLError::TypeMismatch(
117                "tensor dimension must be a positive 32-bit integer".into(),
118            ))
119        } else {
120            Ok(())
121        }
122    }
123}
124
125impl SQLParam {
126    /// Construct a typed tensor from packed row-major floats, retaining its dimension even when no rows are present.
127    pub fn tensor_with_control(
128        values: &[f32],
129        dimensions: u32,
130        control: &ProductionControl<'_>,
131    ) -> Result<Produced<Self>, SQLError> {
132        let (tensor, memory) =
133            SQLTensor::from_slice_with_control(values, dimensions, control)?.into_parts();
134        Ok(control.finish(Self::TypedTensor(tensor), memory)?)
135    }
136}
137
138#[cfg(test)]
139mod tests;