big docs update primarily SQL (#6569)

This commit adds SQL to the mdbook docs and makes a few other changes.

The pipe form of "from" has been unified with SQL from and updated
with a new style that better works with the left sidebar.  Here the
main topic of an md file is a single # at the top and each section
begins with ##.  We should do the rest of the docs in this style.
The SQL docs follow this style.

We also removed some trailing whitespace in a few places.

Author: mccanne

book/src/SUMMARY.md

@@ -102,20 +102,18 @@
         - [unnest](super-sql/operators/unnest.md)
         - [values](super-sql/operators/values.md)
         - [where](super-sql/operators/where.md)
-    - [SQL Clauses](super-sql/sql/intro.md)
-        - [FROM](super-sql/sql/from.md)
+    - [SQL](super-sql/sql/intro.md)
         - [SELECT](super-sql/sql/select.md)
+            - [FROM](super-sql/sql/from.md)
             - [WHERE](super-sql/sql/where.md)
             - [GROUP BY](super-sql/sql/group-by.md)
             - [HAVING](super-sql/sql/having.md)
-            - [FILTER](super-sql/sql/filter.md)
         - [VALUES](super-sql/sql/values.md)
-        - [ORDER](super-sql/sql/order.md)
+        - [ORDER BY](super-sql/sql/order-by.md)
         - [LIMIT](super-sql/sql/limit.md)
-        - [JOIN](super-sql/sql/join.md)
         - [WITH](super-sql/sql/with.md)
-        - [UNION](super-sql/sql/union.md)
-        - [INTERSECT](super-sql/sql/intersect.md)
+        - [JOIN](super-sql/sql/join.md)
+        - [Set Operators](super-sql/sql/set-ops.md)
     - [Functions](super-sql/functions/intro.md)
         - [Generics](super-sql/functions/generics/intro.md)
             - [coalesce](super-sql/functions/generics/coalesce.md)

book/src/super-sql/aggregates/intro.md

@@ -15,11 +15,11 @@ with the particular function, and
 Aggregate functions may appear in
 * the [aggregate](../operators/aggregate.md) operator,
 * an aggregate [shortcut](../operators/intro.md#shortcuts), or
-* in [SQL operators](../sql/intro.md) when performing aggregations.
+* in [SQL expressions](../sql/intro.md) when performing aggregations.
 
 When aggregate functions appear in context of grouping
 (e.g., the `by` clause of an [aggregate](../operators/aggregate.md) operator or a
-[SQL operator](../sql/intro.md) with a [GROUP BY](../sql/group-by.md) clause),
+[SELECT](../sql/select.md) query with a [GROUP BY](../sql/group-by.md) clause),
 then the aggregate function produces one output value for each
 unique combination of grouping expressions.
 

book/src/super-sql/declarations/functions.md

@@ -140,7 +140,7 @@ fn stats(numbers): (
     | sort this
     | avg(this),min(this),max(this),mode:=collect(this)
     | mode:=mode[len(mode)/2]
-) 
+)
 values stats(a)
 # input
 {a:[3,1,2]}

book/src/super-sql/expressions/inputs.md

