feat: add crypto_hash_agg function

Author: rustyconover

README.md

@@ -60,6 +60,35 @@ Computes a cryptographic hash of the input value using the specified algorithm.
 
 **Note:** Different data types with the same value will produce different hashes (e.g., `42::INTEGER` vs `42::BIGINT` vs `'42'::VARCHAR`).
 
+### crypto_hash_agg()
+
+**Syntax:**
+```sql
+crypto_hash_agg(algorithm, value ORDER BY sort_expression) → BLOB
+```
+
+An aggregate function that computes a cryptographic hash over multiple rows of data. This is useful for creating checksums of entire datasets, detecting changes in groups of records, or generating deterministic identifiers for sets of values.
+
+**Parameters:**
+- `algorithm` (VARCHAR): The hash algorithm name (same algorithms as `crypto_hash`)
+- `value`: The column/expression to hash (supports same data types as `crypto_hash`)
+- `ORDER BY`: **Required** - ensures deterministic ordering of values before hashing
+
+**Returns:** BLOB containing the raw hash bytes, or NULL for empty result sets
+
+**Important Notes:**
+- The `ORDER BY` clause is **mandatory** because hash aggregation is order-dependent
+- Values are hashed sequentially in the order specified by `ORDER BY`
+- For `VARCHAR` and `BLOB` types, each value's length is hashed before its content (same as list hashing)
+- The function produces the same hash as `crypto_hash()` would produce for an equivalent list
+- Empty result sets return `NULL`
+
+**Use Cases:**
+- **Dataset Checksums**: Verify data integrity across tables or partitions
+- **Change Detection**: Detect if any values in a group have changed
+- **Merkle-like Hashing**: Create hierarchical hashes of grouped data
+- **Deterministic IDs**: Generate stable identifiers for sets of values
+
 ### Supported Hash Algorithms
 
 | Algorithm | Output Size | Description |
@@ -127,6 +156,25 @@ SELECT octet_length(crypto_hash('sha2-256', 'test'));
 -- Handle NULL values
 SELECT crypto_hash('sha2-256', NULL::VARCHAR) IS NULL;
 -- true
+
+-- Aggregate hash over multiple rows (requires ORDER BY)
+SELECT lower(to_hex(crypto_hash_agg('sha2-256', email ORDER BY email)))
+FROM users;
+-- Produces a single hash representing all email values in order
+
+-- Aggregate hash with grouping
+SELECT
+  department,
+  lower(to_hex(crypto_hash_agg('sha2-256', employee_id ORDER BY employee_id))) as dept_hash
+FROM employees
+GROUP BY department;
+-- Produces a hash for each department's employee IDs
+
+-- Verify aggregate produces same hash as list
+SELECT crypto_hash_agg('sha2-256', value ORDER BY value) =
+       crypto_hash('sha2-256', [1, 2, 3, 4, 5]::INTEGER[])
+FROM (VALUES (1), (2), (3), (4), (5)) t(value);
+-- true (aggregate hash matches list hash)
 ```
 
 ## HMAC Functions
@@ -218,21 +266,57 @@ SELECT
 FROM users;
 ```
 
+### Dataset Integrity Verification
+```sql
+-- Create a checksum for an entire table partition
+SELECT
+  partition_date,
+  lower(to_hex(crypto_hash_agg('blake3', transaction_id ORDER BY transaction_id))) AS partition_checksum
+FROM transactions
+GROUP BY partition_date;
+
+-- Detect changes in a dataset by comparing checksums
+WITH current_hash AS (
+  SELECT crypto_hash_agg('sha2-256', data ORDER BY id) AS hash
+  FROM critical_table
+)
+SELECT hash = '\x<expected_hash_value>'::BLOB AS data_unchanged
+FROM current_hash;
+```
+
+### Merkle-Style Hierarchical Hashing
+```sql
+-- Create hierarchical hashes for efficient change detection
+-- Level 1: Hash individual user transactions
+WITH user_hashes AS (
+  SELECT
+    user_id,
+    crypto_hash_agg('sha2-256', transaction_id ORDER BY timestamp) AS user_hash
+  FROM transactions
+  GROUP BY user_id
+)
+-- Level 2: Hash all user hashes to get global hash
+SELECT
+  lower(to_hex(crypto_hash_agg('sha2-256', user_hash ORDER BY user_id))) AS global_hash
+FROM user_hashes;
+```
+
 ## Important Notes
 
