Skip to content

Commit

Permalink
docs: Update Scylla to ScyllaDB in *all* RST docs files v3
Browse files Browse the repository at this point in the history
  • Loading branch information
tzach authored and tgrabiec committed Jul 1, 2024
1 parent b6aabca commit 91401f7
Show file tree
Hide file tree
Showing 244 changed files with 1,529 additions and 1,529 deletions.
8 changes: 4 additions & 4 deletions docs/architecture/anti-entropy/hinted-handoff.rst
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
ScyllaDB Hinted Handoff
========================

A typical write in Scylla works according to the scenarios described in our :doc:`Fault Tolerance documentation </architecture/architecture-fault-tolerance>`.
A typical write in ScyllaDB works according to the scenarios described in our :doc:`Fault Tolerance documentation </architecture/architecture-fault-tolerance>`.

But what happens when a write request is sent to a Scylla node that is unresponsive due to reasons including heavy write load on a node, network issues, or even hardware failure? To ensure availability and consistency, Scylla implements :term:`hinted handoff<Hinted Handoff>`.
But what happens when a write request is sent to a ScyllaDB node that is unresponsive due to reasons including heavy write load on a node, network issues, or even hardware failure? To ensure availability and consistency, ScyllaDB implements :term:`hinted handoff<Hinted Handoff>`.

:term:`Hint<Hint>` = target replica ID + :term:`mutation<Mutation>` data


In other words, Scylla saves a copy of the writes intended for down nodes, and replays them to the nodes when they are up later. Thus, the write operation flow, when a node is down, looks like this:
In other words, ScyllaDB saves a copy of the writes intended for down nodes, and replays them to the nodes when they are up later. Thus, the write operation flow, when a node is down, looks like this:

1. The co-ordinator determines all the replica nodes;

Expand Down Expand Up @@ -39,7 +39,7 @@ Hinted handoff is enabled and managed by these settings in :code:`scylla.yaml`:

* :code:`hinted_handoff_enabled`: enables or disables the hinted handoff feature completely or enumerates data centers where hints are allowed. By default, “true” enables hints to all nodes.
* :code:`max_hint_window_in_ms`: do not generate hints if the destination node has been down for more than this value. If a node is down longer than this period, new hints are not created. Hint generation resumes once the destination node is back up. By default, this is set to 3 hours.
* :code:`hints_directory`: the directory where Scylla will store hints. By default this is :code:`$SCYLLA_HOME/hints`.
* :code:`hints_directory`: the directory where ScyllaDB will store hints. By default this is :code:`$SCYLLA_HOME/hints`.

Storing of the hint can also fail. Enabling hinted handoff therefore does not eliminate the need for repair; a user must recurrently :doc:`run a full repair </operating-scylla/procedures/maintenance/repair/>` to ensure data consistency across the cluster nodes.

Expand Down
22 changes: 11 additions & 11 deletions docs/architecture/anti-entropy/index.rst
Original file line number Diff line number Diff line change
@@ -1,16 +1,16 @@
Scylla Anti-Entropy
===================
ScyllaDB Anti-Entropy
=====================

.. toctree::
:hidden:
:glob:

Scylla Hinted Handoff <hinted-handoff/>
Scylla Read Repair <read-repair/>
Scylla Repair </operating-scylla/procedures/maintenance/repair/>
ScyllaDB Hinted Handoff <hinted-handoff/>
ScyllaDB Read Repair <read-repair/>
ScyllaDB Repair </operating-scylla/procedures/maintenance/repair/>


Scylla replicates data according to :term:`eventual consistency<Eventual Consistency>`. This means that, in Scylla, when considering the :term:`CAP Theorem<CAP Theorem>`, availability and partition tolerance are considered a higher priority over consistency. Although Scylla’s tunable consistency allows users to make a tradeoff between availability and consistency, Scylla’s :term:`consistency level<Consistency Level (CL)>` is tunable per query.
ScyllaDB replicates data according to :term:`eventual consistency<Eventual Consistency>`. This means that, in ScyllaDB, when considering the :term:`CAP Theorem<CAP Theorem>`, availability and partition tolerance are considered a higher priority over consistency. Although ScyllaDB’s tunable consistency allows users to make a tradeoff between availability and consistency, ScyllaDB’s :term:`consistency level<Consistency Level (CL)>` is tunable per query.

