Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[docs][core] update quick starts with new dataset #11653

Merged
merged 15 commits into from
Mar 29, 2022
828 changes: 564 additions & 264 deletions docs/content/latest/quick-start/explore/ysql.md

Large diffs are not rendered by default.

340 changes: 321 additions & 19 deletions docs/content/latest/sample-data/retail-analytics.md

Large diffs are not rendered by default.

Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@ showAsideToc: true

Use any browser to connect to Yugabyte Cloud by using Cloud Shell. Cloud Shell doesn't require a CA certificate or any special network access configured.

## Command line interface

You have the option of using the following command line interfaces (CLIs) in Cloud Shell:

- [ysqlsh](../../../admin/ysqlsh/) - YSQL shell for interacting with YugabyteDB using the [YSQL API](../../../api/ysql/).
Expand Down Expand Up @@ -68,7 +70,7 @@ Use HELP for help.
admin@ycqlsh:yugabyte>
```

If you enter an incorrect password, the shell session terminates immediately and you must start a new session.
When you connect to your cluster using Cloud Shell with the YSQL API, the shell window incorporates a [quick start guide](../../cloud-quickstart/qs-explore/), with a series of pre-built queries for you to run.

## ysqlsh meta-commands in Cloud Shell

Expand Down
12 changes: 0 additions & 12 deletions docs/content/latest/yugabyte-cloud/cloud-quickstart/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,18 +42,6 @@ Get started with YugabyteDB on Yugabyte Cloud in a few steps:
</a>
</div>

<div class="col-12 col-md-6 col-lg-12 col-xl-6">
<a class="section-link icon-offset" href="qs-data/">
<div class="head">
<img class="icon" src="/images/section_icons/quick_start/explore_ysql.png" aria-hidden="true" />
<div class="title">Create a database and load data</div>
</div>
<div class="body">
Create a database on your cluster and add some data using Cloud Shell.
</div>
</a>
</div>

<div class="col-12 col-md-6 col-lg-12 col-xl-6">
<a class="section-link icon-offset" href="qs-explore/">
<div class="head">
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ showAsideToc: true

The free cluster provides a fully functioning single node YugabyteDB cluster deployed to the region of your choice. The cluster is free forever and includes enough resources to explore the core features available for developing applications with YugabyteDB. No credit card information is required. You can only have one free cluster.

After setting up your Yugabyte Cloud account, [log in](https://cloud.yugabyte.com/login) to display the Yugabyte Cloud console. The console has the following main sections, accessed via the left menu:
After setting up your Yugabyte Cloud account, [log in](https://cloud.yugabyte.com/login) to access Yugabyte Cloud. Yugabyte Cloud has the following main sections, accessed via the left menu:

- **Getting Started** - Create your free cluster and access documentation.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ To connect to your cluster, do the following:
Cloud Shell opens in a separate browser window. Cloud Shell can take up to 30 seconds to be ready.

```output
Password for user admin:
Enter the password for your database user:
```

1. Enter the password for the admin user credentials that you saved when you created the cluster.\
Expand Down Expand Up @@ -63,4 +63,4 @@ For information on other ways to connect to your cluster, refer to [Connect to c

## Next step

[Create a database and load data](../qs-data/)
[Explore distributed SQL](../qs-explore)
189 changes: 0 additions & 189 deletions docs/content/latest/yugabyte-cloud/cloud-quickstart/qs-data.md

This file was deleted.

233 changes: 38 additions & 195 deletions docs/content/latest/yugabyte-cloud/cloud-quickstart/qs-explore.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,211 +14,54 @@ isTocNested: true
showAsideToc: true
---

After [creating a free cluster](../qs-add/), [connecting to the cluster](../qs-connect/) using Cloud Shell, and [creating a database (yb_demo) and loading some data](../qs-data/), you can start exploring YugabyteDB's PostgreSQL-compatible, fully-relational Yugabyte SQL API.
After [creating a free cluster](../qs-add/) and [connecting to the cluster](../qs-connect/) using Cloud Shell, you can start exploring YugabyteDB's PostgreSQL-compatible, fully-relational Yugabyte SQL API.

This exercise assumes you are already connected to your cluster using the `ysqlsh` shell, have created the `yb_demo` database, and loaded the sample data.
When you connect to your cluster using Cloud Shell with the YSQL API, the shell window incorporates a quick start guide, with a series of pre-built queries for you to run.

## Explore YugabyteDB
## Create a database

To display the schema of the `products` table, enter the following command:
While optional, it's good practise to create separate databases for different applications.

```sql
yb_demo=# \d products
```

```output
Table "public.products"
Column | Type | Collation | Nullable | Default
------------+-----------------------------+-----------+----------+--------------------------------------
id | bigint | | not null | nextval('products_id_seq'::regclass)
created_at | timestamp without time zone | | |
category | text | | |
ean | text | | |
price | double precision | | |
quantity | integer | | | 5000
rating | double precision | | |
title | text | | |
vendor | text | | |
Indexes:
"products_pkey" PRIMARY KEY, lsm (id HASH)
```

### Simple queries

To see how many products there are in this table, run the following query.

```sql
yb_demo=# SELECT count(*) FROM products;
```

```output
count
-------
15
(1 row)
```

The following query selects the `id`, `title`, `category`, and `price` columns for the first five products.

```sql
yb_demo=# SELECT id, title, category, price, rating
FROM products
LIMIT 5;
```

```output
id | title | category | price | rating
----+---------------------------+-----------+------------------+--------
3 | Synergistic Granite Chair | Doohickey | 35.3887448815391 | 4
14 | Awesome Concrete Shoes | Widget | 25.0987635927189 | 4
9 | Practical Bronze Computer | Widget | 58.3131209852614 | 4.2
12 | Sleek Paper Toucan | Gizmo | 77.3428505441222 | 4.4
5 | Enormous Marble Wallet | Gadget | 82.7450976850356 | 4
(5 rows)
```

### The JOIN clause

Use a JOIN clause to combine rows from two or more tables, based on a related column between them.

The following JOIN query selects the `total` column from the `orders` table, and for each of these orders, fetches the `id`, `name`, and `email` from the `users` table of the corresponding users that placed those orders. The related column between the two tables is the user's id.

```sql
yb_demo=# SELECT users.id, users.name, users.email, orders.id, orders.total
FROM orders INNER JOIN users ON orders.user_id=users.id
LIMIT 5;
```

```output
id | name | email | id | total
----+--------------------+------------------------------+----+------------------
4 | Arnold Adams | adams.arnold@gmail.com | 22 | 49.0560710142838
15 | Bertrand Romaguera | romaguera.bertrand@gmail.com | 76 | 28.0989026289413
1 | Hudson Borer | borer-hudson@yahoo.com | 9 | 81.6742695904106
10 | Tressa White | white.tressa@yahoo.com | 54 | 122.116378514938
4 | Arnold Adams | adams.arnold@gmail.com | 23 | 56.5115886738793
(5 rows)
```

### Distributed transactions

To track quantities accurately, each product being ordered in some quantity by a user has to decrement the corresponding product inventory quantity. These operations should be performed inside a transaction.

Imagine the user with id `1` wants to order `10` units of the product with id `2`.

Before running the transaction, you can verify the quantity of product `2` in stock by running the following query:
To create a database, enter the following command:

```sql
yb_demo=# SELECT id, category, price, quantity FROM products WHERE id=2;
```

```output
SELECT id, category, price, quantity FROM products WHERE id=2;
id | category | price | quantity
----+-----------+------------------+----------
2 | Doohickey | 70.0798961307176 | 5000
(1 row)
yugabyte=# CREATE DATABASE yb_demo;
```

To place the order, you can run the following transaction:
Next, connect to the new database using the ysqlsh `\c` meta-command:

```sql
yb_demo=# BEGIN TRANSACTION;

