Add Configure KSQL to Syntax Guide, fix/clariy config examples

docs/examples.md

@@ -1,6 +1,6 @@
 # Examples
 
-| [Overview](/docs#ksql-documentation) |[Quick Start](/docs/quickstart#quick-start) | [Concepts](/docs/concepts.md#concepts) | [Syntax Reference](/docs/syntax-reference.md#syntax-reference) |[Demo](/ksql-clickstream-demo#clickstream-analysis) | Examples | [FAQ](/docs/faq.md#frequently-asked-questions)  | [Roadmap](/docs/roadmap.md#roadmap) | 
+| [Overview](/docs#ksql-documentation) |[Quick Start](/docs/quickstart#quick-start) | [Concepts](/docs/concepts.md#concepts) | [Syntax Reference](/docs/syntax-reference.md#syntax-reference) |[Demo](/ksql-clickstream-demo#clickstream-analysis) | Examples | [FAQ](/docs/faq.md#frequently-asked-questions)  | [Roadmap](/docs/roadmap.md#roadmap) |
 |---|----|-----|----|----|----|----|----|
 
 **Table of Contents**
@@ -252,30 +252,22 @@ CREATE STREAM pageviews_interest_contact AS \
 
 ## Configuring KSQL
 
-You can set config properties for KSQL and your queries with the SET statement.  This includes configuring settings
-relating to Kafka's Streams API as well as settings for Kafka's producer and consumer clients.
+Common configuration properties that you might want to change from their default values include:
 
-```sql
-SET '<property-name>'='<property-value>';
-```
-
-Both property name and property value should be enclosed in single quotes.
-A property that is set using the SET statement will remain in effect for the remainder of the KSQL CLI session
-until you issue another SET statement to change it.
-
-Here are some of the common config properties that you might want to change from their default values:
-
-- `auto.offset.reset`: The default value in KSQL is `latest` meaning all the Kafka topics will be read
-  from the current offset (aka latest available data). You can change it using the following statement:
+- [auto.offset.reset](https://kafka.apache.org/documentation/#newconsumerconfigs):
+  The default value in KSQL is `latest` meaning all the Kafka topics will be read from the current offset (aka latest
+  available data). You can change it using the following statement:
 
     ```sql
     SET 'auto.offset.reset'='earliest';
     ```
 
-- `commit.interval.ms`: The default value is `2000`. Here is an example to change the value to `5000`:
+- [commit.interval.ms](https://kafka.apache.org/documentation/#streamsconfigs):
+  The default value in KSQL is `2000`. Here is an example to change the value to `5000`:
 
     ```sql
     SET 'commit.interval.ms'='5000';
     ```
 
-- `cache.max.bytes.buffering`: The default value is `10485760` (10 MB);
+- [cache.max.bytes.buffering](https://kafka.apache.org/documentation/#streamsconfigs):
+  The default value in KSQL is `10000000` (~ 10 MB);

docs/syntax-reference.md

@@ -1,6 +1,6 @@
 # Syntax Reference
 
-| [Overview](/docs#ksql-documentation) |[Quick Start](/docs/quickstart#quick-start) | [Concepts](/docs/concepts.md#concepts) | Syntax Reference | [Demo](/ksql-clickstream-demo#clickstream-analysis) | [Examples](/docs/examples.md#examples) | [FAQ](/docs/faq.md#frequently-asked-questions)  | [Roadmap](/docs/roadmap.md#roadmap) |
+| [Overview](/docs#ksql-documentation) | [Quick Start](/docs/quickstart#quick-start) | [Concepts](/docs/concepts.md#concepts) | Syntax Reference | [Demo](/ksql-clickstream-demo#clickstream-analysis) | [Examples](/docs/examples.md#examples) | [FAQ](/docs/faq.md#frequently-asked-questions)  | [Roadmap](/docs/roadmap.md#roadmap) |
 |---|----|-----|----|----|----|----|----|
 
 
@@ -12,6 +12,7 @@ The KSQL CLI provides a terminal-based interactive shell for running queries.
 - [KSQL statements](#ksql-statements)
 - [Scalar functions](#scalar-functions)
 - [Aggregate functions](#aggregate-functions)
+- [Configuring KSQL](#configuring-ksql)
 
 
 # CLI-specific commands
@@ -428,6 +429,19 @@ SHOW QUERIES;
 List the running persistent queries.
 
 
+### SHOW PROPERTIES
+
+**Synopsis**
+
+```sql
+SHOW PROPERTIES;
+```
+
+**Description**
+
+List the [configuration settings](#configuring-ksql) that are currently in effect.
+
+
 ### TERMINATE
 
 **Synopsis**
@@ -477,3 +491,47 @@ Terminate a persistent query. Persistent queries run continuously until they are
 | MAX        | `MAX(col1)`               | Return the maximum value for a given column and window |
 | MIN        | `MIN(col1)`               | Return the minimum value for a given column and window |
 | SUM        | `SUM(col1)`               | Sums the column values                                 |
+
+
+# Configuring KSQL
+
+You can set configuration properties for KSQL and your queries with the SET statement.  This includes
+[settings for Kafka's Streams API](https://kafka.apache.org/documentation/#streamsconfigs)
+(e.g., `cache.max.bytes.buffering`) as well as
+settings for Kafka's [producer client](https://kafka.apache.org/documentation/#producerconfigs) and
+[consumer client](https://kafka.apache.org/documentation/#newconsumerconfigs) (e.g., `auto.offset.reset`).
+
+```sql
+SET '<property-name>'='<property-value>';
+```
+
+Examples:
+
+```
+ksql> SET 'auto.offset.reset'='earliest';
+ksql> SET 'commit.interval.ms'='5000';
+```
+
+Both property name and property value should be enclosed in single quotes.
+
+Once a property has been set, it will remain in effect for the remainder of the KSQL CLI session until you issue another
+SET statement to change it.
+
+You can also use a *properties file* instead of the SET statement.  The syntax of properties files follow Java
+conventions, which are slightly different to the syntax of the SET statement above.
+
+```bash
+# Show the example contents of a properties file
+$ cat ksql.properties
+auto.offset.reset=earliest
+
+# Start KSQL in standalone mode with the custom properties above
+$ ksql-cli local --properties-file ./ksql.properties
+
+# Start a KSQL server node (for client-server mode) with the custom properties above
+$ ksql-server-start --properties-file ./ksql.properties
+```
+
+Note: Be careful when you are using KSQL in Docker because the properties file must be available inside the Docker
+container.  If you don't want to customize your Docker setup so that it contains an appropriate properties file, you
+should not use a properties file but the SET statement.