@@ -8,9 +8,10 @@ is always referenced as the special value `this`.
 
 In [relational scoping](../intro.md#relational-scoping), input data
 is referenced by specifying the columns of one or more tables.
-See the [SQL section](../sql/intro.md#input-references) for
-details on how columns are bound to [identifiers](../queries.md#identifiers), how table references
-are resolved, and how `this` behaves in a SQL expression.
+See the [SQL section](../sql/intro.md) for
+details on how columns are [bound](../sql/intro.md#relational-bindings)
+to [identifiers](../queries.md#identifiers), how table references
+are resolved, and how [`this`](../sql/intro.md#this) behaves in a SQL expression.
 
 The type of `this` may be any [type](../types/intro.md).
 When `this` is a [record](../types/record.md), references
@@ -29,12 +30,9 @@ tables or columns are referenced.
 In a SQL operator, if the input is not a record (i.e., not relational),
 then the input data can still be referred to as the value `this` and placed
 into an output relation using [SELECT](../sql/select.md).
-When referring to non-relational inputs with `*`, there are no columns and
-thus the select value is empty, i.e., the value `{}`.
-
-When non-record data is referenced in a SQL operator and the input
-schema is dynamic and unknown, runtime [errors](../types/error.md) like `error("missing")`
-will generally arise and be present in the output data.
+Otherwise, column references to non-record data in dynamic inputs
+generally cause runtime [errors](../types/error.md)
+like `error("missing")`.
 
 ### Examples
 

book/src/super-sql/expressions/intro.md

@@ -21,7 +21,7 @@ used by pipe operators.
 
 While SQL expressions and pipe expressions share an identical syntax,
 their semantics diverge in some key ways:
-* SQL expressions that reference `this` have [semantics](../sql/intro.md#accessing-this)
+* SQL expressions that reference `this` have [semantics](../sql/intro.md#this)
   that depend on the SQL clause that expression appears in,
 * relational tables and/or columns cannot be referenced using aliases in pipe scoping,
 * double-quoted string [literals](literals.md) may be used in pipe expressions but are interpreted
@@ -52,7 +52,7 @@ Operators include
       an array, set, record, [map](../types/map.md), string, or [bytes](../types/bytes.md),
   * [logic](logic.md) to combine predicates using Boolean logic, and
   * [slices](slices.md) to extract subsequences from arrays, sets, strings, and bytes.
-  
+
 ### Identifier Resolution
 
 An identifier that appears as an operand in an expression is resolved to

book/src/super-sql/expressions/subqueries.md

@@ -221,7 +221,7 @@ _Independent subqueries in SQL operators are supported while correlated subqueri
 let input = (values {x:1},{x:2},{x:3})
 select x
 from input
-where x >= (select avg(x) from input)  
+where x >= (select avg(x) from input)
 # input
 
 # expected output

book/src/super-sql/intro.md

@@ -20,27 +20,16 @@ and the SuperSQL compiler often optimizes a query into an implementation
 different from the [dataflow](https://en.wikipedia.org/wiki/Dataflow) implied by the pipeline to achieve the
 same semantics with better performance.
 
-While SuperSQL at its core is a pipe-oriented language, it is also
-[backward compatible](../intro.md#supersql) with relational SQL in that any
-arbitrarily complex SQL query may appear as a single pipe operator
-anywhere in a SuperSQL pipe query.
-
-In other words, a single pipe operator that happens to be a standalone SQL query
-is also a SuperSQL pipe query.
-For example, these are all valid SuperSQL queries:
-```
-SELECT 'hello, world'
-SELECT * FROM table
-SELECT * FROM f1.json JOIN f2.json ON f1.id=f2.id
-SELECT watchers FROM https://api.github.com/repos/brimdata/super
-```
-
-## Interactive UX
+## Friendly Syntax
 
-To support an interactive pattern of usage, SuperSQL includes
-[search](operators/search.md) syntax
-reminiscent of Web or email keyword search along with
-[_operator shortcuts_](operators/intro.md#shortcuts).
+In addition to its user-friendly pipe syntax,
+SuperSQL embraces two key design patterns that simplify
+query editing for interactive usage:
+* [shortcuts](operators/intro.md#shortcuts) that reduce
+typing overhead and provide a concise syntax for common query patterns, and
+* [search](operators/search.md)
+reminiscent of Web or email keyword search, which is otherwise hard
+to carry out with traditional SQL syntax.
 
 With shortcuts, verbose queries can be typed in a shorthand facilitating
 rapid data exploration.  For example, the query
@@ -49,7 +38,10 @@ SELECT count(), key
 FROM source
 GROUP BY key
 ```
-can be simplified as `from source | count() by key`.
+can be simplified to
+```
+from source | count() by key
+```
 
 With search, all of the string fields in a value can easily be searched for
 patterns, e.g., this query
@@ -60,6 +52,23 @@ from source
 searches for the strings "example.com" and "urgent" in all of the string values in
 the input and also includes a numeric comparison regarding the field `message_length`.
 
+## SQL Compatibility
+
+While SuperSQL at its core is a pipe-oriented language, it is also
+[backward compatible](sql/intro.md) with relational SQL in that any
+arbitrarily complex SQL query may appear as a single pipe operator
+anywhere in a SuperSQL pipe query.
+
+In other words, a single pipe operator that happens to be a standalone SQL query
+is also a SuperSQL pipe query.
+For example, these are all valid SuperSQL queries:
+```
+SELECT 'hello, world'
+SELECT * FROM table
+SELECT * FROM f1.json JOIN f2.json ON f1.id=f2.id
+SELECT watchers FROM https://api.github.com/repos/brimdata/super
+```
+
 ## Pipe Queries
 
 The entities that transform data within a SuperSQL pipeline are called
@@ -109,7 +118,7 @@ fork
 
 ## Pipe Sources
 
-Like SQL, input data for a query is typically sourced with the
+Like SQL, input data for a pipe query is typically sourced with the
 [from](operators/from.md) operator.
 
 When `from` is not present, the file arguments to the
@@ -331,12 +340,12 @@ The array subquery produces an array value so it is often desirable to
 [unnest](operators/unnest.md) this array with respect to the outer
 values as in
 ```
-from f1.json | unnest {outer:this,inner:[from f2.json | ...]} into ( <scope> )
+from f1.json | unnest {outer:this,inner:[from f2.json | ...]} into ( <query> )
 ```
-where `<scope>` can be an arbitrary pipe query that processes each
+where `<query>` is an arbitrary pipe query that processes each
 collection of unnested values separately as a unit for each outer value.
-The `into ( <scope> )` body is an optional component of `unnest`, and if absent,
-the unnested collection boundaries are ignored and all of the unnested data is output.
+The `into ( <query> )` body is an optional component of `unnest`, and if absent,
+the unnested collection boundaries are ignored and all of the unnested data is output as a combined sequence.
 
 With the `unnest` operator, we can now consider how a [correlated subquery](https://en.wikipedia.org/wiki/Correlated_subquery) from
 SQL can be implemented purely as a pipe query with pipe scoping.
@@ -363,7 +372,7 @@ giving the same result
 {s:21}
 ```
 
-## Strong Typing
+## Type Checking
 
 Data in SuperSQL is always strongly typed.