Update docs with recently added features

content/references/advanced/asof_join.md

@@ -12,14 +12,27 @@ Usage example:
 -- Example schema
 create table humidity(measure_time timestamp, value double);
 create table temperature(measure_time timestamp, value double);
+insert into humidity values ('2024-06-01 07:00', 40), ('2024-06-01 08:00', 50), ('2024-06-01 09:00', 55);
+insert into temperature values ('2024-06-01 07:30', 20), ('2024-06-01 08:45', 21);
 
 -- Get combined measurements, e.g., to calculate a "feels like" heat index
 select h.measure_time, t.measure_time, h.value as humidity, t.value as temperature
 from humidity h
 asof join temperature t
-on h.measure_time >= t.measure_time;
+on h.measure_time >= t.measure_time
+order by h.measure_time;
 ```
 
+```text
+    measure_time     |    measure_time     | humidity | temperature
+---------------------+---------------------+----------+-------------
+ 2024-06-01 08:00:00 | 2024-06-01 07:30:00 |       50 |          20
+ 2024-06-01 09:00:00 | 2024-06-01 08:45:00 |       55 |          21
+(2 rows)
+```
+
+The 07:00 humidity measurement has no earlier temperature reading, so it does not appear in the result.
+
 In this example, we get the latest temperature for a humidity measurement, even when the times do not line up precisely.
 Expressing this query in standard SQL is more involved and usually results in slower execution, see
 [Alternative Implementations](#alternative-implementations).
@@ -34,6 +47,41 @@ In contrast to regular joins, AsOf joins are asymmetric:
 AsOf joins produce *at most* one tuple on the left side with the matching tuple from the right.
 Tuples that do not find a matching value are filtered out.
 
+The following example groups matches with an additional equality condition.
+For each tree, it returns the latest soil moisture reading of the same tree at or before the time of the height measurement:
+
+```sql
+create table tree_heights(tree_id int, measured_at int, height_m numeric);
+create table soil_moisture(tree_id int, measured_at int, moisture int);
+insert into tree_heights values (1, 10, 4.2), (2, 10, 3.1), (1, 5, 4.0);
+insert into soil_moisture values (1, 1, 30), (1, 8, 35), (2, 3, 41), (2, 9, 44);
+
+select h.tree_id, h.measured_at, h.height_m, m.measured_at as moisture_at, m.moisture
+from tree_heights h
+asof join soil_moisture m
+  on h.tree_id = m.tree_id and h.measured_at >= m.measured_at
+order by h.tree_id, h.measured_at;
+```
+
+```text
+ tree_id | measured_at | height_m | moisture_at | moisture
+---------+-------------+----------+-------------+----------
+       1 |           5 | 4.000000 |           1 |       30
+       1 |          10 | 4.200000 |           8 |       35
+       2 |          10 | 3.100000 |           9 |       44
+(3 rows)
+```
+
+If several rows of the right side are equally close, CedarDB returns only one of them.
+
+The `on` condition must contain exactly one ordering comparison, optionally combined with equality conditions using `and`.
+
+{{< callout type="warning" >}}
+CedarDB only supports the inner `asof join`.
+The parser also accepts `asof left join`, `asof right join`, and `asof full join`, but these currently behave like an inner `asof join` and drop rows without a match.
+`asof join ... using (...)` without an ordering comparison behaves like a regular equi-join.
+{{< /callout >}}
+
 {{< callout type="info" >}}
 CedarDB currently does not use any indexes for AsOf joins.
 Support for index-supported AsOf joins is planned for a future CedarDB release.

content/references/advanced/benchmarking.md

@@ -9,13 +9,6 @@ For benchmarking purposes, we support several advanced settings in CedarDB's int
 ## Repetition of queries
 
 To validate performance, it is important to run queries multiple times.
-To repeat a query, you can either repeat the execution (`e`), the compilation (`c`), or both (`a`).
-To change the repetition mode, simply query this command.
-
-```text
-\set repeatmode 'a'
-```
-
 The number of repetitions can be set with the following command.
 
 ```text

