Skip to content

Commit

Permalink
[docs][explore] Intro/setup for Explore (#14810)
Browse files Browse the repository at this point in the history 
* Intro/setup for Explore

* Explore index page changes

* try it a different way

* Misc edits

* minor edits

* minor edits

* add setup boilerplate to some topics

* comments, edit, format

* review comments, cleanup

* format

* style fix on tab widget

* add shortcode for explore setup

* test push

* indexes and constraints

* review comments

* observability changes

* tidyups

* tidyups

* tidyups

* tidyups

* links, format

* tidyups

* delete file

* minor edit

Co-authored-by: aishwarya24 <ashchakravarthy@gmail.com>
  • Loading branch information
@ddhodge @aishwarya24
ddhodge and aishwarya24 authored Nov 14, 2022
1 parent 2f908eb commit febc5da
Show file tree
Hide file tree
Showing 72 changed files with 1,058 additions and 2,725 deletions.
2 changes: 1 addition & 1 deletion docs/content/preview/architecture/transactions/read-committed.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ The recheck steps are as follows:
1. On commit of any conflicting transaction, traverse the chain of updates as described above and re-evaluate the latest version of the row for any conflict. If there is no conflict, `insert` the original row. Else, perform the `do update` part on the latest version of the row.
1. ON CONFLICT DO NOTHING: do nothing if a conflict occurs.

Note that the above methodology in PostgreSQL can lead to two different user visible semantics, one which is the common case and another which is a degenerate situation which can never be seen in practice, but is nevertheless possible and still upholds the semantics of Read Commited isolation. The common case is as follows:
Note that the preceding methodology in PostgreSQL can lead to two different user visible semantics. One is the common case, and the other is a degenerate situation that can never be seen in practice, but is nevertheless possible and still upholds the semantics of Read Committed isolation. The common case is as follows:

```sql
create table test (k int primary key, v int);
Expand Down
5 changes: 3 additions & 2 deletions docs/content/preview/contribute/docs/widgets-and-shortcodes.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,10 +17,11 @@ There are a number of display widgets and shortcodes available. All the shortcod
## Admonition boxes

Use the note, tip, and warning shortcodes to create admonition boxes.

### tip

{{< tip title="Tip" >}}
A tip box gives a hint or other useful but optional piece of information.
A tip box gives a hint or other helpful but optional piece of information.
{{< /tip >}}

#### tip source
Expand Down Expand Up @@ -63,7 +64,7 @@ An inline section switcher lets you switch between content sections **without a

![Inline section switcher](https://raw.githubusercontent.com/yugabyte/docs/master/contributing/inline-section-switcher.png)

The corresponding code for this widget is shown below. Note that the actual content must be placed in a file with the `.md` extension inside a subdirectory whose name is easy to associate with the switcher title.
The corresponding code for this widget is as follows. Note that the actual content must be placed in a file with the `.md` extension inside a subdirectory; name the subdirectory such that it can be associated with the switcher title.

```html
<ul class="nav nav-tabs-alt nav-tabs-yb">
Expand Down
2 changes: 1 addition & 1 deletion docs/content/preview/deploy/multi-dc/async-replication.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -135,7 +135,7 @@ Replication lag is computed at the tablet level as follows:

*hybrid_clock_time* is the hybrid clock timestamp on the source's tablet-server, and *last_read_hybrid_time* is the hybrid clock timestamp of the latest record pulled from the source.
To obtain information about the overall maximum lag, you should check `/metrics` or `/prometheus-metrics` for `async_replication_sent_lag_micros` or `async_replication_committed_lag_micros` and take the maximum of these values across each source's T-Server. For information on how to set up the node exporter and Prometheus manually, see [Prometheus integration](../../../explore/observability/prometheus-integration/linux/).
To obtain information about the overall maximum lag, you should check `/metrics` or `/prometheus-metrics` for `async_replication_sent_lag_micros` or `async_replication_committed_lag_micros` and take the maximum of these values across each source's T-Server. For information on how to set up the node exporter and Prometheus manually, see [Prometheus integration](../../../explore/observability/prometheus-integration/macos/).

## Set up replication with TLS

Expand Down
331 changes: 200 additions & 131 deletions docs/content/preview/explore/_index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,151 +12,220 @@ aliases:
- /preview/explore/planet-scale/
- /preview/explore/cloud-native/orchestration-readiness/
type: indexpage
showRightNav: true
---

<div class="row">
<div class="col-12 col-md-6 col-lg-12 col-xl-6">
<a class="section-link icon-offset" href="ysql-language-features/">
<div class="head">
<img class="icon" src="/images/section_icons/explore/fault_tolerance.png" aria-hidden="true" />
<div class="title">SQL features</div>
</div>
<div class="body">
SQL features in YSQL.
</div>
</a>
</div>
The Explore section introduces you to YugabyteDB's features and provides examples.

<div class="col-12 col-md-6 col-lg-12 col-xl-6">
<a class="section-link icon-offset" href="fault-tolerance/macos/">
<div class="head">
<img class="icon" src="/images/section_icons/explore/fault_tolerance.png" aria-hidden="true" />
<div class="title">Fault tolerance</div>
</div>
<div class="body">
Resilient and self-healing.
</div>
</a>
</div>
Most examples demonstrating database features such as API compatibility can be run on a single-node cluster on your laptop or using the free Sandbox cluster in YugabyteDB Managed. More advanced scenarios use a multi-node deployment. Refer to [Set up your YugabyteDB cluster](#set-up-your-yugabytedb-cluster) for instructions on creating clusters to run the examples.

<div class="col-12 col-md-6 col-lg-12 col-xl-6">
<a class="section-link icon-offset" href="linear-scalability/">
<div class="head">
<img class="icon" src="/images/section_icons/explore/linear_scalability.png" aria-hidden="true" />
<div class="title">Horizontal scalability</div>
</div>
<div class="body">
Reliable, rapid scaling for both writes and reads.
</div>
</a>
</div>
The following table describes the YugabyteDB features you can explore, along with the setup required to run the examples (single- or multi-node cluster).

<div class="col-12 col-md-6 col-lg-12 col-xl-6">
<a class="section-link icon-offset" href="transactions/">
<div class="head">
<div class="icon"><i class="fa-solid fa-file-invoice-dollar"></i></div>
<div class="title">Transactions</div>
</div>
<div class="body">
Explore distributed transactions support and other concurrency control features in YugabyteDB.
</div>
</a>
</div>
| Section | Purpose | [Cluster&nbsp;Setup](#set-up-your-yugabytedb-cluster) |
| :--- | :--- | :--- |
| [SQL features](ysql-language-features/) | Learn about YugabyteDB's compatibility with PostgreSQL, including data types, queries, expressions, operators, extensions, and more. | Single&nbsp;node<br/>Local/Cloud |
| [Going beyond SQL](ysql-language-features/going-beyond-sql/) | Learn about reducing read latency via follower reads and moving data closer to users using tablespaces. | Multi node<br/>Local |
| [Fault tolerance](fault-tolerance/macos/) | Learn how YugabyteDB achieves high availability when a node fails. | Multi&nbsp;node<br/>Local |
| [Horizontal scalability](linear-scalability/) | See how YugabyteDB handles loads while dynamically adding or removing nodes. | Multi node<br/>Local |
| [Transactions](transactions/) | Understand how distributed transactions and isolation levels work in YugabyteDB. | Single&nbsp;node<br/>Local/Cloud |
| [Indexes and constraints](indexes-constraints/) | Explore indexes in YugabyteDB, including primary and foreign keys, secondary, unique, partial, and expression indexes, and more. | Single&nbsp;node<br/>Local/Cloud |
| [JSON support](json-support/jsonb-ysql/) | YugabyteDB support for JSON is nearly identical to that in PostgreSQL - learn about JSON-specific functions and operators in YugabyteDB. | Single&nbsp;node<br/>Local/Cloud |
| [Multi-region deployments](multi-region-deployments/) | Learn about the different multi-region topologies that you can deploy using YugabyteDB. | Multi node<br/>Local |
| [Query tuning](query-1-performance/) | Learn about the tools available to identify and optimize queries in YSQL. | Single&nbsp;node<br/>Local/Cloud |
| [Cluster management](cluster-management/) | Learn how to roll back database changes to a specific point in time using point in time recovery. | Single&nbsp;node<br/>Local |
| [Change data capture](change-data-capture/) | Learn about YugabyteDB support for streaming data to Kafka. | N/A |
| [Security](security/security/) | Learn how to secure data in YugabyteDB, using authentication, authorization (RBAC), encryption, and more. | Single&nbsp;node<br/>Local/Cloud |
| [Observability](observability/) | Export metrics into Prometheus and create dashboards using Grafana. | Multi node<br/>Local |

<div class="col-12 col-md-6 col-lg-12 col-xl-6">
<a class="section-link icon-offset" href="indexes-constraints/">
<div class="head">
<div class="icon"><i class="fa-solid fa-file-invoice-dollar"></i></div>
<div class="title">Indexes and constraints</div>
</div>
<div class="body">
Improve database performance with indexes and constraints.
</div>
</a>
</div>
## Set up your YugabyteDB cluster

<div class="col-12 col-md-6 col-lg-12 col-xl-6">
<a class="section-link icon-offset" href="json-support/jsonb-ysql/">
<div class="head">
<div class="icon"><i class="fa-regular fa-file-code"></i></div>
<div class="title">JSON support</div>
</div>
<div class="body">
JSON document data types and support for built-in functions, indexes and constraints.
</div>
</a>
</div>
The examples in Explore can be run on your local machine, or in the cloud using a cluster in YugabyteDB Managed.

<div class="col-12 col-md-6 col-lg-12 col-xl-6">
<a class="section-link icon-offset" href="multi-region-deployments/">
<div class="head">
<img class="icon" src="/images/section_icons/explore/planet_scale.png" aria-hidden="true" />
<div class="title">Multi-region deployments</div>
</div>
<div class="body">
Multi-region deployment topologies, including synchronous and xCluster replication, geo-partitioning, and more.
</div>
</a>
</div>
This section assumes that you have either [created an account](https://cloud.yugabyte.com/signup?utm_medium=direct&utm_source=docs&utm_campaign=Cloud_signup) in YugabyteDB Managed or [installed YugabyteDB](../quick-start/linux/) on your local computer.

<div class="col-12 col-md-6 col-lg-12 col-xl-6">
<a class="section-link icon-offset" href="query-1-performance/">
<div class="head">
<img class="icon" src="/images/section_icons/explore/fault_tolerance.png" aria-hidden="true" />
<div class="title">Query tuning</div>
</div>
<div class="body">
Optimize query performance.
</div>
<ul class="nav nav-tabs-alt nav-tabs-yb custom-tabs">
<li >
<a href="#cloud" class="nav-link active" id="cloud-tab" data-toggle="tab"
role="tab" aria-controls="cloud" aria-selected="true">
<i class="fas fa-cloud" aria-hidden="true"></i>
Use a cloud cluster
</a>
</div>

<div class="col-12 col-md-6 col-lg-12 col-xl-6">
<a class="section-link icon-offset" href="change-data-capture/">
<div class="head">
<img class="icon" src="/images/section_icons/explore/monitoring.png" aria-hidden="true" />
<div class="title">Change data capture</div>
</div>
<div class="body">
Stream database changes to external processes, applications, or other databases.
</div>
</li>
<li>
<a href="#local" class="nav-link" id="local-tab" data-toggle="tab"
role="tab" aria-controls="local" aria-selected="false">
<i class="icon-shell" aria-hidden="true"></i>
Use a local cluster
</a>
</div>
</li>
</ul>

<div class="col-12 col-md-6 col-lg-12 col-xl-6">
<a class="section-link icon-offset" href="security/security/">
<div class="head">
<img class="icon" src="/images/section_icons/explore/secure.png" aria-hidden="true" />
<div class="title">Security</div>
</div>
<div class="body">
Learn about strategies for securing YugabyteDB.
</div>
</a>
</div>
<div class="tab-content">
<div id="cloud" class="tab-pane fade show active" role="tabpanel" aria-labelledby="cloud-tab">

<div class="col-12 col-md-6 col-lg-12 col-xl-6">
<a class="section-link icon-offset" href="observability/">
<div class="head">
<img class="icon" src="/images/section_icons/explore/monitoring.png" aria-hidden="true" />
<div class="title">Observability</div>
</div>
<div class="body">
Observe metrics at every layer of the database using Prometheus.
</div>
</a>
</div>
To run the Explore examples in YugabyteDB Managed, create a single- or multi-node cluster as follows.

{{< tabpane text=true >}}

{{% tab header="Single-node cluster" lang="YBM Single" %}}

Examples requiring a single-node cluster can be run using the free [Sandbox](../yugabyte-cloud/cloud-basics/create-clusters/create-clusters-free/) cluster.

If you haven't already created your sandbox cluster, log in to YugabyteDB Managed, on the **Clusters** page click **Add Cluster**, and follow the instructions in the **Create Cluster** wizard.

Save your cluster credentials in a convenient location. You will use them to connect to your cluster.

{{% /tab %}}

{{% tab header="Multi-node cluster" lang="YBM Multi" %}}

Before you can create a multi-node cluster in YugabyteDB Managed, you need to [add your billing profile and payment method](../yugabyte-cloud/cloud-admin/cloud-billing-profile/), or you can [request a free trial](https://support.yugabyte.com/hc/en-us/requests/new?ticket_form_id=360003113431).

To create a single region multi-node cluster, refer to [Create a single-region cluster](../yugabyte-cloud/cloud-basics/create-clusters/create-single-region/).

{{% /tab %}}

{{< /tabpane >}}

**Connect to your clusters**

You can run Explore exercises in YugabyteDB Managed using the [Cloud Shell](../yugabyte-cloud/cloud-connect/connect-cloud-shell/):

1. In YugabyteDB Managed, on the **Clusters** page, select your cluster.
1. Click **Connect**.
1. Click **Launch Cloud Shell**.
1. Enter the user name from the cluster credentials you downloaded when you created the cluster.
1. Select the API to use (YSQL or YCQL) and click **Confirm**.
The shell displays in a separate browser page. Cloud Shell can take up to 30 seconds to be ready.
1. Enter the password from the cluster credentials you downloaded when you created the cluster.

Note that if your Cloud Shell session is idle for more than 5 minutes, your browser may disconnect you. To resume, close the browser tab and connect again.

<div class="col-12 col-md-6 col-lg-12 col-xl-6">
<a class="section-link icon-offset" href="cluster-management/">
<div class="head">
<img class="icon" src="/images/section_icons/explore/fault_tolerance.png" aria-hidden="true" />
<div class="title">Cluster management</div>
</div>
<div class="body">
Learn about point-in-time recovery.
</div>
</a>
</div>
<div id="local" class="tab-pane fade" role="tabpanel" aria-labelledby="local-tab">

To run the examples in Explore, you'll need to create a single- or multi-node cluster.

For testing and learning YugabyteDB on your computer, use the [yugabyted](../reference/configuration/yugabyted/) cluster management utility to create and manage clusters.

{{< tabpane text=true >}}

{{% tab header="Single-node cluster" lang="Single-node cluster" %}}

You can create a single-node local cluster with a replication factor (RF) of 1 by running the following command:

```sh
./bin/yugabyted start --advertise_address=127.0.0.1
```

Or, if you are running macOS Monterey:

```sh
./bin/yugabyted start --advertise_address=127.0.0.1 \
--master_webserver_port=9999
```

For more information, refer to [Quick Start](../quick-start/linux/#create-a-local-cluster).

To stop a single-node cluster, do the following:

```sh
./bin/yugabyted destroy
```

{{% /tab %}}

{{% tab header="Multi-node cluster" lang="Multi-node cluster" %}}

If a single-node cluster is currently running, first destroy the running cluster as follows:

```sh
./bin/yugabyted destroy
```

Start a local three-node cluster with a replication factor of `3`by first creating a single node cluster as follows:

```sh
./bin/yugabyted start \
--advertise_address=127.0.0.1 \
--base_dir=/tmp/ybd1 \
--cloud_location=aws.us-east.us-east-1a
```

On MacOS and Linux, the additional nodes need loopback addresses configured:

```sh
sudo ifconfig lo0 alias 127.0.0.2
sudo ifconfig lo0 alias 127.0.0.3
```

Next, join two more nodes with the previous node. By default, [yugabyted](../reference/configuration/yugabyted/) creates a cluster with a replication factor of `3` on starting a 3 node cluster.

```sh
./bin/yugabyted start \
--advertise_address=127.0.0.2 \
--base_dir=/tmp/ybd2 \
--cloud_location=aws.us-east.us-east-2a \
--join=127.0.0.1
```

```sh
./bin/yugabyted start \
--advertise_address=127.0.0.3 \
--base_dir=/tmp/ybd3 \
--cloud_location=aws.us-east.us-east-3a \
--join=127.0.0.1
```

```sh
./bin/yugabyted configure --fault_tolerance=zone
```

To destroy the multi-node cluster, do the following:

```sh
./bin/yugabyted destroy --base_dir=/tmp/ybd1
./bin/yugabyted destroy --base_dir=/tmp/ybd2
./bin/yugabyted destroy --base_dir=/tmp/ybd3
```

{{% /tab %}}

{{< /tabpane >}}

**Connect to clusters**

To run the examples in your cluster, you use either the ysqlsh or ycqlsh CLI to interact with YugabyteDB via the YSQL or YCQL API.

To start ysqlsh:

```sh
./bin/ysqlsh
```

```output
ysqlsh (11.2-YB-2.0.0.0-b0)
Type "help" for help.
yugabyte=#
```

To start ycqlsh:

```sh
./bin/ycqlsh
```

```output
Connected to local cluster at 127.0.0.1:9042.
[ycqlsh 5.0.1 | Cassandra 3.9-SNAPSHOT | CQL spec 3.4.2 | Native protocol v4]
Use HELP for help.
ycqlsh>
```

</div>
</div>

## Next step

Start exploring [SQL features](ysql-language-features/).
Loading

0 comments on commit febc5da

Please sign in to comment.