However, over time, there can be a number of reasons for data inconsistencies, including:

Expand All @@ -21,14 +21,14 @@ However, over time, there can be a number of reasons for data inconsistencies, i
5. a replica that cannot write due to being out of resources;
6. file corruption.

To mitigate :term:`entropy<Entropy>`, or data inconsistency, Scylla uses a few different processes. The goal of Scylla :term:`anti-entropy<Anti-Entropy>` - based on that of Apache Cassandra - is to compare data on all replicas, synchronize data between all replicas, and, finally, ensure each replica has the most recent data.
To mitigate :term:`entropy<Entropy>`, or data inconsistency, ScyllaDB uses a few different processes. The goal of ScyllaDB :term:`anti-entropy<Anti-Entropy>` - based on that of Apache Cassandra - is to compare data on all replicas, synchronize data between all replicas, and, finally, ensure each replica has the most recent data.

Anti-entropy measures include *write-time* changes such as :term:`hinted handoff<Hinted Handoff>`, *read-time* changes such as :term:`read repair<Read Repair>`, and finally, periodic maintenance via :term:`repair<Repair>`.

* :doc:`Scylla Hinted Handoff <hinted-handoff/>` - High-Level view of Scylla Hinted Handoff
* :doc:`Scylla Read Repair <read-repair/>` - High-Level view of Scylla Read Repair
* :doc:`Scylla Repair </operating-scylla/procedures/maintenance/repair/>` - Description of Scylla Repair
* :doc:`ScyllaDB Hinted Handoff <hinted-handoff/>` - High-Level view of ScyllaDB Hinted Handoff
* :doc:`ScyllaDB Read Repair <read-repair/>` - High-Level view of ScyllaDB Read Repair
* :doc:`ScyllaDB Repair </operating-scylla/procedures/maintenance/repair/>` - Description of ScyllaDB Repair

Also learn more in the `Cluster Management, Repair and Scylla Manager lesson <https://university.scylladb.com/courses/scylla-operations/lessons/cluster-management-repair-and-scylla-manager/topic/cluster-management-repair-and-scylla-manager/>`_ on Scylla University.
Also learn more in the `Cluster Management, Repair and ScyllaDB Manager lesson <https://university.scylladb.com/courses/scylla-operations/lessons/cluster-management-repair-and-scylla-manager/topic/cluster-management-repair-and-scylla-manager/>`_ on ScyllaDB University.

.. include:: /rst_include/apache-copyrights.rst
4 changes: 2 additions & 2 deletions docs/architecture/anti-entropy/read-repair.rst
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ ScyllaDB Read Repair

Read repair serves as an anti-entropy mechanism during read path.

On read operations, Scylla runs a process called :term:`read repair<Read Repair>`, to ensure that replicas are updated with most recently updated data. Such repairs during read path run automatically, asynchronously, and in the background.
On read operations, ScyllaDB runs a process called :term:`read repair<Read Repair>`, to ensure that replicas are updated with most recently updated data. Such repairs during read path run automatically, asynchronously, and in the background.

Note however, that if digest mismatch is detected before consistency level is reached, that repair will run in the foreground.

Expand Down Expand Up @@ -37,7 +37,7 @@ See the appendices below for the detailed flow.

.. image:: 4_read_repair.png

* :doc:`Scylla Anti-Entropy </architecture/anti-entropy/index/>`
* :doc:`ScyllaDB Anti-Entropy </architecture/anti-entropy/index/>`

Appendix
^^^^^^^^
Expand Down
6 changes: 3 additions & 3 deletions docs/architecture/compaction/compaction-strategies.rst
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ Choose a Compaction Strategy
============================


Scylla implements the following compaction strategies in order to reduce :term:`read amplification<Read Amplification>`, :term:`write amplification<Write Amplification>`, and :term:`space amplification<Space Amplification>`, which causes bottlenecks and poor performance. These strategies include:
ScyllaDB implements the following compaction strategies in order to reduce :term:`read amplification<Read Amplification>`, :term:`write amplification<Write Amplification>`, and :term:`space amplification<Space Amplification>`, which causes bottlenecks and poor performance. These strategies include:

* `Size-tiered compaction strategy (STCS)`_ - triggered when the system has enough (four by default) similarly sized SSTables.
* `Leveled compaction strategy (LCS)`_ - the system uses small, fixed-size (by default 160 MB) SSTables distributed across different levels.
Expand All @@ -12,7 +12,7 @@ Scylla implements the following compaction strategies in order to reduce :term:`

This document covers how to choose a compaction strategy and presents the benefits and disadvantages of each one. If you want more information on compaction in general or on any of these strategies, refer to the :doc:`Compaction Overview </kb/compaction>`. If you want an explanation of the CQL commands used to create a compaction strategy, refer to :doc:`Compaction CQL Reference </cql/compaction>` .

Learn more in the `Compaction Strategies lesson <https://university.scylladb.com/courses/scylla-operations/lessons/compaction-strategies/>`_ on Scylla University
Learn more in the `Compaction Strategies lesson <https://university.scylladb.com/courses/scylla-operations/lessons/compaction-strategies/>`_ on ScyllaDB University

.. _STCS1:

Expand Down Expand Up @@ -197,6 +197,6 @@ References
----------
* :doc:`Compaction Overview </kb/compaction>` - contains in depth information on all of the strategies
* :doc:`Compaction CQL Reference </cql/compaction>` - covers the CQL parameters used for implementing compaction
* Scylla Summit Tech Talk: `How to Ruin Performance by Choosing the Wrong Compaction Strategy <https://www.scylladb.com/tech-talk/ruin-performance-choosing-wrong-compaction-strategy-scylla-summit-2017/>`_
* ScyllaDB Summit Tech Talk: `How to Ruin Performance by Choosing the Wrong Compaction Strategy <https://www.scylladb.com/tech-talk/ruin-performance-choosing-wrong-compaction-strategy-scylla-summit-2017/>`_


4 changes: 2 additions & 2 deletions docs/architecture/console-CL-full-demo.rst
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
Consistency Level Console Demo
==============================
In this demo, we'll bring up 3 nodes and demonstrate how writes and reads look, with tracing enabled in a cluster where our :term:`Replication Factor (RF)<Replication Factor (RF)>` is set to **3**. We'll change the :term:`Consistency Level (CL)<Consistency Level (CL)>` between operations to show how messages are passed between nodes, and finally take down a few nodes to show failure conditions in a Scylla cluster.
In this demo, we'll bring up 3 nodes and demonstrate how writes and reads look, with tracing enabled in a cluster where our :term:`Replication Factor (RF)<Replication Factor (RF)>` is set to **3**. We'll change the :term:`Consistency Level (CL)<Consistency Level (CL)>` between operations to show how messages are passed between nodes, and finally take down a few nodes to show failure conditions in a ScyllaDB cluster.

You can also learn more in the `High Availability lesson <https://university.scylladb.com/courses/scylla-essentials-overview/lessons/high-availability/>`_ on Scylla University.
You can also learn more in the `High Availability lesson <https://university.scylladb.com/courses/scylla-essentials-overview/lessons/high-availability/>`_ on ScyllaDB University.


Note: We use asciinema_ to generate the console casts used in this demo. These asciicasts are more readable than embedded video, and allow you to copy the text or commands directly from the console to your clipboard. We suggest viewing console casts in **fullscreen** to see the properly formatted output.
Expand Down
4 changes: 2 additions & 2 deletions docs/architecture/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,8 @@ ScyllaDB Architecture
* :doc:`ScyllaDB Ring Architecture </architecture/ringarchitecture/index/>` - High-Level view of ScyllaDB Ring Architecture
* :doc:`ScyllaDB Fault Tolerance </architecture/architecture-fault-tolerance>` - Deep dive into ScyllaDB Fault Tolerance
* :doc:`Consistency Level Console Demo </architecture/console-CL-full-demo>` - Console Demos of Consistency Level Settings
* :doc:`Scylla Anti-Entropy </architecture/anti-entropy/index/>` - High-Level view of Scylla Anti-Entropy
* :doc:`SSTable </architecture/sstable/index/>` - Scylla SSTable 2.0 and 3.0 Format Information
* :doc:`ScyllaDB Anti-Entropy </architecture/anti-entropy/index/>` - High-Level view of ScyllaDB Anti-Entropy
* :doc:`SSTable </architecture/sstable/index/>` - ScyllaDB SSTable 2.0 and 3.0 Format Information
* :doc:`Compaction Strategies </architecture/compaction/compaction-strategies>` - High-level analysis of different compaction strategies
* :doc:`Raft Consensus Algorithm in ScyllaDB </architecture/raft>` - Overview of how Raft is implemented in ScyllaDB.

