mirror of https://github.com/apache/cassandra
Remove read_repair table option from docs, and restore read_repair_chance docs
patch by Milan Krisko; reviewed by Mick Semb Wever for CASSANDRA-17727
This commit is contained in:
Mick Semb Wever
parent
dd51df6734
commit
c2148980ce
|
|
@ -1,2 +1,3 @@
|
|||
ALTER TABLE addamsFamily
|
||||
WITH comment = 'A most excellent and useful table';
|
||||
WITH comment = 'A most excellent and useful table'
|
||||
AND read_repair_chance = 0.2;
|
||||
|
|
|
|||
|
|
@ -3,7 +3,8 @@ CREATE TABLE monkey_species (
|
|||
common_name text,
|
||||
population varint,
|
||||
average_size int
|
||||
) WITH comment='Important biological records';
|
||||
) WITH comment='Important biological records'
|
||||
AND read_repair_chance = 1.0;
|
||||
|
||||
CREATE TABLE timeline (
|
||||
userid uuid,
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
* Cassandra
|
||||
** xref:getting_started/index.adoc[Getting Started]
|
||||
** xref:getting_started/index.adoc[Getting Started]
|
||||
*** xref:getting_started/installing.adoc[Installing Cassandra]
|
||||
*** xref:getting_started/configuring.adoc[Configuring Cassandra]
|
||||
*** xref:getting_started/querying.adoc[Inserting and querying]
|
||||
|
|
@ -8,7 +8,7 @@
|
|||
|
||||
** xref:architecture/index.adoc[Architecture]
|
||||
*** xref:architecture/overview.adoc[Overview]
|
||||
*** xref:architecture/dynamo.adoc[Dynamo]
|
||||
*** xref:architecture/dynamo.adoc[Dynamo]
|
||||
*** xref:architecture/storage_engine.adoc[Storage engine]
|
||||
*** xref:architecture/guarantees.adoc[Guarantees]
|
||||
|
||||
|
|
@ -53,7 +53,6 @@
|
|||
*** xref:operating/snitch.adoc[Snitches]
|
||||
*** xref:operating/topo_changes.adoc[Topology changes]
|
||||
*** xref:operating/repair.adoc[Repair]
|
||||
*** xref:operating/read_repair.adoc[Read repair]
|
||||
*** xref:operating/hints.adoc[Hints]
|
||||
*** xref:operating/bloom_filters.adoc[Bloom filters]
|
||||
*** xref:operating/compression.adoc[Compression]
|
||||
|
|
@ -64,7 +63,7 @@
|
|||
*** xref:operating/security.adoc[Security]
|
||||
*** xref:operating/hardware.adoc[Hardware]
|
||||
*** xref:operating/audit_logging.adoc[Audit logging]
|
||||
*** xref:operating/compaction/index.adoc[Compaction]
|
||||
*** xref:operating/compaction/index.adoc[Compaction]
|
||||
|
||||
** xref:tools/index.adoc[Tools]
|
||||
*** xref:tools/cqlsh.adoc[cqlsh: the CQL shell]
|
||||
|
|
|
|||
|
|
@ -2,9 +2,9 @@
|
|||
:tabs:
|
||||
|
||||
CQL stores data in _tables_, whose schema defines the layout of the
|
||||
data in the table. Tables are located in _keyspaces_.
|
||||
A keyspace defines options that apply to all the keyspace's tables.
|
||||
The xref:cql/ddl.adoc#replication-strategy[replication strategy] is an important keyspace option, as is the replication factor.
|
||||
data in the table. Tables are located in _keyspaces_.
|
||||
A keyspace defines options that apply to all the keyspace's tables.
|
||||
The xref:cql/ddl.adoc#replication-strategy[replication strategy] is an important keyspace option, as is the replication factor.
|
||||
A good general rule is one keyspace per application.
|
||||
It is common for a cluster to define only one keyspace for an actie application.
|
||||
|
||||
|
|
@ -82,8 +82,8 @@ option at your own risk!).
|
|||
|===
|
||||
|
||||
The `replication` property is mandatory and must contain the `'class'` sub-option that defines the desired
|
||||
xref:cql/ddl.adoc#replication-strategy[replication strategy] class.
|
||||
The rest of the sub-options depend on which replication strategy is used.
|
||||
xref:cql/ddl.adoc#replication-strategy[replication strategy] class.
|
||||
The rest of the sub-options depend on which replication strategy is used.
|
||||
By default, Cassandra supports the following `'class'` values:
|
||||
|
||||
[[replication-strategy]]
|
||||
|
|
@ -122,7 +122,7 @@ replicas per datacenter, set a value of 3.
|
|||
When later altering keyspaces and changing the `replication_factor`,
|
||||
auto-expansion will only _add_ new datacenters for safety, it will not
|
||||
alter existing datacenters or remove any, even if they are no longer in
|
||||
the cluster. If you want to remove datacenters while setting the
|
||||
the cluster. If you want to remove datacenters while setting the
|
||||
`replication_factor`, explicitly zero out the datacenter you want to
|
||||
have zero replicas.
|
||||
|
||||
|
|
@ -179,10 +179,10 @@ include::example$CQL/create_ks_trans_repl.cql[]
|
|||
[[use-statement]]
|
||||
== USE
|
||||
|
||||
The `USE` statement changes the _current_ keyspace to the specified keyspace.
|
||||
The `USE` statement changes the _current_ keyspace to the specified keyspace.
|
||||
A number of objects in CQL are bound to a keyspace (tables, user-defined types, functions, etc.) and the
|
||||
current keyspace is the default keyspace used when those objects are
|
||||
referred to in a query without a fully-qualified name (without a prefixed keyspace name).
|
||||
referred to in a query without a fully-qualified name (without a prefixed keyspace name).
|
||||
A `USE` statement specifies the keyspace to use as an argument:
|
||||
|
||||
[source,bnf]
|
||||
|
|
@ -255,8 +255,8 @@ For example, here are some CQL statements to create tables:
|
|||
include::example$CQL/create_table.cql[]
|
||||
----
|
||||
|
||||
A CQL table has a name and is composed of a set of _rows_.
|
||||
Creating a table amounts to defining which xref:cql/ddl.adoc#column-definition[columns] each rows will have,
|
||||
A CQL table has a name and is composed of a set of _rows_.
|
||||
Creating a table amounts to defining which xref:cql/ddl.adoc#column-definition[columns] each rows will have,
|
||||
which of those columns comprise the xref:cql/ddl.adoc#primary-key[primary key], as well as defined
|
||||
xref:cql/ddl.adoc#create-table-options[options] for the table.
|
||||
|
||||
|
|
@ -267,10 +267,10 @@ statement will be a no-op if the table already exists.
|
|||
[[column-definition]]
|
||||
=== Column definitions
|
||||
|
||||
Every row in a CQL table will have the predefined columns defined at table creation.
|
||||
Every row in a CQL table will have the predefined columns defined at table creation.
|
||||
Columns can be added later using an xref:cql/ddl.adoc#alter-table-statement[alter statement].
|
||||
|
||||
A `column_definition` is comprised of the name of the column and its xref:cql/ddl.adoc#data-type[type],
|
||||
A `column_definition` is comprised of the name of the column and its xref:cql/ddl.adoc#data-type[type],
|
||||
restricting the values that are accepted for that column. Additionally, a column definition can have the
|
||||
following modifiers:
|
||||
|
||||
|
|
@ -282,15 +282,15 @@ following modifiers:
|
|||
|
||||
Some columns can be declared as `STATIC` in a table definition. A column
|
||||
that is static will be “shared” by all the rows belonging to the same
|
||||
partition (having the same xref:cql/ddl.adoc#partition-key[partition key].
|
||||
partition (having the same xref:cql/ddl.adoc#partition-key[partition key].
|
||||
|
||||
For example:
|
||||
|
||||
[{tabs}]
|
||||
====
|
||||
Code::
|
||||
+
|
||||
--
|
||||
[{tabs}]
|
||||
====
|
||||
Code::
|
||||
+
|
||||
--
|
||||
[source,cql]
|
||||
----
|
||||
include::example$CQL/create_static_column.cql[]
|
||||
|
|
@ -316,7 +316,7 @@ value for `s`.
|
|||
|
||||
The use of static columns has the following restrictions:
|
||||
|
||||
* A table without clustering columns cannot have static columns.
|
||||
* A table without clustering columns cannot have static columns.
|
||||
In a table without clustering columns, every partition has only one row, and
|
||||
so every column is inherently static)
|
||||
* Only non-primary key columns can be static.
|
||||
|
|
@ -325,20 +325,20 @@ so every column is inherently static)
|
|||
=== The Primary key
|
||||
|
||||
Within a table, a row is uniquely identified by its `PRIMARY KEY`, and
|
||||
hence all tables *must* define a single PRIMARY KEY.
|
||||
A `PRIMARY KEY` is composed of one or more of the defined columns in the table.
|
||||
Syntactically, the primary key is defined with the phrase `PRIMARY KEY`
|
||||
hence all tables *must* define a single PRIMARY KEY.
|
||||
A `PRIMARY KEY` is composed of one or more of the defined columns in the table.
|
||||
Syntactically, the primary key is defined with the phrase `PRIMARY KEY`
|
||||
followed by a comma-separated list of the column names within parenthesis.
|
||||
If the primary key has only one column, you can alternatively add the `PRIMARY KEY` phrase to
|
||||
that column in the table definition.
|
||||
The order of the columns in the primary key definition defines the partition key and
|
||||
that column in the table definition.
|
||||
The order of the columns in the primary key definition defines the partition key and
|
||||
clustering columns.
|
||||
|
||||
A CQL primary key is composed of two parts:
|
||||
|
||||
xref:cql/ddl.adoc#partition-key[partition key]::
|
||||
* It is the first component of the primary key definition.
|
||||
It can be a single column or, using an additional set of parenthesis, can be multiple columns.
|
||||
* It is the first component of the primary key definition.
|
||||
It can be a single column or, using an additional set of parenthesis, can be multiple columns.
|
||||
A table must have at least one partition key, the smallest possible table definition is:
|
||||
+
|
||||
[source,cql]
|
||||
|
|
@ -357,9 +357,9 @@ Some examples of primary key definition are:
|
|||
|
||||
[IMPORTANT]
|
||||
====
|
||||
The primary key uniquely identifies a row in the table, as described above.
|
||||
A consequence of this uniqueness is that if another row is inserted using the same primary key,
|
||||
then an `UPSERT` occurs and an existing row with the same primary key is replaced.
|
||||
The primary key uniquely identifies a row in the table, as described above.
|
||||
A consequence of this uniqueness is that if another row is inserted using the same primary key,
|
||||
then an `UPSERT` occurs and an existing row with the same primary key is replaced.
|
||||
Columns that are not part of the primary key cannot define uniqueness.
|
||||
====
|
||||
|
||||
|
|
@ -367,10 +367,10 @@ Columns that are not part of the primary key cannot define uniqueness.
|
|||
==== Partition key
|
||||
|
||||
Within a table, CQL defines the notion of a _partition_ that defines the location of data within a Cassandra cluster.
|
||||
A partition is the set of rows that share the same value for their partition key.
|
||||
A partition is the set of rows that share the same value for their partition key.
|
||||
|
||||
Note that if the partition key is composed of multiple columns, then rows belong to the same partition
|
||||
when they have the same values for all those partition key columns.
|
||||
Note that if the partition key is composed of multiple columns, then rows belong to the same partition
|
||||
when they have the same values for all those partition key columns.
|
||||
A hash is computed from the partition key columns and that hash value defines the partition location.
|
||||
So, for instance, given the following table definition and content:
|
||||
|
||||
|
|
@ -396,23 +396,23 @@ because the partition key, compound or otherwise, identifies a single location.
|
|||
|
||||
The most important property of partition is that all the rows belonging
|
||||
to the same partition are guaranteed to be stored on the same set of
|
||||
replica nodes.
|
||||
In other words, the partition key of a table defines which rows will be localized on the same
|
||||
node in the cluster.
|
||||
replica nodes.
|
||||
In other words, the partition key of a table defines which rows will be localized on the same
|
||||
node in the cluster.
|
||||
The localization of data is important to the efficient retrieval of data, requiring the Cassandra coordinator
|
||||
to contact as few nodes as possible.
|
||||
However, there is a flip-side to this guarantee, and all rows sharing a partition key will be stored on the same
|
||||
However, there is a flip-side to this guarantee, and all rows sharing a partition key will be stored on the same
|
||||
node, creating a hotspot for both reading and writing.
|
||||
While selecting a primary key that groups table rows assists batch updates and can ensure that the updates are
|
||||
While selecting a primary key that groups table rows assists batch updates and can ensure that the updates are
|
||||
_atomic_ and done in _isolation_, the partitions must be sized "just right, not too big nor too small".
|
||||
|
||||
Data modeling that considers the querying patterns and assigns primary keys based on the queries will have the lowest
|
||||
Data modeling that considers the querying patterns and assigns primary keys based on the queries will have the lowest
|
||||
latency in fetching data.
|
||||
|
||||
[[clustering-columns]]
|
||||
==== Clustering columns
|
||||
|
||||
The clustering columns of a table define the clustering order for the partition of that table.
|
||||
The clustering columns of a table define the clustering order for the partition of that table.
|
||||
For a given `partition`, all rows are ordered by that clustering order. Clustering columns also add uniqueness to
|
||||
a row in a table.
|
||||
|
||||
|
|
@ -432,10 +432,10 @@ include::example$RESULTS/select_table_clustercolumn.result[]
|
|||
----
|
||||
<1> Row 1 is in one partition, and Rows 2-5 are in a different one. The display order is also different.
|
||||
|
||||
Looking more closely at the four rows in the same partition, the `b` clustering column defines the order in which those rows
|
||||
are displayed.
|
||||
Whereas the partition key of the table groups rows on the same node, the clustering columns control
|
||||
how those rows are stored on the node.
|
||||
Looking more closely at the four rows in the same partition, the `b` clustering column defines the order in which those rows
|
||||
are displayed.
|
||||
Whereas the partition key of the table groups rows on the same node, the clustering columns control
|
||||
how those rows are stored on the node.
|
||||
|
||||
That sorting allows the very efficient retrieval of a range of rows within a partition:
|
||||
|
||||
|
|
@ -462,27 +462,27 @@ One important option that cannot be changed after creation, `CLUSTERING ORDER BY
|
|||
[[clustering-order]]
|
||||
==== Clustering order
|
||||
|
||||
The clustering order of a table is defined by the clustering columns.
|
||||
By default, the clustering order is ascending for the clustering column's data types.
|
||||
For example, integers order from 1, 2, ... n, while text orders from A to Z.
|
||||
The clustering order of a table is defined by the clustering columns.
|
||||
By default, the clustering order is ascending for the clustering column's data types.
|
||||
For example, integers order from 1, 2, ... n, while text orders from A to Z.
|
||||
|
||||
The `CLUSTERING ORDER BY` table option uses a comma-separated list of the
|
||||
clustering columns, each set for either `ASC` (for _ascending_ order) or `DESC` (for _descending order).
|
||||
The default is ascending for all clustering columns if the `CLUSTERING ORDER BY` option is not set.
|
||||
The default is ascending for all clustering columns if the `CLUSTERING ORDER BY` option is not set.
|
||||
|
||||
This option is basically a hint for the storage engine that changes the order in which it stores the row.
|
||||
Beware of the consequences of setting this option:
|
||||
|
||||
* It changes the default ascending order of results when queried with a `SELECT` statement with no `ORDER BY` clause.
|
||||
|
||||
* It limits how the `ORDER BY` clause is used in `SELECT` statements on that table.
|
||||
* It limits how the `ORDER BY` clause is used in `SELECT` statements on that table.
|
||||
Results can only be ordered with either the original clustering order or the reverse clustering order.
|
||||
Suppose you create a table with two clustering columns `a` and `b`, defined `WITH CLUSTERING ORDER BY (a DESC, b ASC)`.
|
||||
Queries on the table can use `ORDER BY (a DESC, b ASC)` or `ORDER BY (a ASC, b DESC)`.
|
||||
Queries on the table can use `ORDER BY (a DESC, b ASC)` or `ORDER BY (a ASC, b DESC)`.
|
||||
Mixed order, such as `ORDER BY (a ASC, b ASC)` or `ORDER BY (a DESC, b DESC)` will not return expected order.
|
||||
|
||||
* It has a performance impact on queries. Queries in reverse clustering order are slower than the default ascending order.
|
||||
If you plan to query mostly in descending order, declare the clustering order in the table schema using `WITH CLUSTERING ORDER BY ()`.
|
||||
If you plan to query mostly in descending order, declare the clustering order in the table schema using `WITH CLUSTERING ORDER BY ()`.
|
||||
This optimization is common for time series, to retrieve the data from newest to oldest.
|
||||
|
||||
[[create-table-general-options]]
|
||||
|
|
@ -495,6 +495,11 @@ A table supports the following options:
|
|||
|option | kind | default | description
|
||||
|
||||
| `comment` | _simple_ | none | A free-form, human-readable comment
|
||||
| `read_repair_chance` | _simple_ | 0.1 | The probability with which to query extra nodes
|
||||
(e.g. more nodes than required by the consistency level) for the purpose of read repairs.
|
||||
| `dclocal_read_repair_chance` | _simple_ | 0 | The probability with which to query extra nodes
|
||||
(e.g. more nodes than required by the consistency level) belonging to the same data center than
|
||||
the read coordinator for the purpose of read repairs.
|
||||
| xref:cql/ddl.adoc#spec_retry[`speculative_retry`] | _simple_ | 99PERCENTILE | Speculative retry options
|
||||
| `cdc` |_boolean_ |false |Create a Change Data Capture (CDC) log on the table
|
||||
| `additional_write_policy` |_simple_ |99PERCENTILE | Same as `speculative_retry`
|
||||
|
|
@ -508,7 +513,6 @@ impact the size of bloom filters in-memory and on-disk.
|
|||
| `compression` |_map_ |_see below_ | xref:operating/compression/index.adoc#cql-compression-options[Compression options]
|
||||
| `caching` |_map_ |_see below_ |Caching options
|
||||
| `memtable_flush_period_in_ms` |_simple_ |0 |Time (in ms) before Cassandra flushes memtables to disk
|
||||
| `read_repair` |_simple_ |BLOCKING |Sets read repair behavior (see below)
|
||||
|===
|
||||
|
||||
[[spec_retry]]
|
||||
|
|
@ -518,7 +522,7 @@ By default, Cassandra read coordinators only query as many replicas as
|
|||
necessary to satisfy consistency levels: one for consistency level
|
||||
`ONE`, a quorum for `QUORUM`, and so on. `speculative_retry` determines
|
||||
when coordinators may query additional replicas, a useful action when
|
||||
replicas are slow or unresponsive. Speculative retries reduce the latency.
|
||||
replicas are slow or unresponsive. Speculative retries reduce the latency.
|
||||
The speculative_retry option configures rapid read protection, where a coordinator sends more
|
||||
requests than needed to satisfy the consistency level.
|
||||
|
||||
|
|
@ -550,9 +554,9 @@ include::example$CQL/alter_table_spec_retry_percent.cql[]
|
|||
----
|
||||
|
||||
A percentile setting can backfire. If a single host becomes unavailable, it can
|
||||
force up the percentiles. A value of `p99` will not speculate as intended because the
|
||||
value at the specified percentile has increased too much. If the consistency level is set to `ALL`, all
|
||||
replicas are queried regardless of the speculative retry setting.
|
||||
force up the percentiles. A value of `p99` will not speculate as intended because the
|
||||
value at the specified percentile has increased too much. If the consistency level is set to `ALL`, all
|
||||
replicas are queried regardless of the speculative retry setting.
|
||||
|
||||
Cassandra 4.0 supports case-insensitivity for speculative retry values (https://issues.apache.org/jira/browse/CASSANDRA-14293[CASSANDRA-14293]). For example, assigning the value as `none`, `None`, or `NONE` has the same effect.
|
||||
|
||||
|
|
@ -575,12 +579,12 @@ lower at the time of calculation. Parameters are `XPERCENTILE`, `XP`, or
|
|||
|
||||
| `MAX(XPERCENTILE,YMS)` `ALWAYS` `NEVER` | MAX(90.5P,25ms) | A hybrid policy that uses either the specified
|
||||
percentile or fixed milliseconds depending on which value is higher at
|
||||
the time of calculation.
|
||||
the time of calculation.
|
||||
|===
|
||||
|
||||
Cassandra 4.0 adds support for hybrid `MIN()` and `MAX()` speculative retry policies, with a mix and match of either `MIN(), MAX()`, `MIN(), MIN()`, or `MAX(), MAX()` (https://issues.apache.org/jira/browse/CASSANDRA-14293[CASSANDRA-14293]).
|
||||
The hybrid mode will still speculate if the normal `p99` for the table is < 50ms, the minimum value.
|
||||
But if the `p99` level goes higher than the maximum value, then that value can be used.
|
||||
But if the `p99` level goes higher than the maximum value, then that value can be used.
|
||||
In a hybrid value, one value must be a fixed time (ms) value and the other a percentile value.
|
||||
|
||||
To illustrate variations, the following examples are all valid:
|
||||
|
|
@ -597,16 +601,16 @@ quorum write will be upgraded to include transient replicas.
|
|||
===== Compaction options
|
||||
|
||||
The `compaction` options must minimally define the `'class'` sub-option,
|
||||
to specify the compaction strategy class to use.
|
||||
The supported classes are:
|
||||
to specify the compaction strategy class to use.
|
||||
The supported classes are:
|
||||
|
||||
* `'SizeTieredCompactionStrategy'`, xref:operating/compaction/stcs.adoc#stcs[STCS] (Default)
|
||||
* `'LeveledCompactionStrategy'`, xref:operating/compaction/lcs.adoc#lcs[LCS]
|
||||
* `'TimeWindowCompactionStrategy'`, xref:operating/compaction/twcs.adoc#twcs[TWCS]
|
||||
* `'TimeWindowCompactionStrategy'`, xref:operating/compaction/twcs.adoc#twcs[TWCS]
|
||||
|
||||
The `'DateTieredCompactionStrategy'` is also supported but deprecated;
|
||||
`'TimeWindowCompactionStrategy'` should be used.
|
||||
If a custom strategies is required, specify the full class name as a xref:cql/definitions.adoc#constants[string constant].
|
||||
`'TimeWindowCompactionStrategy'` should be used.
|
||||
If a custom strategies is required, specify the full class name as a xref:cql/definitions.adoc#constants[string constant].
|
||||
|
||||
All default strategies support a number of xref:operating/compaction/index.adoc#compaction-options[common options], as well as options specific to the strategy chosen. See the section corresponding to your strategy for details: xref:operating/compaction/stcs.adoc#stcs_options[STCS], xref:operating/compaction/lcs.adoc#lcs_options[LCS], xref:operating/compaction/twcs.adoc#twcs_options[TWCS].
|
||||
|
||||
|
|
@ -622,20 +626,20 @@ sub-options are available:
|
|||
|===
|
||||
|Option |Default |Description
|
||||
| `class` | LZ4Compressor | The compression algorithm to use. Default compressor are: LZ4Compressor,
|
||||
SnappyCompressor, DeflateCompressor and ZstdCompressor.
|
||||
Use `'enabled' : false` to disable compression.
|
||||
SnappyCompressor, DeflateCompressor and ZstdCompressor.
|
||||
Use `'enabled' : false` to disable compression.
|
||||
Custom compressor can be provided by specifying the full class name as a xref:cql/definitions.adoc#constants[string constant].
|
||||
|
||||
| `enabled` | true | Enable/disable sstable compression.
|
||||
| `enabled` | true | Enable/disable sstable compression.
|
||||
If the `enabled` option is set to `false`, no other options must be specified.
|
||||
|
||||
| `chunk_length_in_kb` | 64 | On disk SSTables are compressed by block (to allow random reads).
|
||||
| `chunk_length_in_kb` | 64 | On disk SSTables are compressed by block (to allow random reads).
|
||||
This option defines the size (in KB) of said block. See xref:cql/ddl.adoc#chunk_note[note] for further information.
|
||||
|
||||
| `crc_check_chance` | 1.0 | Determines how likely Cassandra is to verify the checksum on each
|
||||
compression chunk during reads.
|
||||
|
||||
| `compression_level` | 3 | Compression level. Only applicable for `ZstdCompressor`.
|
||||
| `compression_level` | 3 | Compression level. Only applicable for `ZstdCompressor`.
|
||||
Accepts values between `-131072` and `22`.
|
||||
|===
|
||||
|
||||
|
|
@ -643,9 +647,9 @@ Accepts values between `-131072` and `22`.
|
|||
[NOTE]
|
||||
====
|
||||
Bigger values may improve the compression rate, but will increase the minimum size of data to be read from
|
||||
disk for a read.
|
||||
The default value is an optimal value for compressing tables.
|
||||
Chunk length must be a power of 2 when computing the chunk number from an uncompressed file offset.
|
||||
disk for a read.
|
||||
The default value is an optimal value for compressing tables.
|
||||
Chunk length must be a power of 2 when computing the chunk number from an uncompressed file offset.
|
||||
Block size may be adjusted based on read/write access patterns such as:
|
||||
|
||||
* How much data is typically requested at once
|
||||
|
|
@ -663,8 +667,8 @@ include::example$CQL/chunk_length.cql[]
|
|||
===== Caching options
|
||||
|
||||
Caching optimizes the use of cache memory of a table. The cached data is
|
||||
weighed by size and access frequency.
|
||||
The `caching` options can configure both the `key cache` and the `row cache` for the table.
|
||||
weighed by size and access frequency.
|
||||
The `caching` options can configure both the `key cache` and the `row cache` for the table.
|
||||
The following sub-options are available:
|
||||
|
||||
[cols=",,",options="header",]
|
||||
|
|
@ -672,8 +676,8 @@ The following sub-options are available:
|
|||
|Option |Default |Description
|
||||
| `keys` | ALL | Whether to cache keys (key cache) for this table. Valid values are: `ALL` and `NONE`.
|
||||
|
||||
| `rows_per_partition` | NONE | The amount of rows to cache per partition (row cache).
|
||||
If an integer `n` is specified, the first `n` queried rows of a partition will be cached.
|
||||
| `rows_per_partition` | NONE | The amount of rows to cache per partition (row cache).
|
||||
If an integer `n` is specified, the first `n` queried rows of a partition will be cached.
|
||||
Valid values are: `ALL`, to cache all rows of a queried partition, or `NONE` to disable row caching.
|
||||
|===
|
||||
|
||||
|
|
@ -684,37 +688,6 @@ For instance, to create a table with both a key cache and 10 rows cached per par
|
|||
include::example$CQL/caching_option.cql[]
|
||||
----
|
||||
|
||||
[[read-repair-options]]
|
||||
===== Read Repair options
|
||||
|
||||
The `read_repair` options configure the read repair behavior, tuning for various performance and consistency behaviors.
|
||||
|
||||
The values are:
|
||||
[cols=",,",options="header",]
|
||||
|===
|
||||
|Option |Default |Description
|
||||
|`BLOCKING` | yes | If a read repair is triggered, the read blocks writes sent to other replicas until the consistency level is reached by the writes.
|
||||
|
||||
|`NONE` | no | If set, the coordinator reconciles any differences between replicas, but doesn't attempt to repair them.
|
||||
|===
|
||||
|
||||
Two consistency properties are affected by read repair behavior.
|
||||
|
||||
* Monotonic quorum reads: Monotonic quorum reads
|
||||
prevents reads from appearing to go back in time in some circumstances.
|
||||
When monotonic quorum reads are not provided and a write fails to reach
|
||||
a quorum of replicas, the read values may be visible in one read, and then disappear
|
||||
in a subsequent read. `BLOCKING` provides this behavior.
|
||||
* Write atomicity: Write atomicity prevents reads
|
||||
from returning partially-applied writes. Cassandra attempts to provide
|
||||
partition-level write atomicity, but since only the data covered by a
|
||||
SELECT statement is repaired by a read repair, read repair can break
|
||||
write atomicity when data is read at a more granular level than it is
|
||||
written. For example, read repair can break write atomicity if you write
|
||||
multiple rows to a clustered partition in a batch, but then select a
|
||||
single row by specifying the clustering column in a SELECT statement.
|
||||
`NONE` provides this behavior.
|
||||
|
||||
===== Other considerations:
|
||||
|
||||
* Adding new columns (see `ALTER TABLE` below) is a constant time
|
||||
|
|
@ -741,14 +714,14 @@ include::example$CQL/alter_table_with_comment.cql[]
|
|||
The `ALTER TABLE` statement can:
|
||||
|
||||
* `ADD` a new column to a table. The primary key of a table cannot ever be altered.
|
||||
A new column, thus, cannot be part of the primary key.
|
||||
A new column, thus, cannot be part of the primary key.
|
||||
Adding a column is a constant-time operation based on the amount of data in the table.
|
||||
* `DROP` a column from a table. This command drops both the column and all
|
||||
its content. Be aware that, while the column becomes immediately
|
||||
unavailable, its content are removed lazily during compaction. Because of this lazy removal,
|
||||
the command is a constant-time operation based on the amount of data in the table.
|
||||
the command is a constant-time operation based on the amount of data in the table.
|
||||
Also, it is important to know that once a column is dropped, a column with the same name can be re-added,
|
||||
unless the dropped column was a non-frozen column like a collection.
|
||||
unless the dropped column was a non-frozen column like a collection.
|
||||
|
||||
[WARNING]
|
||||
.Warning
|
||||
|
|
@ -793,7 +766,7 @@ include::example$BNF/truncate_table.bnf[]
|
|||
----
|
||||
|
||||
`TRUNCATE TABLE foo` is the preferred syntax for consistency with other DDL
|
||||
statements.
|
||||
statements.
|
||||
However, tables are the only object that can be truncated currently, and the `TABLE` keyword can be omitted.
|
||||
|
||||
Truncating a table permanently removes all existing data from the table, but without removing the table itself.
|
||||
|
|
|
|||
|
|
@ -5,7 +5,6 @@
|
|||
* xref:operating/topo_changes.adoc[Topology changes]
|
||||
* xref:operating/hints.adoc[Hints]
|
||||
* xref:operating/repair.adoc[Repair]
|
||||
* xref:operating/read_repair.adoc[Read repair]
|
||||
* xref:operating/backups.adoc[Backups]
|
||||
* xref:operating/compression.adoc[Compression]
|
||||
* xref:operating/compaction/index.adoc[Compaction]
|
||||
|
|
|
|||
|
|
@ -1,264 +0,0 @@
|
|||
= Read repair
|
||||
|
||||
Read Repair is the process of repairing data replicas during a read
|
||||
request. If all replicas involved in a read request at the given read
|
||||
consistency level are consistent the data is returned to the client and
|
||||
no read repair is needed. But if the replicas involved in a read request
|
||||
at the given consistency level are not consistent a read repair is
|
||||
performed to make replicas involved in the read request consistent. The
|
||||
most up-to-date data is returned to the client. The read repair runs in
|
||||
the foreground and is blocking in that a response is not returned to the
|
||||
client until the read repair has completed and up-to-date data is
|
||||
constructed.
|
||||
|
||||
== Expectation of Monotonic Quorum Reads
|
||||
|
||||
Cassandra uses a blocking read repair to ensure the expectation of
|
||||
"monotonic quorum reads" i.e. that in 2 successive quorum reads, it’s
|
||||
guaranteed the 2nd one won't get something older than the 1st one, and
|
||||
this even if a failed quorum write made a write of the most up to date
|
||||
value only to a minority of replicas. "Quorum" means majority of nodes
|
||||
among replicas.
|
||||
|
||||
== Table level configuration of monotonic reads
|
||||
|
||||
Cassandra 4.0 adds support for table level configuration of monotonic
|
||||
reads
|
||||
(https://issues.apache.org/jira/browse/CASSANDRA-14635[CASSANDRA-14635]).
|
||||
The `read_repair` table option has been added to table schema, with the
|
||||
options `blocking` (default), and `none`.
|
||||
|
||||
The `read_repair` option configures the read repair behavior to allow
|
||||
tuning for various performance and consistency behaviors. Two
|
||||
consistency properties are affected by read repair behavior.
|
||||
|
||||
* Monotonic Quorum Reads: Provided by `BLOCKING`. Monotonic quorum reads
|
||||
prevents reads from appearing to go back in time in some circumstances.
|
||||
When monotonic quorum reads are not provided and a write fails to reach
|
||||
a quorum of replicas, it may be visible in one read, and then disappear
|
||||
in a subsequent read.
|
||||
* Write Atomicity: Provided by `NONE`. Write atomicity prevents reads
|
||||
from returning partially applied writes. Cassandra attempts to provide
|
||||
partition level write atomicity, but since only the data covered by a
|
||||
`SELECT` statement is repaired by a read repair, read repair can break
|
||||
write atomicity when data is read at a more granular level than it is
|
||||
written. For example read repair can break write atomicity if you write
|
||||
multiple rows to a clustered partition in a batch, but then select a
|
||||
single row by specifying the clustering column in a `SELECT` statement.
|
||||
|
||||
The available read repair settings are:
|
||||
|
||||
=== Blocking
|
||||
|
||||
The default setting. When `read_repair` is set to `BLOCKING`, and a read
|
||||
repair is started, the read will block on writes sent to other replicas
|
||||
until the CL is reached by the writes. Provides monotonic quorum reads,
|
||||
but not partition level write atomicity.
|
||||
|
||||
=== None
|
||||
|
||||
When `read_repair` is set to `NONE`, the coordinator will reconcile any
|
||||
differences between replicas, but will not attempt to repair them.
|
||||
Provides partition level write atomicity, but not monotonic quorum
|
||||
reads.
|
||||
|
||||
An example of using the `NONE` setting for the `read_repair` option is
|
||||
as follows:
|
||||
|
||||
[source,none]
|
||||
----
|
||||
CREATE TABLE ks.tbl (k INT, c INT, v INT, PRIMARY KEY (k,c)) with read_repair='NONE'");
|
||||
----
|
||||
|
||||
== Read Repair Example
|
||||
|
||||
To illustrate read repair with an example, consider that a client sends
|
||||
a read request with read consistency level `TWO` to a 5-node cluster as
|
||||
illustrated in Figure 1. Read consistency level determines how many
|
||||
replica nodes must return a response before the read request is
|
||||
considered successful.
|
||||
|
||||
image::Figure_1_read_repair.jpg[image]
|
||||
|
||||
Figure 1. Client sends read request to a 5-node Cluster
|
||||
|
||||
Three nodes host replicas for the requested data as illustrated in
|
||||
Figure 2. With a read consistency level of `TWO` two replica nodes must
|
||||
return a response for the read request to be considered successful. If
|
||||
the node the client sends request to hosts a replica of the data
|
||||
requested only one other replica node needs to be sent a read request
|
||||
to. But if the receiving node does not host a replica for the requested
|
||||
data the node becomes a coordinator node and forwards the read request
|
||||
to a node that hosts a replica. A direct read request is forwarded to
|
||||
the fastest node (as determined by dynamic snitch) as shown in Figure 2.
|
||||
A direct read request is a full read and returns the requested data.
|
||||
|
||||
image::Figure_2_read_repair.jpg[image]
|
||||
|
||||
Figure 2. Direct Read Request sent to Fastest Replica Node
|
||||
|
||||
Next, the coordinator node sends the requisite number of additional
|
||||
requests to satisfy the consistency level, which is `TWO`. The
|
||||
coordinator node needs to send one more read request for a total of two.
|
||||
All read requests additional to the first direct read request are digest
|
||||
read requests. A digest read request is not a full read and only returns
|
||||
the hash value of the data. Only a hash value is returned to reduce the
|
||||
network data traffic. In the example being discussed the coordinator
|
||||
node sends one digest read request to a node hosting a replica as
|
||||
illustrated in Figure 3.
|
||||
|
||||
image::Figure_3_read_repair.jpg[image]
|
||||
|
||||
Figure 3. Coordinator Sends a Digest Read Request
|
||||
|
||||
The coordinator node has received a full copy of data from one node and
|
||||
a hash value for the data from another node. To compare the data
|
||||
returned a hash value is calculated for the full copy of data. The two
|
||||
hash values are compared. If the hash values are the same no read repair
|
||||
is needed and the full copy of requested data is returned to the client.
|
||||
The coordinator node only performed a total of two replica read request
|
||||
because the read consistency level is `TWO` in the example. If the
|
||||
consistency level were higher such as `THREE`, three replica nodes would
|
||||
need to respond to a read request and only if all digest or hash values
|
||||
were to match with the hash value of the full copy of data would the
|
||||
read request be considered successful and the data returned to the
|
||||
client.
|
||||
|
||||
But, if the hash value/s from the digest read request/s are not the same
|
||||
as the hash value of the data from the full read request of the first
|
||||
replica node it implies that an inconsistency in the replicas exists. To
|
||||
fix the inconsistency a read repair is performed.
|
||||
|
||||
For example, consider that that digest request returns a hash value that
|
||||
is not the same as the hash value of the data from the direct full read
|
||||
request. We would need to make the replicas consistent for which the
|
||||
coordinator node sends a direct (full) read request to the replica node
|
||||
that it sent a digest read request to earlier as illustrated in Figure
|
||||
4.
|
||||
|
||||
image::Figure_4_read_repair.jpg[image]
|
||||
|
||||
Figure 4. Coordinator sends Direct Read Request to Replica Node it had
|
||||
sent Digest Read Request to
|
||||
|
||||
After receiving the data from the second replica node the coordinator
|
||||
has data from two of the replica nodes. It only needs two replicas as
|
||||
the read consistency level is `TWO` in the example. Data from the two
|
||||
replicas is compared and based on the timestamps the most recent replica
|
||||
is selected. Data may need to be merged to construct an up-to-date copy
|
||||
of data if one replica has data for only some of the columns. In the
|
||||
example, if the data from the first direct read request is found to be
|
||||
outdated and the data from the second full read request to be the latest
|
||||
read, repair needs to be performed on Replica 2. If a new up-to-date
|
||||
data is constructed by merging the two replicas a read repair would be
|
||||
needed on both the replicas involved. For example, a read repair is
|
||||
performed on Replica 2 as illustrated in Figure 5.
|
||||
|
||||
image::Figure_5_read_repair.jpg[image]
|
||||
|
||||
Figure 5. Coordinator performs Read Repair
|
||||
|
||||
The most up-to-date data is returned to the client as illustrated in
|
||||
Figure 6. From the three replicas Replica 1 is not even read and thus
|
||||
not repaired. Replica 2 is repaired. Replica 3 is the most up-to-date
|
||||
and returned to client.
|
||||
|
||||
image::Figure_6_read_repair.jpg[image]
|
||||
|
||||
Figure 6. Most up-to-date Data returned to Client
|
||||
|
||||
== Read Consistency Level and Read Repair
|
||||
|
||||
The read consistency is most significant in determining if a read repair
|
||||
needs to be performed. As discussed in Table 1 a read repair is not
|
||||
needed for all of the consistency levels.
|
||||
|
||||
Table 1. Read Repair based on Read Consistency Level
|
||||
|
||||
[width="93%",cols="35%,65%",]
|
||||
|===
|
||||
|Read Consistency Level |Description
|
||||
|
||||
|ONE |Read repair is not performed as the data from the first direct
|
||||
read request satisfies the consistency level ONE. No digest read
|
||||
requests are involved for finding mismatches in data.
|
||||
|
||||
|TWO |Read repair is performed if inconsistencies in data are found as
|
||||
determined by the direct and digest read requests.
|
||||
|
||||
|THREE |Read repair is performed if inconsistencies in data are found as
|
||||
determined by the direct and digest read requests.
|
||||
|
||||
|LOCAL_ONE |Read repair is not performed as the data from the direct
|
||||
read request from the closest replica satisfies the consistency level
|
||||
LOCAL_ONE.No digest read requests are involved for finding mismatches in
|
||||
data.
|
||||
|
||||
|LOCAL_QUORUM |Read repair is performed if inconsistencies in data are
|
||||
found as determined by the direct and digest read requests.
|
||||
|
||||
|QUORUM |Read repair is performed if inconsistencies in data are found
|
||||
as determined by the direct and digest read requests.
|
||||
|===
|
||||
|
||||
If read repair is performed it is made only on the replicas that are not
|
||||
up-to-date and that are involved in the read request. The number of
|
||||
replicas involved in a read request would be based on the read
|
||||
consistency level; in the example it is two.
|
||||
|
||||
== Improved Read Repair Blocking Behavior in Cassandra 4.0
|
||||
|
||||
Cassandra 4.0 makes two improvements to read repair blocking behavior
|
||||
(https://issues.apache.org/jira/browse/CASSANDRA-10726[CASSANDRA-10726]).
|
||||
|
||||
[arabic]
|
||||
. Speculative Retry of Full Data Read Requests. Cassandra 4.0 makes use
|
||||
of speculative retry in sending read requests (full, not digest) to
|
||||
replicas if a full data response is not received, whether in the initial
|
||||
full read request or a full data read request during read repair. With
|
||||
speculative retry if it looks like a response may not be received from
|
||||
the initial set of replicas Cassandra sent messages to, to satisfy the
|
||||
consistency level, it speculatively sends additional read request to
|
||||
un-contacted replica/s. Cassandra 4.0 will also speculatively send a
|
||||
repair mutation to a minority of nodes not involved in the read repair
|
||||
data read / write cycle with the combined contents of all
|
||||
un-acknowledged mutations if it looks like one may not respond.
|
||||
Cassandra accepts acks from them in lieu of acks from the initial
|
||||
mutations sent out, so long as it receives the same number of acks as
|
||||
repair mutations transmitted.
|
||||
. Only blocks on Full Data Responses to satisfy the Consistency Level.
|
||||
Cassandra 4.0 only blocks for what is needed for resolving the digest
|
||||
mismatch and wait for enough full data responses to meet the consistency
|
||||
level, no matter whether it’s speculative retry or read repair chance.
|
||||
As an example, if it looks like Cassandra might not receive full data
|
||||
requests from everyone in time, it sends additional requests to
|
||||
additional replicas not contacted in the initial full data read. If the
|
||||
collection of nodes that end up responding in time end up agreeing on
|
||||
the data, the response from the disagreeing replica that started the
|
||||
read repair is not considered, and won't be included in the response to
|
||||
the client, preserving the expectation of monotonic quorum reads.
|
||||
|
||||
== Diagnostic Events for Read Repairs
|
||||
|
||||
Cassandra 4.0 adds diagnostic events for read repair
|
||||
(https://issues.apache.org/jira/browse/CASSANDRA-14668[CASSANDRA-14668])
|
||||
that can be used for exposing information such as:
|
||||
|
||||
* Contacted endpoints
|
||||
* Digest responses by endpoint
|
||||
* Affected partition keys
|
||||
* Speculated reads / writes
|
||||
* Update oversized
|
||||
|
||||
== Background Read Repair
|
||||
|
||||
Background read repair, which was configured using `read_repair_chance`
|
||||
and `dclocal_read_repair_chance` settings in `cassandra.yaml` is removed
|
||||
Cassandra 4.0
|
||||
(https://issues.apache.org/jira/browse/CASSANDRA-13910[CASSANDRA-13910]).
|
||||
|
||||
Read repair is not an alternative for other kind of repairs such as full
|
||||
repairs or replacing a node that keeps failing. The data returned even
|
||||
after a read repair has been performed may not be the most up-to-date
|
||||
data if consistency level is other than one requiring response from all
|
||||
replicas.
|
||||
Loading…
Reference in New Issue