Updated README for sqlplannertest (#239)

Expanded README for sqlplannertest with more instructions on how to
write, run, and update tests.
Added a simple test for expressions.

Author: apavlo

optd-sqlplannertest/README.md

@@ -1,20 +1,54 @@
-# Usage
+# SQL Planner Tests
 
-## Update the test cases
+These test cases use the [sqlplannertest](https://crates.io/crates/sqlplannertest) crate to execute SQL queries and inspect their output.
+They do not check whether a plan is correct, and instead rely on a text-based diff of the query's output to determine whether something is different than the expected output.
 
-```shell
-cargo run -p optd-sqlplannertest --bin planner_test_apply
-# or, supply a list of directories to scan from
-cargo run -p optd-sqlplannertest --bin planner_test_apply -- subqueries
-```
 
-## Verify the test cases
+## Execute Test Cases
 
 ```shell
 cargo test -p optd-sqlplannertest
 # or use nextest
 cargo nextest run -p optd-sqlplannertest
 ```
+## Add New Test Case
+
+To add a SQL query tests, create a YAML file in a subdir in "tests".
+Each file can contain multiple tests that are executed in sequential order from top to bottom.
+
+```yaml
+- sql: |
+    CREATE TABLE xxx (a INTEGER, b INTEGER);
+    INSERT INTO xxx VALUES (0, 0), (1, 1), (2, 2);
+  tasks:
+    - execute
+  desc: Database Setup
+- sql: |
+    SELECT * FROM xxx WHERE a = 0;
+  tasks:
+    - execute
+    - explain:logical_optd,physical_optd
+  desc: Equality predicate
+```
+| Name       | Description                                                        |
+| ---------- | ------------------------------------------------------------------ |
+| `sql`      | List of SQL statements to execute separate by newlines             |
+| `tasks`    | How to execute the SQL statements. See [Tasks](#tasks) below       |
+| `desc`     | (Optional) Text description of what the test cases represents      |
+
+After adding the YAML file, you then need to use the update command to automatically create the matching SQL file that contains the expected output of the test cases.
+
+## Regenerate Test Case Output
+
+If you change the output of optd's `EXPLAIN` syntax, then you need to update all of the expected output files for each test cases.
+The following commands will automatically update all of them for you. You should try to avoid this doing this often since if you introduce a bug, all the outputs will get overwritten and the tests will report false negatives.
+
+```shell
+# Update all test cases
+cargo run -p optd-sqlplannertest --bin planner_test_apply
+# or, supply a list of directories to update
+cargo run -p optd-sqlplannertest --bin planner_test_apply -- subqueries
+```
 
 ## Tasks
 
@@ -24,19 +58,19 @@ The `explain` and `execute` task will be run with datafusion's logical optimizer
 
 #### Flags
 
-| Name           | Description                           |
-| -------------- | ------------------------------------- |
-| use_df_logical | Enable Datafusion's logical optimizer |
+| Name             | Description                           |
+| ---------------- | ------------------------------------- |
+| `use_df_logical` | Enable Datafusion's logical optimizer |
 
 ### Explain Task
 
 #### Flags
 
-| Name           | Description                                                        |
-| -------------- | ------------------------------------------------------------------ |
-| use_df_logical | Enable Datafusion's logical optimizer                              |
-| verbose        | Display estimated cost in physical plan                            |
-| logical_rules  | Only enable these logical rules (also disable heuristic optimizer) |
+| Name             | Description                                                        |
+| ---------------- | ------------------------------------------------------------------ |
+| `use_df_logical` | Enable Datafusion's logical optimizer                              |
+| `verbose`        | Display estimated cost in physical plan                            |
+| `logical_rules`  | Only enable these logical rules (also disable heuristic optimizer) |
 
 Currently we have the following options for the explain task:
 

optd-sqlplannertest/tests/expressions/redundant_exprs.planner.sql

@@ -0,0 +1,39 @@
+-- Setup Test Table
+CREATE TABLE xxx (a INTEGER, b INTEGER);
+INSERT INTO xxx VALUES (0, 0), (1, 1), (2, 2);
+SELECT * FROM xxx WHERE a = 0;
+
+/*
+3
+0 0
+*/
+
+-- (no id or description)
+SELECT * FROM xxx WHERE a + 0 = b + 0;
+
+/*
+0 0
+1 1
+2 2
+
+LogicalProjection { exprs: [ #0, #1 ] }
+└── LogicalFilter
+    ├── cond:Eq
+    │   ├── Add
+    │   │   ├── Cast { cast_to: Int64, child: #0 }
+    │   │   └── 0(i64)
+    │   └── Add
+    │       ├── Cast { cast_to: Int64, child: #1 }
+    │       └── 0(i64)
+    └── LogicalScan { table: xxx }
+PhysicalFilter
+├── cond:Eq
+│   ├── Add
+│   │   ├── Cast { cast_to: Int64, child: #0 }
+│   │   └── 0(i64)
+│   └── Add
+│       ├── Cast { cast_to: Int64, child: #1 }
+│       └── 0(i64)
+└── PhysicalScan { table: xxx }
+*/
+

optd-sqlplannertest/tests/expressions/redundant_exprs.yml

@@ -0,0 +1,12 @@
+- sql: |
+    CREATE TABLE xxx (a INTEGER, b INTEGER);
+    INSERT INTO xxx VALUES (0, 0), (1, 1), (2, 2);
+    SELECT * FROM xxx WHERE a = 0;
+  tasks:
+    - execute
+  desc: Setup Test Table
+- sql: |
+    SELECT * FROM xxx WHERE a + 0 = b + 0;
+  tasks:
+    - execute
+    - explain:logical_optd,physical_optd