-1. **Output Format**: Both `crypto_hash()` and `crypto_hmac()` return raw binary data as `BLOB`. Use `to_hex()` to convert to hexadecimal strings, or `lower(to_hex(...))` for lowercase hex.
+1. **Output Format**: `crypto_hash()`, `crypto_hash_agg()`, and `crypto_hmac()` all return raw binary data as `BLOB`. Use `to_hex()` to convert to hexadecimal strings, or `lower(to_hex(...))` for lowercase hex.
 
 2. **Type Sensitivity**: The hash is computed on the binary representation of the data type. The same numeric value with different types will produce different hashes:
    ```sql
    SELECT crypto_hash('sha2-256', 42::INTEGER) != crypto_hash('sha2-256', 42::BIGINT);
    -- true (different hashes)
    ```
 
-3. **NULL Handling**: Both functions return `NULL` if the input value is `NULL`.
+3. **NULL Handling**: `crypto_hash()` and `crypto_hmac()` return `NULL` if the input value is `NULL`. `crypto_hash_agg()` returns `NULL` for empty result sets.
 
-4. **List Hashing with Length Encoding**:
-   - For fixed-length types (integers, floats, dates, etc.) in lists, only the raw binary data is hashed
-   - For variable-length types (`VARCHAR` and `BLOB`) in lists, each element is hashed as: `[8-byte length][content]`
+4. **List and Aggregate Hashing with Length Encoding**:
+   - Applies to both `crypto_hash()` when hashing lists and `crypto_hash_agg()` when aggregating values
+   - For fixed-length types (integers, floats, dates, etc.), only the raw binary data is hashed
+   - For variable-length types (`VARCHAR` and `BLOB`), each element is hashed as: `[8-byte length][content]`
    - The length is encoded as a 64-bit unsigned integer (uint64_t) in native byte order
    - This prevents length extension attacks where `['ab', 'c']` would otherwise hash the same as `['a', 'bc']`
    - Example:
@@ -245,6 +329,11 @@ FROM users;
      -- 9a8acca1b6c6c0befd3fbc756aed625da998c998f7252e738c4ef061906b9b21
 
      -- Different hashes prove length encoding prevents collisions
+
+     -- Same applies to aggregate function
+     SELECT lower(to_hex(crypto_hash_agg('sha2-256', data ORDER BY data)))
+     FROM (VALUES ('ab'), ('c')) t(data);
+     -- Produces different hash than ['a', 'bc']
      ```
 
 5. **Security Considerations**:
@@ -253,7 +342,23 @@ FROM users;
    - For HMAC operations, use a strong, randomly generated secret key
    - Blake3 HMAC requires exactly a 32-byte key
 
-6. **Algorithm Availability**: MD4 is deprecated and may be disabled in modern OpenSSL builds.
+6. **Aggregate Function Requirements**:
+   - `crypto_hash_agg()` **requires** an `ORDER BY` clause to ensure deterministic results
+   - Without `ORDER BY`, the function will raise an error
+   - The aggregate produces the same hash as `crypto_hash()` would for an equivalent ordered list
+   - Example:
+     ```sql
+     -- This works - produces same hash as list [1,2,3,4,5]
+     SELECT crypto_hash_agg('sha2-256', value ORDER BY value)
+     FROM (VALUES (5), (2), (1), (4), (3)) t(value);
+
+     -- This fails - ORDER BY is required
+     SELECT crypto_hash_agg('sha2-256', value)
+     FROM (VALUES (1), (2)) t(value);
+     -- Error: Hash aggregation requires a distinct total ordering
+     ```
+
+7. **Algorithm Availability**: MD4 is deprecated and may be disabled in modern OpenSSL builds.
 
 ## Comparison with Built-in DuckDB Functions