/* First insert a new order into the orders table. */
INSERT INTO orders
(id, created_at, user_id, product_id, discount, quantity, subtotal, tax, total)
VALUES (
(SELECT max(id)+1 FROM orders) /* id */,
now() /* created_at */,
1 /* user_id */,
2 /* product_id */,
0 /* discount */,
10 /* quantity */,
(10 * (SELECT price FROM products WHERE id=2)) /* subtotal */,
0 /* tax */,
(10 * (SELECT price FROM products WHERE id=2)) /* total */
) RETURNING id;

/* Next decrement the total quantity from the products table. */
UPDATE products SET quantity = quantity - 10 WHERE id = 2;

COMMIT;
```

Verify that the order got inserted by running the following command:

```sql
yb_demo=# SELECT * FROM orders WHERE id = (SELECT max(id) FROM orders);
```

```output
id | created_at | user_id | product_id | discount | quantity | subtotal | tax | total
----+----------------------------+---------+------------+----------+----------+------------------+-----+------------------
77 | 2021-09-08 20:03:12.308302 | 1 | 2 | 0 | 10 | 700.798961307176 | 0 | 700.798961307176
(1 row)
```

To verify that total quantity of product id `2` in the inventory has been updated, run the following query:

```sql
yb_demo=# SELECT id, category, price, quantity FROM products WHERE id=2;
```

```output
id | category | price | quantity
----+-----------+------------------+----------
2 | Doohickey | 70.0798961307176 | 4990
(1 row)
```

### Create a view

To answer questions such as what percentage of the total sales is from the Facebook channel, you can create a view.

```sql
yb_demo=# CREATE VIEW channel AS
(SELECT source, ROUND(SUM(orders.total)) AS total_sales
FROM users LEFT JOIN orders ON users.id=orders.user_id
GROUP BY source
ORDER BY total_sales DESC);
```

Now that the view is created, you can see it in the list of relations.

```sql
yb_demo=# \d
```

```output
List of relations
Schema | Name | Type | Owner
--------+-----------------+----------+----------
public | channel | view | yugabyte
public | orders | table | yugabyte
public | orders_id_seq | sequence | yugabyte
public | products | table | yugabyte
public | products_id_seq | sequence | yugabyte
public | reviews | table | yugabyte
public | reviews_id_seq | sequence | yugabyte
public | users | table | yugabyte
public | users_id_seq | sequence | yugabyte
(9 rows)
```

```sql
yb_demo=# SELECT source,
total_sales * 100.0 / (SELECT SUM(total_sales) FROM channel) AS percent_sales
FROM channel
WHERE source='Facebook';
```

```output
source | percent_sales
----------+------------------
Facebook | 31.3725490196078
(1 row)
```
yugabyte=# \c yb_demo;
```

