diff --git a/docs/architecture/sstable/_common/sstable_what_is.rst b/docs/architecture/sstable/_common/sstable_what_is.rst index 3270014513..dd35a58f87 100644 --- a/docs/architecture/sstable/_common/sstable_what_is.rst +++ b/docs/architecture/sstable/_common/sstable_what_is.rst @@ -4,6 +4,11 @@ The location of ScyllaDB SSTables is specified in scylla.yaml ``data_file_direct SSTable 3.x is more efficient and requires less disk space than the SSTable 2.x. +For more information on each of the SSTable formats, see below: + +* :doc:`SSTable 2.x ` +* :doc:`SSTable 3.x ` + SSTable Version Support ------------------------ @@ -13,11 +18,11 @@ SSTable Version Support * - SSTable Version - ScyllaDB Version - * - 3.x ('ms') + * - 3.x (``ms``) - 2025.4 and above - * - 3.x ('me') + * - 3.x (``me``) - 2022.2 and above - * - 3.x ('md') + * - 3.x (``md``) - 2021.1 * The supported formats are ``me`` and ``ms``. @@ -27,3 +32,10 @@ SSTable Version Support **writes**. The legacy SSTable formats (``ka``, ``la``, ``mc``) remain supported for reads, which is essential for restoring clusters from existing backups. + +The ms Format: Trie-Based SSTable Index +----------------------------------------- + +The ``ms`` format introduces a *trie-based* SSTable index. + +For a detailed description of the trie index format, see :doc:`SSTable ms Index `. \ No newline at end of file diff --git a/docs/architecture/sstable/index.rst b/docs/architecture/sstable/index.rst index 1c0587c384..88d61b687e 100644 --- a/docs/architecture/sstable/index.rst +++ b/docs/architecture/sstable/index.rst @@ -7,9 +7,4 @@ ScyllaDB SSTable Format sstable2/index sstable3/index -.. include:: _common/sstable_what_is.rst - -For more information on each of the SSTable formats, see below: - -* :doc:`SSTable 2.x ` -* :doc:`SSTable 3.x ` +.. include:: _common/sstable_what_is.rst \ No newline at end of file diff --git a/docs/architecture/sstable/sstable3/index.rst b/docs/architecture/sstable/sstable3/index.rst index bbd9369268..e9c6e769e6 100644 --- a/docs/architecture/sstable/sstable3/index.rst +++ b/docs/architecture/sstable/sstable3/index.rst @@ -8,6 +8,7 @@ ScyllaDB SSTable - 3.x sstables-3-statistics sstables-3-summary sstables-3-index + sstable-ms-index sstable-format .. include:: ../_common/sstable_what_is.rst @@ -20,5 +21,6 @@ For more information on ScyllaDB 3.x SSTable formats, see below: * :doc:`SSTable 3.0 Data File Format ` * :doc:`SSTable 3.0 Statistics ` * :doc:`SSTable 3.0 Summary ` -* :doc:`SSTable 3.0 Index ` -* :doc:`SSTable 3.0 Format in ScyllaDB ` +* :doc:`SSTable 3.0 Index (me/md format) ` +* :doc:`SSTable ms Index (Trie-Based) ` +* :doc:`SSTable 3.0 Format in ScyllaDB ` \ No newline at end of file diff --git a/docs/architecture/sstable/sstable3/sstable-format.rst b/docs/architecture/sstable/sstable3/sstable-format.rst index 54363bf230..37ba12e992 100644 --- a/docs/architecture/sstable/sstable3/sstable-format.rst +++ b/docs/architecture/sstable/sstable3/sstable-format.rst @@ -9,8 +9,28 @@ Looking more carefully, you will see that ScyllaDB maintains more, smaller, SSTables than Cassandra does. On ScyllaDB, each core manages its own subset of SSTables. This internal sharding allows each core (shard) to work more efficiently, avoiding the complexity and delays of multiple -cores competing for the same data +cores competing for the same data. + +SSTable Format Variants +------------------------ + +ScyllaDB 3.x SSTables come in three format variants, selected via the ``sstable_format`` +parameter in ``scylla.yaml``: + +``ms`` + Introduces a trie-based SSTable index. + For details, see :doc:`SSTable ms Index (Trie-Based) `. + +``me`` + The baseline 3.x format, default from ScyllaDB 2022.2 through 2026.1. + +``md`` + An earlier 3.x variant. Only used when upgrading from an existing ``md`` cluster. + The ``sstable_format`` parameter is ignored if set to ``md``. + +Existing SSTables are not rewritten automatically when upgrading to 2026.2. +They are upgraded to the ``ms`` format on the next compaction. .. include:: /rst_include/architecture-index.rst -.. include:: /rst_include/apache-copyrights.rst +.. include:: /rst_include/apache-copyrights.rst \ No newline at end of file diff --git a/docs/architecture/sstable/sstable3/sstable-ms-index.rst b/docs/architecture/sstable/sstable3/sstable-ms-index.rst new file mode 100644 index 0000000000..1640966f46 --- /dev/null +++ b/docs/architecture/sstable/sstable3/sstable-ms-index.rst @@ -0,0 +1,47 @@ +.. _sstable-ms-index: + +SSTable ms Index: Trie-Based Format +===================================== + +The ``ms`` format introduces a trie-based partition index, replacing the previous +Cassandra 3.0 index format used by ``me`` and ``md``. + +Benefits +--------- + +Compared to the previous format, the trie-based index provides: + +* **Reduced memory footprint** - less in-memory index data per SSTable. +* **Faster partition lookups** - more efficient index traversal. +* **Smaller on-disk index files** - shared key prefixes reduce redundant storage. + +Configuring ms Format +---------------------- + +New Clusters (2026.2 and Later) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Starting with ScyllaDB 2026.2, ``ms`` is the default value for ``sstable_format`` in the +default ``scylla.yaml``. Clusters created with ScyllaDB 2026.2 use the ``ms`` format unless +the configuration is changed. + +Upgraded Clusters +~~~~~~~~~~~~~~~~~~ + +Clusters upgraded from an earlier version continue to use the format specified in their +``scylla.yaml``. To switch to the ``ms`` format, add the following to ``scylla.yaml``: + +.. code-block:: yaml + + sstable_format: ms + +After the node configuration is updated, newly created SSTables will use the ``ms`` format. + +Existing SSTables are not automatically converted. They will be rewritten in ``ms`` format +during the next compaction. Conversion can be triggered using ``nodetool upgradesstables -a`` +after updating the node configuration. + +Related Topics +-------------- + +* :doc:`SSTable 3.0 Format in ScyllaDB ` - overview of 3.x format variants \ No newline at end of file