content/references/advanced/createserver.md

@@ -6,6 +6,10 @@ linkTitle: "Create Server"
 Create server adds a new remote server to the database catalog.
 Those servers can then be used for remote tables (see [create table](/docs/references/objects/tables)).
 
+{{< callout type="info" >}}
+`CREATE SERVER` requires an enterprise license.
+{{< /callout >}}
+
 The following example defines a server that can later be referenced as `server_name`.
 
 ```sql
@@ -45,6 +49,55 @@ For example if you want to create a user for us-east-1 region, you can do the fo
   3. Click on the user and go to the security credentials tab
   4. Create a new access key, which looks similar to AKIA5CBDR…, and note down the secret that is shown
 
+## Managing servers
+
+`CREATE SERVER IF NOT EXISTS` skips the statement if a server with that name exists.
+
+The `pg_foreign_server` system table lists all servers. CedarDB masks the secret:
+
+```sql
+create server tree_archive foreign data wrapper s3 options (location 's3://tree-archive:eu-central-1', id 'AKIAEXAMPLE', secret 'example-secret');
+select srvname, srvowner::regrole, srvoptions from pg_foreign_server;
+```
+
+```text
+   srvname    | srvowner |                             srvoptions
+--------------+----------+---------------------------------------------------------------------
+ tree_archive | postgres | {location=s3://tree-archive:eu-central-1,id=AKIAEXAMPLE,secret=***}
+(1 row)
+```
+
+You can change the owner of a server and drop it:
+
+```sql
+-- Assumes a role named forester exists
+alter server tree_archive owner to forester;
+drop server tree_archive;
+```
+
+`DROP SERVER` supports `IF EXISTS` and `CASCADE`.
+
 ## Permissions
 
-To create a server, you need to have superuser or `createdb` permissions.
+Only superusers can create servers.
+
+The owner of a server can drop it and grant the `USAGE` privilege on it:
+
+```sql
+grant usage on foreign server tree_archive to forester;
+grant usage on foreign server tree_archive to forester with grant option;
+revoke usage on foreign server tree_archive from forester cascade;
+```
+
+CedarDB records the privileges and their grantor in `pg_foreign_server.srvacl`.
+A role without the grant option gets `ERROR: permission denied for remoteserver '<server>'` when it tries to grant `USAGE`.
+
+To create a table on a server, you need the `USAGE` privilege on it, directly or through a role you are a member of.
+The owner of the server has it by default, and superusers bypass the check.
+`USAGE` is only checked when you create a table: revoking it does not affect existing tables on the server.
+
+## PostgreSQL Differences
+
+* Only the foreign data wrappers `s3` and `gs` (see [Tables on Google Cloud Storage](../gs)) exist. `CREATE FOREIGN DATA WRAPPER` raises `CREATE FDW not implemented yet`.
+* `ALTER SERVER ... OPTIONS` raises `ALTER SERVER not implemented yet`. To change the options, drop and re-create the server.
+* `CREATE SERVER` requires superuser rights. PostgreSQL requires `USAGE` on the foreign data wrapper.

content/references/advanced/gs.md

@@ -14,6 +14,10 @@ For more technical details, you can also read up on our [blog](https://cedardb.c
 CedarDB still uses a regular (local) storage device for metadata and recently updated (hot) data.
 {{</callout>}}
 
+{{< callout type="info" >}}
+`CREATE SERVER` requires an enterprise license.
+{{< /callout >}}
+
 ## Creating a Table on Google Cloud Storage
 
 Before creating tables that work on remote data, you need to use the [CREATE SERVER](../../advanced/createserver/) statement to first define the location of the data (e.g., the bucket) and the credentials.

content/references/advanced/loadhistory.md

@@ -44,6 +44,24 @@ Setting this to `0` disables load history collection altogether.
 Setting `loadhistory.retention` specifies the number of measurements that are stored before they will be dropped. The default value for this setting is `8640`.
 For an interval of 10 seconds, this will retain values for 24 hours.
 
+Set both values at startup in the [configuration file or as environment variables](../../configuration), for example `LOADHISTORY_INTERVAL=5000`.
+In SQL, the settings appear as `debug.loadhistory.interval` and `debug.loadhistory.retention`:
+
+```sql
+select name, setting from pg_settings where name like 'debug.loadhistory%';
+```
+
+```text
+            name             | setting
+-----------------------------+---------
+ debug.loadhistory.interval  | 10000
+ debug.loadhistory.retention | 8640
+(2 rows)
+```
+
+Without an enterprise license, querying a `cedardb_*_load_history` table fails with `ERROR: Load history collection requires an enterprise license to be executed.`
+CedarDB only collects measurements if the license is active at startup, i.e., set in the configuration file or as the `LICENSE_KEY` environment variable.
+
 ## Metrics and Tables
 
 All `cedardb_*_load_history` tables have as their first column the `timestamp` of when the measurement was taken.

content/references/advanced/pgvector.md

@@ -121,13 +121,15 @@ select vector_cmp('[1,2,3]'::vector, '[0,1,2]'::vector);
 ```
 
 Since vectors support basic arithmetic and comparison, you can also use them
-with aggregation functions such as `sum`, `avg`, `min`, and `max`:
+with the aggregation functions `sum`, `min`, and `max`:
 
 ```sql
 create table my_vectors ( v vector not null );
-select sum(v), avg(v), min(v), max(v) from my_vectors;
+select sum(v), min(v), max(v) from my_vectors;
 ```
 
+`avg` is not supported for vectors.
+
 ## Vector Functions and Operators
 
 When working with vectors, it is very common to compare them according to
@@ -145,6 +147,11 @@ For compatibility with pgvector, the `inner_product` function returns the inner
 product of two vectors but the `<#>` operator returns the *negative* inner
 product.
 
+If the two vectors have different dimensions, CedarDB pads the smaller vector
+with zeros, as for arithmetic. For example,
+`l2_distance('[1,2]'::vector, '[1,2,3]'::vector)` returns `3`. The pgvector
+extension raises an error in this case.
+
 Here are some examples:
 
 ```sql

content/references/advanced/prepare.md

@@ -125,8 +125,38 @@ In many cases, CedarDB infers parameter types from the surrounding query, and an
 However, in some cases it is not possible to infer the data type, which results in an error:
 
 ```sql
-prepare echo as select $1;
+prepare isempty as select $1 is null;
 ERROR:  unable to infer the data type for parameter $1
 ```
 
 In such cases, you can explicitly cast the parameter to a type, e.g.: `$1::int`.
+If a parameter is only used as an output column, such as in `prepare echo as select $1;`, CedarDB uses the type `text`.
+
+You can list the prepared statements of your session in the `pg_prepared_statements` system view:
+
+```sql
+prepare add as select $1::int + $2::int as sum;
+select name, parameter_types, result_types from pg_prepared_statements where name <> '';
+```
+
+```text
+ name |  parameter_types  | result_types
+------+-------------------+--------------
+ add  | {integer,integer} | {integer}
+(1 row)
+```
+
+## Permissions
+
+`PREPARE` does not check any privileges.
+CedarDB checks the privileges of the prepared statement each time you run it with `EXECUTE`:
+
+```sql
+-- As a role without the SELECT privilege on trees
+prepare findtree as select * from trees where id = $1;
+-- PREPARE succeeds
+execute findtree(1);
+ERROR:  permission denied for table 'trees'
+```
+
+`DEALLOCATE` requires no privileges.

content/references/advanced/s3.md

@@ -14,6 +14,10 @@ For more technical details, you can also read up on our [blog](https://cedardb.c
 CedarDB still uses a regular (local) storage device for metadata and recently updated (hot) data.
 {{</callout>}}
 
+{{< callout type="info" >}}
+`CREATE SERVER` requires an enterprise license.
+{{< /callout >}}
+
 ## Creating a Table on S3
 
 Before creating tables that work on remote data, you need to use the [CREATE SERVER](../../advanced/createserver/) statement to first define the location of the data (e.g., the bucket) and the credentials.

content/references/configuration.md

@@ -65,7 +65,7 @@ You can also update the configuration file from a SQL session with the [`ALTER S
 statement, without editing the file by hand:
 
 ```sql
-ALTER SYSTEM SET buffersize = '8G';
+ALTER SYSTEM SET debug.buffersize = '8G';
 ```
 
 As with the config file, these changes only take effect after a restart.

content/references/datatypes/array.md

@@ -47,11 +47,3 @@ select a[1] as first from data;
 
 CedarDB supports arrays with a maximum of 4 GB of underlying data.
 For most data types, this limits array to about one billion elements.
-
-```sql
-select array_fill('x', array[1000000000]);
-```
-
-```text
-ERROR:   string length overflow
-```

content/references/datatypes/bit.md

@@ -28,3 +28,18 @@ select * from example;
  11001010111111101011101010111110
 (4 rows)
 ```
+
+## Operators
+
+| Operator | Description           | Example                 | Result |
+|----------|-----------------------|-------------------------|--------|
+| `\|\|`   | Concatenation         | `B'10' \|\| B'01'`      | `1001` |
+| `&`      | Bitwise AND           | `B'1010' & B'0110'`     | `0010` |
+| `\|`     | Bitwise OR            | `B'1010' \| B'0101'`    | `1111` |
+| `#`      | Bitwise XOR           | `B'1010' # B'0110'`     | `1100` |
+
+For functions on bit strings, such as `length`, `bit_count`, `get_bit`, and `set_bit`, see [bit string functions](/docs/references/functions/bitstring).
+
+## PostgreSQL Differences
+
+- The bitwise NOT operator `~` and the shift operators `<<` and `>>` are not supported for bit strings.

content/references/datatypes/boolean.md

@@ -57,7 +57,7 @@ This results in more subtle ternary truth tables for booleans:
 
 ```sql
 with bools(v) as (values (true), (null), (false))
-select a.v as a, b.v as b, a and b as and, a or b as or
+select a.v as a, b.v as b, a.v and b.v as "and", a.v or b.v as "or"
 from bools a, bools b;
 ```
 

content/references/datatypes/date.md

@@ -5,7 +5,7 @@ weight: 14
 ---
 
 Date is a day-accurate type without time of day references in ISO 8601 `YYYY-MM-DD` format.
-CedarDB also accepts [PostgreSQL notation](https://www.postgresql.org/docs/current/datatype-datetime.html#DATATYPE-DATETIME-DATE-TABLE).
+CedarDB also accepts the common PostgreSQL input formats, such as `January 8, 1999`, `1999-Jan-08`, `19990108`, and `J2451187`.
 
 ## Usage Example
 
@@ -39,15 +39,17 @@ Operations on dates are range checked, so that e.g., overflows will never cause
 ## Input
 
 In a session, you can change the `DateStyle` setting, which determines the parsing when entering ambiguous dates.
+The default is `ISO, YMD`.
+CedarDB accepts the field orders `DMY`, `MDY`, and `YMD`, optionally prefixed with `ISO` and a comma, e.g., `ISO, DMY`.
 
 ```sql
 -- The common "little-endian" date style
 set DateStyle = 'DMY';
-select '01/02/03';
+select date '01/02/03';
 ```
 
 ```text
-  ?column?  
+  ?column?
 ------------
  2003-02-01
 (1 row)
@@ -56,12 +58,17 @@ select '01/02/03';
 ```sql
 -- US "middle-endian" date style
 set DateStyle = 'MDY';
-select '01/02/03';
+select date '01/02/03';
 ```
 
 ```text
-  ?column?  
+  ?column?
 ------------
  2003-01-02
 (1 row)
 ```
+
+## PostgreSQL Differences
+
+- The special values `infinity` and `-infinity` are not supported.
+- CedarDB always prints dates in ISO format. The `DateStyle` output styles `SQL`, `Postgres`, and `German` are not supported.