Text-to-SQL: Add more examples

Author: amotl

doc/query/nlsql/example-employee.md

@@ -0,0 +1,54 @@
+(nlsql-example-employee)=
+
+# NLSQL with employee data
+
+Let's use a single `employees` database table
+and populate it with a few records worth of data.
+
+:::{rubric} Provision
+:::
+
+Create table and insert data.
+
+```sql
+CREATE TABLE employees (id INT, name TEXT, department TEXT, hire_date TIMESTAMP); 
+
+INSERT INTO employees (id, name, department, hire_date) VALUES
+(1, 'Alice Johnson', 'Engineering', '2022-03-15'),
+(2, 'Bob Smith', 'Marketing', '2021-07-01'),
+(3, 'Carol Lee', 'Human Resources', '2020-11-23'),
+(4, 'David Brown', 'Finance', '2019-05-30'),
+(5, 'Eva Green', 'Engineering', '2023-01-10'),
+(6, 'Frank Miller', 'Sales', '2019-08-12'),
+(7, 'Grace Kim', 'Sales', '2021-02-18'),
+(8, 'Henry Davis', 'Sales', '2022-06-25'),
+(9, 'Isabella Martinez', 'Sales', '2020-12-05'),
+(10, 'Jack Wilson', 'Sales', '2023-09-14');
+```
+
+:::{rubric} Query
+:::
+
+Submit a typical query in human language.
+
+```shell
+ctk query nlsql "List all employees in the 'Sales' department hired after 2022."
+```
+
+:::{rubric} Response
+:::
+
+The model figures out the SQL statement, the engine runs it, and
+uses the model again to come back with an answer in human language:
+```text
+The employees in the Sales department hired after 2022 are Henry Davis and Jack Wilson.
+```
+
+The SQL statement was:
+```sql
+SELECT
+    name FROM employees
+WHERE
+    department = 'Sales' AND
+    hire_date > '2022-01-01';
+```

doc/query/nlsql/example-product.md

