v20-rc1: update documentation (#1767)

* update vitess image versions

Signed-off-by: Shlomi Noach <2607934+shlomi-noach@users.noreply.github.com>

* 21.0 docs

Signed-off-by: Shlomi Noach <2607934+shlomi-noach@users.noreply.github.com>

* remove 'git checkout' from 21.0 docs

Signed-off-by: Shlomi Noach <2607934+shlomi-noach@users.noreply.github.com>

---------

Signed-off-by: Shlomi Noach <2607934+shlomi-noach@users.noreply.github.com>

config.toml

@@ -13,8 +13,8 @@ pygmentsStyle = "fruity"
 # Versions (folder-based)
 
 [params.versions]
-current = "19.0"
-next = "20.0"
+current = "20.0"
+next = "21.0"
 
 # end Versions
 

content/en/docs/20.0/_index.md

@@ -1,7 +1,7 @@
 ---
-title: v20.0 (Development)
+title: v20.0 (RC)
 description: >
-  Under construction, development release.
+  Release Candidate.
   Everything you need to know about scaling MySQL with Vitess.
 notoc: true
 cascade:

content/en/docs/20.0/get-started/local-docker.md

@@ -21,6 +21,7 @@ Clone the GitHub repository via:
 
 ```shell
 cd vitess
+git checkout release-20.0
 ```
 
 ## Build the docker image

content/en/docs/20.0/get-started/local-mac.md

@@ -76,6 +76,7 @@ With everything now in place you can clone and build Vitess.
 ```sh
 $ git clone https://github.com/vitessio/vitess.git
 $ cd vitess
+$ git checkout release-20.0
 $ make build
 ```
 

content/en/docs/20.0/get-started/local.md

@@ -88,8 +88,8 @@ Download the [latest binary release](https://github.com/vitessio/vitess/releases
 * Ubuntu is the only fully supported OS, for another OS please [build Vitess by yourself](/docs/contributing) or use the Docker images.
 
 ```sh
-version=19.0.0-rc1
-file=vitess-${version}-1bdb462.tar.gz
+version=20.0.0-rc1
+file=vitess-${version}-fe01c8d.tar.gz
 wget https://github.com/vitessio/vitess/releases/download/v${version}/${file}
 tar -xzf ${file}
 cd ${file/.tar.gz/}

content/en/docs/20.0/get-started/operator.md

@@ -33,6 +33,7 @@ Change to the operator example directory:
 ```bash
 git clone https://github.com/vitessio/vitess
 cd vitess/examples/operator
+git checkout release-20.0
 ```
 
 Install the operator:

content/en/docs/20.0/get-started/vttestserver-docker-image.md

@@ -22,6 +22,7 @@ Clone the GitHub repository via:
 
 ```shell
 cd vitess
+git checkout release-20.0
 ```
 
 #### Build the docker image

content/en/docs/21.0/_index.md

@@ -0,0 +1,11 @@
+---
+title: v21.0 (Development)
+description: >
+  Under construction, development release.
+  Everything you need to know about scaling MySQL with Vitess.
+notoc: true
+cascade:
+  version: v21.0
+weight: 79
+---
+

content/en/docs/21.0/concepts/_index.md

@@ -0,0 +1,6 @@
+---
+title: Concepts
+description: Learn core Vitess concepts and terminology
+aliases: ['/docs/overview/concepts/']
+weight: 3
+---

content/en/docs/21.0/concepts/cell.md

@@ -0,0 +1,10 @@
+---
+title: Cell
+description: Data center, availability zone or group of computing resources
+---
+
+A *cell* is a group of servers and network infrastructure collocated in an area, and isolated from failures in other cells. It is typically either a full data center or a subset of a data center, sometimes called a *zone* or *availability zone*. Vitess gracefully handles cell-level failures, such as when a cell is cut off the network.
+
+Each cell in a Vitess implementation has a [local topology service](../topology-service), which is hosted in that cell. The topology service contains most of the information about the Vitess tablets in its cell. This enables a cell to be taken down and rebuilt as a unit.
+
+Vitess limits cross-cell traffic for both data and metadata. While it may be useful to also have the ability to route read traffic to individual cells, Vitess currently serves reads only from the local cell. Writes will go cross-cell when necessary, to wherever the primary for that shard resides.

content/en/docs/21.0/concepts/execution-plans.md

@@ -0,0 +1,33 @@
+---
+title: Execution Plans
+---
+
+Vitess parses queries at both the VTGate and VTTablet layer in order to evaluate the best method to execute a query. This evaluation is known as query planning, and results in a _query execution plan_.
+
+The Execution Plan is dependent on both the query and the associated [VSchema](../vschema). One of the underlying goals of Vitess' planning strategy is to push down as much work as possible to the underlying MySQL instances. When this is not possible, Vitess will use a plan that collects input from multiple sources and merges the results to produce the correct query result.
+
+### Evaluation Model
+
+An execution plan consists of operators, each of which implements a specific piece of work. The operators combine into a tree-like structure, which represents the overall execution plan. The plan represents each operator as a node in the tree. Each operator takes as input zero or more rows, and produces as output zero or more rows. This means that the output from one operator becomes the input for the next operator. Operators that join two branches in the tree combine input from two incoming streams and produce a single output.
+
+Evaluation of the execution plan begins at the leaf nodes of the tree. Leaf nodes pull in data from VTTablet, the Topology Service, and in some cases are also able to evaluate expression values locally. Each leaf node will not have input from other operators, and pipe in any nodes they produce into their parent nodes. The parents nodes will then pipe in nodes to their parent nodes, all the way up to a root node. The root node produces the final results of the query and delivers the results to the user.
+
+### Routing Operators
+
+A routing operator in an execution plan instructs Vitess which destination to send a piece of work to. Typically a routing operator will tell Vitess which keyspace to use when executing the piece of work, whether or not the keyspace is sharded, and, in the case of sharded keyspaces, which vindex to use.
+
+### Scatter Queries
+
+A routing operator which specifies a sharded keyspace, but which does not specify a vindex, will "scatter" to all shards in a sharded keyspace. A "scatter" query contains one or more pieces of work routed to a sharded keyspace, but which cannot be routed using a vindex.
+
+Note that not all queries which are sent to multiple (or all) shards in a sharded keyspace are considered scatter queries.
+
+### Observing Execution Plans
+
+Cached execution plans can be observed at the VTGate level by browsing the `/queryz` end point.
+
+Starting with Vitess 16, individual statement plans can also be observed with [`VExplain`](../../user-guides/sql/explain-format-vtexplain).
+
+**Related Vitess Documentation**
+
+* [VTGate](../vtgate)

content/en/docs/21.0/concepts/keyspace-id.md

@@ -0,0 +1,10 @@
+---
+title: Keyspace ID
+---
+
+The *keyspace ID* is the value that is used to decide on which shard a given row lives. [Range-based Sharding](../../reference/features/sharding/#key-ranges-and-partitions) refers to creating shards that each cover a particular range of keyspace IDs.
+
+Using this technique means you can split a given shard by replacing it with two or more new shards that combine to cover the original range of keyspace IDs, without having to move any records in other shards.
+
+The keyspace ID itself is computed using a function of some column in your data, such as the user ID. Vitess allows you to choose from a variety of functions ([vindexes](../../reference/features/vindexes/)) to perform this mapping. This allows you to choose the right one to achieve optimal distribution of the data across shards.
+

content/en/docs/21.0/concepts/keyspace.md

@@ -0,0 +1,8 @@
+---
+title: Keyspace
+---
+
+A *keyspace* is a logical database. If you're using [sharding](http://en.wikipedia.org/wiki/Shard_(database_architecture)), a keyspace maps to multiple MySQL databases; if you're not using sharding, a keyspace maps directly to a MySQL database name. In either case, a keyspace appears as a single database from the standpoint of the application.
+
+Reading data from a keyspace is just like reading from a MySQL database. However, depending on the consistency requirements of the read operation, Vitess might fetch the data from a primary database or from a replica. By routing each query to the appropriate database, Vitess allows your code to be structured as if it were reading from a single MySQL database.
+

content/en/docs/21.0/concepts/move-tables.md

@@ -0,0 +1,26 @@
+---
+title: MoveTables
+---
+
+MoveTables is a workflow based on VReplication. It enables you to relocate tables between keyspaces, and therefore physical MySQL instances, without downtime.
+
+## Identifying Candidate Tables
+
+It is recommended to keep tables that need to join on each other in the same keyspace, so typical candidates for a MoveTables operation are a set of tables which logically group together or are otherwise isolated.
+
+If you have multiple groups of tables as candidates, which makes the most sense to move may depend on the specifics of your environment. For example, a larger table will take more time to move, but in doing so you might be able to utilize additional or newer hardware which has more headroom before you need to perform additional operations such as sharding.
+
+Similarly, tables that are updated at a more frequent rate could increase the move time.
+
+### Impact to Production Traffic
+
+Internally, a MoveTables operation is comprised of both a table copy and a subscription to all changes made to the table. Vitess uses batching to improve the performance of both table copying and applying subscription changes, but you should expect that tables with lighter modification rates to move faster.
+
+During the active move process, data is copied from replicas instead of the primary server. This helps ensure minimal production traffic impact.
+
+During the `SwitchTraffic` phase of the MoveTables operation, for primary tablets, Vitess may be briefly unavailable. This unavailability is usually a few seconds, but will be higher in the event that your system has a high replication delay from primary to replica(s).
+
+
+**Related Vitess Documentation**
+
+* [MoveTables User Guide](../../user-guides/migration/move-tables)