ProvSQL C/C++ API
Adding support for provenance and uncertainty management to PostgreSQL databases
Loading...
Searching...
No Matches
Aggregation.h
Go to the documentation of this file.
1/**
2 * @file Aggregation.h
3 * @brief Typed aggregation value, operator, and aggregator abstractions.
4 *
5 * This header provides the type system used by ProvSQL's aggregate
6 * provenance evaluation:
7 *
8 * - @c ComparisonOperator: the six standard SQL comparison operators,
9 * used by @c gate_cmp gates in the circuit.
10 * - @c AggregationOperator: the SQL aggregation functions that ProvSQL
11 * tracks provenance for (COUNT, SUM, MIN, MAX, AVG, AND, OR…).
12 * - @c ValueType: the runtime type tag for aggregate values.
13 * - @c AggValue: a tagged union holding one aggregate value of any
14 * supported type, built on @c std::variant.
15 * - @c Aggregator: an abstract interface for stateful incremental
16 * accumulators, one per aggregation function/type combination.
17 *
18 * The free functions @c getAggregationOperator() and @c makeAggregator()
19 * map PostgreSQL OIDs and operator/type pairs to the corresponding C++
20 * objects.
21 */
22#ifndef AGGREGATION_H
23#define AGGREGATION_H
24
25extern "C" {
26#include "postgres.h"
27}
28#include "c_cpp_compatibility.h"
29
30#include <variant>
31#include <cmath>
32#include <string>
33#include <vector>
34#include <cassert>
35#include <memory>
36
37/**
38 * @brief SQL comparison operators used in @c gate_cmp circuit gates.
39 */
41 EQ, ///< Equal (=)
42 NE, ///< Not equal (<>)
43 LE, ///< Less than or equal (<=)
44 LT, ///< Less than (<)
45 GE, ///< Greater than or equal (>=)
46 GT ///< Greater than (>)
47};
48
49/**
50 * @brief SQL aggregation functions tracked by ProvSQL.
51 */
53 COUNT, ///< COUNT(*) or COUNT(expr) → integer
54 SUM, ///< SUM → integer or float
55 MIN, ///< MIN → input type
56 MAX, ///< MAX → input type
57 AVG, ///< AVG → float
58 AND, ///< Boolean AND aggregate
59 OR, ///< Boolean OR aggregate
60 CHOOSE, ///< Arbitrary selection (pick one element)
61 ARRAY_AGG, ///< Array aggregation
62 NONE, ///< No aggregation (returns NULL)
63};
64
65/**
66 * @brief Arithmetic operations carried by @c gate_arith circuit gates.
67 *
68 * The C++ mirror of the @c provsql_arith_op on-disk tag stored in the
69 * gate's @c info1 (see @c provsql_utils.h), decoupled from it so that
70 * the semiring interface -- which is where these reach a circuit
71 * evaluator -- stays free of the PostgreSQL headers, exactly as
72 * @c ComparisonOperator is decoupled from the comparison-operator OID.
73 * @c arithOpFromTag() performs the translation.
74 */
76 PLUS, ///< n-ary sum
77 TIMES, ///< n-ary product
78 MINUS, ///< binary difference
79 DIV, ///< binary quotient
80 INTDIV, ///< binary quotient truncated toward zero (integer division)
81 NEG, ///< unary negation
82 MAX, ///< n-ary maximum (order statistic)
83 MIN, ///< n-ary minimum (order statistic)
84 POW, ///< binary power
85 LN, ///< unary natural logarithm
86 EXP, ///< unary exponential
87 PERCENTILE, ///< continuous percentile over interleaved [indicator, value] wires
88 ROUND, ///< rounding, to a number of digits given by a second wire
89 FLOOR, ///< unary floor
90 CEIL, ///< unary ceiling
91 ABS, ///< unary absolute value
92 AS_FLOAT8, ///< unary: the value as double precision reads it
93 AS_FLOAT4 ///< unary: the value as real reads it
94};
95
96/**
97 * @brief Runtime type tag for aggregate values.
98 */
99enum class ValueType {
100 INT, ///< Signed 64-bit integer
101 FLOAT, ///< Double-precision float
102 BOOLEAN, ///< Boolean
103 STRING, ///< Text string
104 ARRAY_INT, ///< Array of integers
105 ARRAY_FLOAT, ///< Array of floats
106 ARRAY_BOOLEAN,///< Array of booleans
107 ARRAY_STRING, ///< Array of strings
108 NONE ///< No value (NULL)
109};
110
111/**
112 * @brief The order PostgreSQL gives numbers: for floats, NaN equals NaN and
113 * is greater than every other value (where IEEE comparisons are all
114 * false).
115 */
116template <class T> inline bool sql_less(T a, T b) { return a < b; }
117/** @brief @c sql_less for @c double, with PostgreSQL's place for NaN. */
118template <> inline bool sql_less<double>(double a, double b) {
119 if (std::isnan(b)) return !std::isnan(a);
120 if (std::isnan(a)) return false;
121 return a < b;
122}
123
124/**
125 * @brief A dynamically-typed aggregate value.
126 *
127 * Wraps a @c std::variant of all supported scalar and array types.
128 * The active alternative is identified by the @c ValueType tag returned
129 * by @c getType().
130 */
131struct AggValue {
132private:
133 ValueType t; ///< Active type tag
134
135public:
136 /** @brief The variant holding the actual value. */
137 std::variant<long, double, bool, std::string,
138 std::vector<long>, std::vector<double>, std::vector<bool>, std::vector<std::string> > v;
139
140 /** @brief Construct a NULL (NONE) value. */
142 }
143 /** @brief Construct an integer value. @param l Integer value. */
144 AggValue(long l) : t(ValueType::INT), v(l) {
145 }
146 /** @brief Construct a float value. @param d Float value. */
147 AggValue(double d) : t(ValueType::FLOAT), v(d) {
148 }
149 /** @brief Construct a boolean value. @param b Boolean value. */
150 AggValue(bool b) : t(ValueType::BOOLEAN), v(b) {
151 }
152 /** @brief Construct a string value. @param s String value. */
153 AggValue(std::string s) : t(ValueType::STRING), v(s) {
154 }
155 /** @brief Construct an integer-array value. @param vec Integer array. */
156 AggValue(std::vector<long> vec) : t(ValueType::ARRAY_INT), v(vec) {
157 }
158 /** @brief Construct a float-array value. @param vec Float array. */
159 AggValue(std::vector<double> vec) : t(ValueType::ARRAY_FLOAT), v(vec) {
160 }
161 /** @brief Construct a boolean-array value. @param vec Boolean array. */
162 AggValue(std::vector<bool> vec) : t(ValueType::ARRAY_BOOLEAN), v(vec) {
163 }
164 /** @brief Construct a string-array value. @param vec String array. */
165 AggValue(std::vector<std::string> vec) : t(ValueType::ARRAY_STRING), v(vec) {
166 }
167
168 /**
169 * @brief Return the runtime type tag of this value.
170 * @return The @c ValueType identifying the active alternative.
171 */
173 return t;
174 }
175};
176
177/**
178 * @brief Abstract interface for an incremental aggregate accumulator.
179 *
180 * Each concrete subclass implements one aggregation function for one
181 * input type (e.g., SUM over integers, MAX over floats). Instances are
182 * created by @c makeAggregator().
183 */
185 virtual ~Aggregator() = default;
186
187 /**
188 * @brief Incorporate one input value into the running aggregate.
189 * @param x Input value to add.
190 */
191 virtual void add(const AggValue& x) = 0;
192
193 /**
194 * @brief Return the final aggregate result.
195 * @return The accumulated aggregate as an @c AggValue.
196 */
197 virtual AggValue finalize() const = 0;
198
199 /**
200 * @brief Return the type of the input values accepted by @c add().
201 * @return The @c ValueType of values passed to @c add().
202 *
203 * Used (via the @c resultType() default) to report the aggregate's
204 * result type; see @c makeAggregator() for the operators actually built.
205 */
206 virtual ValueType inputType() const = 0;
207
208 /**
209 * @brief Return the type of the value returned by @c finalize().
210 *
211 * Defaults to @c inputType(); override when the result type differs
212 * (e.g., AVG returns FLOAT regardless of the input type).
213 * @return The @c ValueType of the value returned by @c finalize().
214 */
215 virtual ValueType resultType() const {
216 return inputType();
217 }
218};
219
220/**
221 * @brief Map a PostgreSQL aggregate function OID to an @c AggregationOperator.
222 *
223 * @param oid OID of the aggregate function (e.g. @c F_COUNT_ANY, @c F_SUM_INT4).
224 * @return The corresponding @c AggregationOperator.
225 */
227
228/**
229 * @brief Map a PostgreSQL comparison-operator OID to a @c ComparisonOperator.
230 *
231 * The OID is the one stored in @c gate_cmp's @c info1 field (the OID of
232 * one of the six standard comparators @c =, @c <>, @c <, @c <=, @c >,
233 * @c >=). The translation goes via @c get_opname() so it is operand-type
234 * agnostic.
235 *
236 * @param[in] op_oid Comparison-operator OID.
237 * @param[out] ok Set to @c true on a recognised comparator, @c false
238 * when @p op_oid does not resolve in @c pg_operator
239 * or its name is not one of the six standard ones.
240 * @return The matching @c ComparisonOperator on success; an
241 * unspecified value (currently @c EQ) when @p ok is @c false.
242 */
243ComparisonOperator cmpOpFromOid(Oid op_oid, bool &ok);
244
245/**
246 * @brief Map a @c gate_arith operator tag to an @c ArithmeticOperator.
247 *
248 * The tag is the @c provsql_arith_op value stored in @c gate_arith's
249 * @c info1 field.
250 *
251 * @param[in] tag The persisted operator tag.
252 * @param[out] ok Set to @c true on a recognised tag, @c false when
253 * @p tag is outside the enumeration (a circuit written
254 * by a newer version of the extension).
255 * @return The matching @c ArithmeticOperator on success; an
256 * unspecified value (currently @c PLUS) when @p ok is @c false.
257 */
258ArithmeticOperator arithOpFromTag(unsigned tag, bool &ok);
259
260/**
261 * @brief Create a concrete @c Aggregator for the given operator and value type.
262 *
263 * @param op The aggregation function to implement.
264 * @param t The type of input values that will be accumulated.
265 * @return A heap-allocated @c Aggregator, or @c nullptr if the combination
266 * is not supported.
267 */
268std::unique_ptr<Aggregator> makeAggregator(AggregationOperator op, ValueType t);
269
270#endif /* AGGREGATION_H */
ArithmeticOperator arithOpFromTag(unsigned tag, bool &ok)
Map a gate_arith operator tag to an ArithmeticOperator.
AggregationOperator
SQL aggregation functions tracked by ProvSQL.
Definition Aggregation.h:52
@ OR
Boolean OR aggregate.
Definition Aggregation.h:59
@ MAX
MAX → input type.
Definition Aggregation.h:56
@ COUNT
COUNT(*) or COUNT(expr) → integer.
Definition Aggregation.h:53
@ AND
Boolean AND aggregate.
Definition Aggregation.h:58
@ SUM
SUM → integer or float.
Definition Aggregation.h:54
@ ARRAY_AGG
Array aggregation.
Definition Aggregation.h:61
@ NONE
No aggregation (returns NULL).
Definition Aggregation.h:62
@ CHOOSE
Arbitrary selection (pick one element).
Definition Aggregation.h:60
@ AVG
AVG → float.
Definition Aggregation.h:57
ComparisonOperator
SQL comparison operators used in gate_cmp circuit gates.
Definition Aggregation.h:40
@ LT
Less than (<).
Definition Aggregation.h:44
@ GT
Greater than (>).
Definition Aggregation.h:46
@ LE
Less than or equal (<=).
Definition Aggregation.h:43
@ NE
Not equal (<>).
Definition Aggregation.h:42
@ GE
Greater than or equal (>=).
Definition Aggregation.h:45
ComparisonOperator cmpOpFromOid(Oid op_oid, bool &ok)
Map a PostgreSQL comparison-operator OID to a ComparisonOperator.
bool sql_less(T a, T b)
The order PostgreSQL gives numbers: for floats, NaN equals NaN and is greater than every other value ...
AggregationOperator getAggregationOperator(Oid oid)
Map a PostgreSQL aggregate function OID to an AggregationOperator.
bool sql_less< double >(double a, double b)
sql_less for double, with PostgreSQL's place for NaN.
std::unique_ptr< Aggregator > makeAggregator(AggregationOperator op, ValueType t)
Create a concrete Aggregator for the given operator and value type.
ValueType
Runtime type tag for aggregate values.
Definition Aggregation.h:99
@ ARRAY_INT
Array of integers.
@ ARRAY_BOOLEAN
Array of booleans.
@ INT
Signed 64-bit integer.
@ STRING
Text string.
@ ARRAY_FLOAT
Array of floats.
@ ARRAY_STRING
Array of strings.
@ BOOLEAN
Boolean.
@ FLOAT
Double-precision float.
ArithmeticOperator
Arithmetic operations carried by gate_arith circuit gates.
Definition Aggregation.h:75
@ POW
binary power
Definition Aggregation.h:84
@ DIV
binary quotient
Definition Aggregation.h:79
@ ROUND
rounding, to a number of digits given by a second wire
Definition Aggregation.h:88
@ PERCENTILE
continuous percentile over interleaved [indicator, value] wires
Definition Aggregation.h:87
@ FLOOR
unary floor
Definition Aggregation.h:89
@ CEIL
unary ceiling
Definition Aggregation.h:90
@ NEG
unary negation
Definition Aggregation.h:81
@ INTDIV
binary quotient truncated toward zero (integer division)
Definition Aggregation.h:80
@ ABS
unary absolute value
Definition Aggregation.h:91
@ EXP
unary exponential
Definition Aggregation.h:86
@ TIMES
n-ary product
Definition Aggregation.h:77
@ AS_FLOAT8
unary: the value as double precision reads it
Definition Aggregation.h:92
@ AS_FLOAT4
unary: the value as real reads it
Definition Aggregation.h:93
@ LN
unary natural logarithm
Definition Aggregation.h:85
@ MINUS
binary difference
Definition Aggregation.h:78
Fix macro conflicts between PostgreSQL headers and the C++ STL/Boost.
A dynamically-typed aggregate value.
AggValue(std::vector< bool > vec)
Construct a boolean-array value.
ValueType getType() const
Return the runtime type tag of this value.
AggValue(std::vector< long > vec)
Construct an integer-array value.
AggValue()
Construct a NULL (NONE) value.
AggValue(long l)
Construct an integer value.
ValueType t
Active type tag.
AggValue(std::vector< std::string > vec)
Construct a string-array value.
AggValue(double d)
Construct a float value.
AggValue(std::string s)
Construct a string value.
AggValue(bool b)
Construct a boolean value.
std::variant< long, double, bool, std::string, std::vector< long >, std::vector< double >, std::vector< bool >, std::vector< std::string > > v
The variant holding the actual value.
AggValue(std::vector< double > vec)
Construct a float-array value.
Abstract interface for an incremental aggregate accumulator.
virtual void add(const AggValue &x)=0
Incorporate one input value into the running aggregate.
virtual AggValue finalize() const =0
Return the final aggregate result.
virtual ValueType inputType() const =0
Return the type of the input values accepted by add().
virtual ~Aggregator()=default
virtual ValueType resultType() const
Return the type of the value returned by finalize().
#define MIN(x, y)
Return the minimum of two values.
Definition subset.cpp:98