@@ -0,0 +1,206 @@
+(nlsql-example-product)=
+
+# NLSQL with product orders
+
+Let's use a basic products / orders / customers database.
+
+## Basic JOINs and filtering
+
+:::{rubric} Provision
+:::
+
+Create table and insert data.
+Populate the table using a few records worth of example data.
+
+```sql
+CREATE TABLE customers (customer_id INTEGER, name VARCHAR, city VARCHAR); 
+CREATE TABLE orders (order_id INTEGER, customer_id INTEGER, amount INTEGER);
+CREATE TABLE products (product_id INTEGER, name VARCHAR);
+CREATE TABLE order_items (order_id INTEGER, product_id INTEGER);
+
+-- customers
+INSERT INTO customers (customer_id, name, city) VALUES
+(1, 'Alice', 'Berlin'),
+(2, 'Bob', 'Munich'),
+(3, 'Charlie', 'Hamburg');
+
+-- products
+INSERT INTO products (product_id, name) VALUES
+(1, 'Laptop'),
+(2, 'Phone'),
+(3, 'Headphones');
+
+-- orders
+INSERT INTO orders (order_id, customer_id, amount) VALUES
+(101, 1, 1200),
+(102, 2, 800),
+(103, 1, 200),
+(104, 3, 150);
+
+-- order_items
+-- Alice bought Laptop, Bob bought Phone, Alice bought Headphones,
+-- Charlie bought Headphones, Charlie also bought Phone.
+INSERT INTO order_items (order_id, product_id) VALUES
+(101, 1),  
+(102, 2),
+(103, 3),
+(104, 3),
+(104, 2);
+```
+
+:::{rubric} Query
+:::
+
+Submit a typical query in human language.
+
+```shell
+ctk query nlsql "List all customers with orders over €500."
+```
+
+:::{rubric} Response
+:::
+
+The model figures out the SQL statement, the engine runs it, and
+uses the model again to come back with an answer in human language:
+
+> The query results show that the customers 'Alice' from Berlin
+> and 'Bob' from Munich have placed orders over €500.
+
+The SQL statement was:
+```sql
+SELECT customers.name, customers.city
+FROM customers JOIN orders ON customers.customer_id = orders.customer_id
+WHERE orders.amount > 500;
+```
+
+## Advanced JOINs and filtering
+
+:::{rubric} Provision
+:::
+
+Create table and insert data.
+Add a few customers in New York and others elsewhere.
+Synthesize orders with amounts both above and below the average.
+
+```sql
+CREATE TABLE customers (customer_id INTEGER, name VARCHAR, city VARCHAR); 
+CREATE TABLE orders (order_id INTEGER, customer_id INTEGER, amount INTEGER);
+CREATE TABLE products (product_id INTEGER, name VARCHAR);
+CREATE TABLE order_items (order_id INTEGER, product_id INTEGER);
+
+INSERT INTO customers (customer_id, name, city) VALUES
+(1, 'Alice Johnson', 'New York'),
+(2, 'Bob Smith', 'Los Angeles'),
+(3, 'Carol Lee', 'New York'),
+(4, 'David Brown', 'Chicago');
+
+INSERT INTO orders (order_id, customer_id, amount) VALUES
+(101, 1, 500),   -- NY, high
+(102, 1, 150),   -- NY, low
+(103, 2, 300),   -- non-NY
+(104, 3, 700),   -- NY, high
+(105, 4, 200);   -- non-NY
+
+INSERT INTO products (product_id, name) VALUES
+(1001, 'Laptop'),
+(1002, 'Phone'),
+(1003, 'Tablet'),
+(1004, 'Headphones');
+
+INSERT INTO order_items (order_id, product_id) VALUES
+(101, 1001),
+(101, 1004),
+(102, 1002),
+(103, 1003),
+(104, 1001),
+(104, 1002),
+(105, 1004);
+```
+
+:::{rubric} Query
+:::
+
+Submit a typical query in human language.
+
+```shell
+ctk query nlsql "Get the names of products that were ordered by customers in New York who spent more than the average amount."
+```
+
+:::{rubric} Response
+:::
+
+The model figures out the SQL statement, the engine runs it, and
+uses the model again to come back with a synthesized response
+based on the provided SQL query and its result:
+
+> The query identifies the top 10 product names ordered by customers in New York
+> who spent more than the average order amount.
+> The results show that "Laptop", "Phone", and "Headphones" were among the most
+> popular products purchased by New York customers with high spending.
+
+The SQL statement was:
+```sql
+SELECT
+    p.name FROM products AS p
+    JOIN order_items AS oi ON p.product_id = oi.product_id
+    JOIN orders AS o ON oi.order_id = o.order_id
+    JOIN customers AS c ON o.customer_id = c.customer_id
+WHERE
+    c.city = 'New York'
+ORDER BY
+    o.amount DESC LIMIT 10;
+```
+
+## JOINs and grouping
+
+:::{rubric} Provision
+:::
+
+```sql
+CREATE TABLE customers (customer_id INTEGER, name VARCHAR, city VARCHAR, email_address VARCHAR, gender_code VARCHAR); 
+CREATE TABLE orders (order_id INTEGER, customer_id INTEGER, amount INTEGER);
+CREATE TABLE products (product_id INTEGER, name VARCHAR, price NUMERIC(2), size VARCHAR);
+CREATE TABLE order_items (order_id INTEGER, product_id INTEGER);
+
+INSERT INTO customers (customer_id, name, city, email_address, gender_code) VALUES
+(1, 'Alice Johnson', 'New York', 'alice@example.com', 'F'),
+(2, 'Bob Smith', 'Los Angeles', 'bob@example.com', 'M'),
+(3, 'Carol Lee', 'Chicago', 'carol@example.com', 'F'),
+(4, 'David Brown', 'Houston', 'david@example.com', 'M'),
+(5, 'Eva Green', 'Phoenix', 'eva@example.com', 'F'),
+(6, 'Frank Miller', 'Miami', 'frank@example.com', 'M'),
+(7, 'Grace Kim', 'Seattle', 'grace@example.com', 'F'),
+(8, 'Henry Davis', 'Boston', 'henry@example.com', 'O'); -- least common gender
+
+INSERT INTO orders (order_id, customer_id, amount) VALUES
+(101, 1, 120),
+(102, 2, 200),
+(103, 3, 150),
+(104, 4, 300),
+(105, 6, 80);
+
+INSERT INTO products (product_id, name, price, size) VALUES
+(1001, 'T-Shirt', 20, 'M'),
+(1002, 'Jeans', 50, 'L'),
+(1003, 'Jacket', 80, 'XL'),
+(1004, 'Sneakers', 60, '42'),
+(1005, 'Hat', 15, 'S');
+
+INSERT INTO order_items (order_id, product_id) VALUES
+(101, 1001),
+(101, 1005),
+(102, 1002),
+(103, 1003),
+(104, 1004),
+(105, 1001);
+```
+
+:::{rubric} Q & A
+:::
+
+- Q: What are the email address and town of the customers who are of the least common gender?
+  SQL: `SELECT email_address, city FROM customers GROUP BY gender_code ORDER BY count(*) ASC LIMIT 1`
+- Q: What are the product price and the product size of the products whose price is above average?
+  SQL: `SELECT products.price, products.size FROM products WHERE products.price > (SELECT AVG(price) FROM products)`
+- Q: Which customers did not make any orders?
+  SQL: `SELECT c.name FROM customers AS c LEFT JOIN orders AS o ON c.customer_id = o.customer_id WHERE o.order_id IS NULL;`