Expand Down
6 changes: 3 additions & 3 deletions docs/architecture/raft.rst
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ version. Please consult the upgrade guide.
The Raft upgrade procedure requires **full cluster availability** to correctly setup the Raft algorithm; after the setup finishes, Raft can proceed with only a majority of nodes, but this initial setup is an exception.
An unlucky event, such as a hardware failure, may cause one of your nodes to fail. If this happens before the Raft upgrade procedure finishes, the procedure will get stuck and your intervention will be required.

To verify that the procedure finishes, look at the log of every Scylla node (using ``journalctl _COMM=scylla``). Search for the following patterns:
To verify that the procedure finishes, look at the log of every ScyllaDB node (using ``journalctl _COMM=scylla``). Search for the following patterns:

* ``Starting internal upgrade-to-raft procedure`` denotes the start of the procedure,
* ``Raft upgrade finished`` denotes the end.
Expand Down Expand Up @@ -252,6 +252,6 @@ Learn More About Raft
----------------------
* `The Raft Consensus Algorithm <https://raft.github.io/>`_
* `Achieving NoSQL Database Consistency with Raft in ScyllaDB <https://www.scylladb.com/tech-talk/achieving-nosql-database-consistency-with-raft-in-scylla/>`_ - A tech talk by Konstantin Osipov
* `Making Schema Changes Safe with Raft <https://www.scylladb.com/presentations/making-schema-changes-safe-with-raft/>`_ - A Scylla Summit talk by Konstantin Osipov (register for access)
* `The Future of Consensus in ScyllaDB 5.0 and Beyond <https://www.scylladb.com/presentations/the-future-of-consensus-in-scylladb-5-0-and-beyond/>`_ - A Scylla Summit talk by Tomasz Grabiec (register for access)
* `Making Schema Changes Safe with Raft <https://www.scylladb.com/presentations/making-schema-changes-safe-with-raft/>`_ - A ScyllaDB Summit talk by Konstantin Osipov (register for access)
* `The Future of Consensus in ScyllaDB 5.0 and Beyond <https://www.scylladb.com/presentations/the-future-of-consensus-in-scylladb-5-0-and-beyond/>`_ - A ScyllaDB Summit talk by Tomasz Grabiec (register for access)

14 changes: 7 additions & 7 deletions docs/architecture/ringarchitecture/index.rst
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
ScyllaDB Ring Architecture - Overview
======================================

Scylla is a database that scales out and up. Scylla adopted much of its distributed scale-out design from the Apache Cassandra project (which adopted distribution concepts from Amazon Dynamo and data modeling concepts from Google BigTable).
ScyllaDB is a database that scales out and up. ScyllaDB adopted much of its distributed scale-out design from the Apache Cassandra project (which adopted distribution concepts from Amazon Dynamo and data modeling concepts from Google BigTable).

In the world of big data, a single node cannot hold the entire dataset and thus, a cluster of nodes is needed.

A Scylla :term:`cluster<Cluster>` is a collection of :term:`nodes<Node>`, or Scylla instances, visualized as a ring. All of the nodes should be homogeneous using a shared-nothing approach. This article describes the design that determines how data is distributed among the cluster members.
A ScyllaDB :term:`cluster<Cluster>` is a collection of :term:`nodes<Node>`, or ScyllaDB instances, visualized as a ring. All of the nodes should be homogeneous using a shared-nothing approach. This article describes the design that determines how data is distributed among the cluster members.