## Run the tutorial

Begin the tutorial by selecting the steps in the left navigation panel, then clicking the **Run** button for the corresponding SQL statements. The tutorial starts with the following tasks:

1. Create a Table.\
\
The tutorial database includes two tables: `dept` for Departments, and `emp` for Employees. The employees table references the departments table through a foreign key constraint. The employees table also references itself through a foreign key constraint to ensure that an employee's manager is in turn an employee themselves. The table uses these constraints to ensure integrity of data, such as uniqueness and validity of email addresses.
1. Insert Data.\
\
Data is added to the tables using multi-value inserts to reduce client-server round trips.

After you create the tables and insert the data, click **Let's get started with the tutorials** to begin the tutorial scenarios. The quick start includes the following:

| Scenario | Description |
| :--- | :--- |
| Self Join | List all employees earning more than their managers using a self-join query. |
| With Recursive | List the manager hierarchy using a recursive query. |
| LAG Window Function | Compare employee hiring time interval by department using an analytical window function. |
| CROSSTABVIEW | Display the sum of salary per job and department using a cross tab pivot query. |
| Regexp | List all employees matching Gmail and org email domains using regular expressions for text pattern matching. |
| GIN Index | Query employee skills using a GIN index on a JSON document. |
| Text Search Index | Create a GIN text search index on the description column and query for words. |
| Arithmetic Date Intervals | Find employees with overlapping evaluation periods using arithmetic date intervals. |
| SQL Update | Update the salary of all employees who are not managers and display the new results. |
| Prepared Statement | Get the salary for an employee using a prepared statement. |
| Stored Procedure | Transfer a commission from one employee to another using a stored procedure. |
| Trigger | Record the last update time of each row automatically. |
| Create Index | Create and analyze an index on the fly. |

## Next step

Expand Down