Add support for GROUP BY with cs_grouped_value_v1

This change adds support for decrypting encrypted columns included in the
`GROUP BY` clause by using a new aggregate function, `cs_grouped_value_v1`.

How it works:
- An ORE term (either in an ORE or SteVec index) can be used in `GROUP BY`
- `cs_grouped_value_v1` can be used in the `SELECT` target list to return a
    single source ciphertext for each group
- the ORE index is used for the equality check needed for grouping
- `cs_grouped_value_v1` allows for using the source ciphertext in the `SELECT`
   target list (since `SELECT`ed items must either use an aggregrate function or
   appear in the `GROUP BY`)
- note that including the source ciphertext in the `GROUP BY` statement wouldn't
  work because source ciphertexts are non-deterministic and don't support
  comparison operations (that's what ORE indexes are for)

Author: CDThomas

README.md

@@ -259,6 +259,16 @@ And is the EQL equivalent of the following plaintext query.
 SELECT id FROM examples ORDER BY field DESC;
 ```
 
+**Grouping example:**
+
+ORE indexes can be used along with the `cs_grouped_value_v1` aggregate function to group by an encrypted column:
+
+```
+SELECT cs_grouped_value_v1(encrypted_field) COUNT(*)
+  FROM users
+  GROUP BY cs_ore_64_8_v1(encrypted_field)
+```
+
 ## Querying JSONB data with EQL
 
 ### `cs_ste_term_v1(val JSONB, epath TEXT)`
@@ -354,7 +364,6 @@ Which is the equivalent to the following SQL query:
 SELECT attrs->'login_count' FROM users;
 ```
 
-
 ### Extraction (in WHERE, ORDER BY)
 
 Select rows that match a field in a JSONB object:
@@ -366,7 +375,20 @@ SELECT * FROM users WHERE cs_ste_term_v1(attrs, 'DQ1rbhWJXmmqi/+niUG6qw') > 'QAJ
 Which is the equivalent to the following SQL query:
 
 ```sql
-SELECT * FROM users WHERE attrs->'login_count' > 10; 
+SELECT * FROM users WHERE attrs->'login_count' > 10;
+```
+
+### Grouping
+
+`cs_ste_vec_term_v1` can be used along with the `cs_grouped_value_v1` aggregate function to group by a field in an encrypted JSONB column:
+
+```
+-- $1 here is a param that containts the EQL payload for an ejson path.
+-- Example EQL payload for the path `$.field_one`:
+--  '{"k": "pt", "p": "$.field_one", "q": "ejson_path", "i": {"t": "users", "c": "attrs"}, "v": 1}'
+SELECT cs_grouped_value_v1(cs_ste_vec_value_v1(attrs), $1) COUNT(*)
+  FROM users
+  GROUP BY cs_ste_vec_term_v1(attrs, $1);
 ```
 
 ## Managing indexes with EQL

sql/010-core.sql

@@ -220,3 +220,17 @@ CREATE FUNCTION cs_ore_64_8_v1(col jsonb)
 BEGIN ATOMIC
 	RETURN cs_ore_64_8_v1_v0_0(col);
 END;
+
+DROP FUNCTION IF EXISTS _cs_first_grouped_value(jsonb, jsonb);
+
+CREATE FUNCTION _cs_first_grouped_value(jsonb, jsonb)
+RETURNS jsonb AS $$
+  SELECT COALESCE($1, $2);
+$$ LANGUAGE sql IMMUTABLE;
+
+DROP AGGREGATE IF EXISTS cs_grouped_value_v1(jsonb);
+
+CREATE AGGREGATE cs_grouped_value_v1(jsonb) (
+  SFUNC = _cs_first_grouped_value,
+  STYPE = jsonb
+);