Merge pull request #188229 from jonels-msft/hsc-quick-gary

Suggestions from Gary for our Hyperscale quickstart

Author: LJSpiller

articles/postgresql/hyperscale/quickstart-connect-psql.md

@@ -60,6 +60,23 @@ When you create your Hyperscale (Citus) server group, a default database named *
    citus=>
    ```
 
+4. Run a test query. Copy the following command and paste it into the psql
+   prompt, then press enter to run:
+
+   ```sql
+   SHOW server_version;
+   ```
+
+   You should see a result matching the PostgreSQL version you selected
+   during server group creation. For instance:
+
+   ```
+    server_version
+   ----------------
+    13.5
+   (1 row)
+   ```
+
 ## Next steps
 
 Now that you've connected to the server group, the next step is to create

articles/postgresql/hyperscale/quickstart-create-portal.md

@@ -46,23 +46,27 @@ To follow this quickstart, you'll first need to:
    | Admin username    | Currently required to be the value `citus`, and can't be changed. |
    | Password          | A new password for the server admin account. It must contain between 8 and 128 characters. Your password must contain characters from three of the following categories: English uppercase letters, English lowercase letters, numbers (0 through 9), and non-alphanumeric characters (!, $, #, %, etc.). |
    | Version           | The latest PostgreSQL major version, unless you have specific requirements. |
-   | Compute + storage | The compute, storage, and Tier configurations for your new server. Select **Configure server group**. |
+
+5. Select **Configure server group**.
 
    ![compute and storage](../media/quickstart-hyperscale-create-portal/compute.png)
 
-5. For this quickstart, you can accept the default value of **Basic** for
+   For this quickstart, you can accept the default value of **Basic** for
    **Tiers**. The other option, standard tier, creates worker nodes for
    greater total data capacity and query parallelism. See
    [tiers](concepts-server-group.md#tiers) for a more in-depth comparison.
-6. Select **Next : Networking >** at the bottom of the screen.
-7. In the **Networking** tab, select **Allow public access from Azure services
+
+6. Select **Save**.
+
+7. Select **Next : Networking >** at the bottom of the screen.
+8. In the **Networking** tab, select **Allow public access from Azure services
    and resources within Azure to this server group**.
 
    ![networking configuration](../media/quickstart-hyperscale-create-portal/networking.png)
 
-8. Select **Review + create** and then **Create** to create the server.
+9. Select **Review + create** and then **Create** to create the server.
    Provisioning takes a few minutes.
-9. The page will redirect to monitor deployment. When the live status changes
+10. The page will redirect to monitor deployment. When the live status changes
    from **Deployment is in progress** to **Your deployment is complete**.
    After this transition, select **Go to resource**.
 

articles/postgresql/hyperscale/quickstart-distribute-tables.md

@@ -88,16 +88,16 @@ By default, `create_distributed_table()` splits tables into 32 shards.  We can
 verify using the `citus_shards` view:
 
 ```sql
-SELECT table_name, count(*)
+SELECT table_name, count(*) AS shards
   FROM citus_shards
  GROUP BY 1;
 ```
 
 ```
-  table_name   | count
----------------+-------
- github_events |    32
- github_users  |    32
+  table_name   | shards
+---------------+--------
+ github_users  |     32
+ github_events |     32
 (2 rows)
 ```
 
@@ -106,21 +106,31 @@ SELECT table_name, count(*)
 We're ready to fill the tables with sample data. For this quickstart, we'll use
 a dataset previously captured from the GitHub API.
 
+Run the following commands to download example CSV files and load them into the
+database tables. (The `curl` command downloads the files, and comes
+pre-installed in the Azure Cloud Shell.)
+
 ```
+-- download users and store in table
+
 \COPY github_users FROM PROGRAM 'curl https://examples.citusdata.com/users.csv' WITH (FORMAT CSV)
+
+-- download events and store in table
+
 \COPY github_events FROM PROGRAM 'curl https://examples.citusdata.com/events.csv' WITH (FORMAT CSV)
 ```
 
 We can confirm the shards now hold data:
 
 ```sql
-SELECT table_name, pg_size_pretty(sum(shard_size))
+SELECT table_name,
+       pg_size_pretty(sum(shard_size)) AS shard_size_sum
   FROM citus_shards
  GROUP BY 1;
 ```
 
 ```
-  table_name   | pg_size_pretty
+  table_name   | shard_size_sum
 ---------------+----------------
  github_users  | 38 MB
  github_events | 95 MB

articles/postgresql/hyperscale/quickstart-run-queries.md

@@ -43,7 +43,9 @@ SELECT count(*) FROM github_users;
 
 Recall that `github_users` is a distributed table, meaning its data is divided
 between multiple shards. Hyperscale (Citus) automatically runs the count on all
-the shards in parallel, and combines the results.
+shards in parallel, and combines the results.
+
+Let's continue looking at a few more query examples:
 
 ```sql
 -- Find all events for a single user.
@@ -67,10 +69,6 @@ SELECT created_at, event_type, repo->>'name' AS repo_name
 
 ## More complicated queries
 
-Hyperscale (Citus) uses an advanced query planner to transform arbitrary SQL
-queries into tasks running across shards. The tasks run in parallel on
-horizontally scalable worker nodes.
-
 Here's an example of a more complicated query, which retrieves hourly
 statistics for push events on GitHub. It uses PostgreSQL's JSONB feature to
 handle semi-structured data.
@@ -98,7 +96,7 @@ ORDER BY hour;
 (4 rows)
 ```
 
-Hyperscale (Citus) also automatically applies changes to data definition across
+Hyperscale (Citus) also automatically applies data definition changes across
 the shards of a distributed table.
 
 ```sql
@@ -113,12 +111,10 @@ The quickstart is now complete. You've successfully created a scalable
 Hyperscale (Citus) server group, created tables, sharded them, loaded data, and
 run distributed queries.
 
-Here are good resources to begin to deepen your knowledge.
+Here are good resources to deepen your knowledge.
 
 * See a more detailed [illustration](tutorial-shard.md) of distributed query
   execution.
-* Discover [useful diagnostic queries](howto-useful-diagnostic-queries.md) to
-  inspect distributed tables.
-* Learn how to speed up the per-minute `http_request` aggregation from this
-  example with "roll-ups" in the [real-time
-  dashboard](tutorial-design-database-realtime.md) tutorial.
+* Scale your server group by [adding
+  nodes](howto-scale-grow.md#add-worker-nodes) and [rebalancing
+  shards](howto-scale-rebalance.md).