doc/query/nlsql/example-sensor.md

@@ -1,12 +1,14 @@
 (nlsql-example-sensor)=
 
-# NLSQL sensor data example
+# NLSQL with sensor data
+
+Let's use a single `time_series_data` database table
+and populate it with a few records worth of time series data.
 
 :::{rubric} Provision
 :::
 
-Add data to the database. Let's use a very basic table schema and
-just a few records worth of time series data.
+Create table and insert data.
 
 ```sql
 CREATE TABLE IF NOT EXISTS time_series_data (
@@ -47,14 +49,14 @@ ctk query nlsql "What is the average value for sensor 1?"
 :::
 
 The model figures out the SQL statement, the engine runs it, and
-uses the model again to come back with an answer in human language.
-
-```sql
-SQL:    SELECT AVG(value) FROM time_series_data WHERE sensor_id = 1;
+uses the model again to come back with an answer in human language:
+```text
+The average value for sensor 1 is approximately 17.03.
 ```
 
-```text
-Answer: The average value for sensor 1 is approximately 17.03.
+The SQL statement was:
+```sql
+SELECT AVG(value) FROM time_series_data WHERE sensor_id = 1;
 ```
 
 :::{rubric} Multiple languages

doc/query/nlsql/example-weather.md

@@ -0,0 +1,53 @@
+(nlsql-example-weather)=
+
+# NLSQL with weather data
+
+Let's use a basic database including weather observations.
+
+:::{rubric} Provision
+:::
+
+Create table and insert data.
+
+```sql
+CREATE TABLE weather (zip_code VARCHAR, city VARCHAR, temperature_fahrenheit INTEGER, mean_visibility_miles INTEGER);
+
+INSERT INTO weather (zip_code, city, temperature_fahrenheit, mean_visibility_miles) VALUES
+('10001', 'New York', 85, 8),       -- visibility < 10
+('90001', 'Los Angeles', 95, 12),   -- temp > 90
+('60601', 'Chicago', 88, 9),        -- visibility < 10
+('73301', 'Austin', 102, 15),       -- temp > 90
+('94102', 'San Francisco', 65, 7),  -- visibility < 10
+('85001', 'Phoenix', 110, 20),      -- temp > 90
+('33101', 'Miami', 91, 11);         -- temp > 90
+```
+
+:::{rubric} Query
+:::
+
+Submit typical queries in human language.
+
+```shell
+ctk query nlsql "Find the zip code where the mean visibility is lower than 10."
+ctk query nlsql "Find all cities with temperatures above 90°F."
+```
+
+:::{rubric} Response
+:::
+
+The model figures out the SQL statements, the engine runs it, and
+uses the model again to come back with answers in human language:
+```text
+The zip codes with a mean visibility of less than 10 miles are 94102, 10001, and 60601.
+```
+```text
+The cities with temperatures above 90°F are Miami, Austin, Phoenix, and Los Angeles.
+```
+
+The SQL statements were:
+```sql
+SELECT zip_code FROM weather WHERE mean_visibility_miles < 10;
+```
+```sql
+SELECT city FROM weather WHERE temperature_fahrenheit > 90;
+```

doc/query/nlsql/index.md

@@ -398,7 +398,10 @@ information from a single table.
 :maxdepth: 1
 :hidden:
 
+Employee data example <example-employee>
+Product orders example <example-product>
 Sensor data example <example-sensor>
+Weather data example <example-weather>
 ```