A Scylla :term:`keyspace<Keyspace>` is a collection of tables with attributes that define how data is replicated on nodes. A keyspace is analogous to a database in SQL. When a new keyspace is created, the user sets a numerical attribute, the :term:`replication factor<Replication Factor (RF)>`, that defines how data is replicated on nodes. For example, an :abbr:`RF (Replication Factor)` of 2 means a given token or token range will be stored on 2 nodes (or replicated on one additional node). We will use an RF value of 2 in our examples.
A ScyllaDB :term:`keyspace<Keyspace>` is a collection of tables with attributes that define how data is replicated on nodes. A keyspace is analogous to a database in SQL. When a new keyspace is created, the user sets a numerical attribute, the :term:`replication factor<Replication Factor (RF)>`, that defines how data is replicated on nodes. For example, an :abbr:`RF (Replication Factor)` of 2 means a given token or token range will be stored on 2 nodes (or replicated on one additional node). We will use an RF value of 2 in our examples.

A :term:`table<Table>` is a standard collection of columns and rows, as defined by a schema. Subsequently, when a table is created, using CQL (Cassandra Query Language) within a keyspace, a primary key is defined out of a subset of the table’s columns.

Expand Down Expand Up @@ -49,7 +49,7 @@ The hashed output of the partition key determines its placement within the clust

The figure above illustrates an example 0-1200 token range divided evenly amongst a three node cluster.

Scylla, by default, uses the Murmur3 partitioner. With the MurmurHash3 function, the 64-bit hash values (produced for the partition key) range from |From| to |To|. This explains why there are also negative values in our ``nodetool ring`` output below.
ScyllaDB, by default, uses the Murmur3 partitioner. With the MurmurHash3 function, the 64-bit hash values (produced for the partition key) range from |From| to |To|. This explains why there are also negative values in our ``nodetool ring`` output below.

.. |From| image:: CodeCogsEqn.gif
.. |To| image:: CodeCogsEqn-2.gif
Expand All @@ -58,9 +58,9 @@ Scylla, by default, uses the Murmur3 partitioner. With the MurmurHash3 function,

In the drawing above, each number represents a token range. With a replication factor of 2, we see that each node holds one range from the previous node, and one range from the next node.

Note, however, that Scylla exclusively uses a Vnode-oriented architecture. A :term:`Virtual node` represents a contiguous range of tokens owned by a single Scylla node. A physical node may be assigned multiple, non-contiguous Vnodes.
Note, however, that ScyllaDB exclusively uses a Vnode-oriented architecture. A :term:`Virtual node` represents a contiguous range of tokens owned by a single ScyllaDB node. A physical node may be assigned multiple, non-contiguous Vnodes.

Scylla’s implementation of a Vnode oriented architecture provides several advantages. First of all, rebalancing a cluster is no longer required when adding or removing nodes. Secondly, as rebuilding can stream data from all available nodes (instead of just the nodes where data would reside on a one-token-per-node setup), Scylla can rebuild faster.
ScyllaDB’s implementation of a Vnode oriented architecture provides several advantages. First of all, rebalancing a cluster is no longer required when adding or removing nodes. Secondly, as rebuilding can stream data from all available nodes (instead of just the nodes where data would reside on a one-token-per-node setup), ScyllaDB can rebuild faster.

.. image:: ring-architecture-5.png

Expand Down Expand Up @@ -113,7 +113,7 @@ We can also get information on our cluster with
Schema versions:
082bce63-be30-3e6b-9858-4fb243ce409c: [172.17.0.2, 172.17.0.3, 172.17.0.4]
Learn more in the `Cluster Node Ring lesson <https://university.scylladb.com/courses/scylla-essentials-overview/lessons/architecture/topic/cluster-node-ring/>`_ on Scylla University
Learn more in the `Cluster Node Ring lesson <https://university.scylladb.com/courses/scylla-essentials-overview/lessons/architecture/topic/cluster-node-ring/>`_ on ScyllaDB University

.. include:: /rst_include/apache-copyrights.rst

Loading

0 comments on commit 91401f7

Please sign in to comment.