From e5f99c5cc560dea7a05507c7b99c4a0c79379ffb Mon Sep 17 00:00:00 2001 From: Bernardo Botella Corbi Date: Mon, 16 Jun 2025 15:50:52 +0200 Subject: [PATCH] CASSANDRA-20699 Fix SAI virtual table names in documentation patch by Soheil Rahsaz; reviewed by Bernardo Botella and Caleb Rackliffe for CASSANDRA-20699 --- .../indexing/sai/operations/monitoring.adoc | 6 +- .../reference/sai-virtual-table-indexes.adoc | 82 +++++++------------ .../partials/sai/queryable-paragraph.adoc | 4 +- 3 files changed, 35 insertions(+), 57 deletions(-) diff --git a/doc/modules/cassandra/pages/developing/cql/indexing/sai/operations/monitoring.adoc b/doc/modules/cassandra/pages/developing/cql/indexing/sai/operations/monitoring.adoc index 4cc645f18b..d2f682163d 100644 --- a/doc/modules/cassandra/pages/developing/cql/indexing/sai/operations/monitoring.adoc +++ b/doc/modules/cassandra/pages/developing/cql/indexing/sai/operations/monitoring.adoc @@ -8,7 +8,7 @@ Both virtual tables and JMX-based metrics can be used to monitor the SAI indexes You can refer to data in the following {product} virtual tables to determine the status of indexes created with SAI: -* `system_views.indexes` -- provides information at the column index level, including the index name, number of indexed SSTables, disk usage, and index state. +* `system_views.sai_column_indexes` -- provides information at the column index level, including the index name and index state. From the index state, the data reveals if the index is currently building, and whether the index can be queried. + [TIP] @@ -16,8 +16,8 @@ From the index state, the data reveals if the index is currently building, and w include::cassandra:partial$sai/queryable-paragraph.adoc[] ==== -* `system_views.sstable_indexes` -- describes individual SSTable indexes, and includes information around disk size, min/max row ID, the min/max ring token, and the write-time version of the index. -* `system_views.sstable_index_segments` -- describes the segments of the SSTable indexes. +* `system_views.sai_sstable_indexes` -- describes individual SSTable indexes, and includes information around disk size, min/max row ID, the min/max ring token, and the write-time version of the index. +* `system_views.sai_sstable_index_segments` -- describes the segments of the SSTable indexes. It exposes the segment row ID offset and most of the information in the SSTable-level virtual table, specifically at a segment granularity. For more details, refer to xref:cassandra:reference/sai-virtual-table-indexes.adoc[Virtual tables for SAI indexes and SSTables]. diff --git a/doc/modules/cassandra/pages/reference/sai-virtual-table-indexes.adoc b/doc/modules/cassandra/pages/reference/sai-virtual-table-indexes.adoc index b273988123..3f9bae40e1 100644 --- a/doc/modules/cassandra/pages/reference/sai-virtual-table-indexes.adoc +++ b/doc/modules/cassandra/pages/reference/sai-virtual-table-indexes.adoc @@ -4,12 +4,12 @@ Storage Attached Indexing (SAI) provides CQL-based virtual tables that enable you to discover the current state of system metadata for SAI indices and associated SSTables. These virtual tables reside in the `system_views` keyspace. -For related information, see the xref:cassandra:developing/indexing/sai/sai-overview.adoc[SAI information]. +For related information, see the xref:cassandra:developing/cql/indexing/sai/sai-overview.adoc[SAI information]. -== system_views.indexes +== system_views.sai_column_indexes -The `system_views.indexes` virtual table contains stateful information about SAI indexes. -This view provides information at the column index level, including the index name, number of indexed SSTables, disk usage, and index state. +The `system_views.sai_column_indexes` virtual table contains stateful information about SAI indexes. +This view provides information at the column index level, including the index name and index state. From the index state, the data reveals if the index is currently building, and whether the index can be queried. Use CQL to view the table's description. @@ -17,26 +17,22 @@ Example: [source,language-cql] ---- -DESCRIBE TABLE system_views.indexes; +DESCRIBE TABLE system_views.sai_column_indexes; ---- [source,results] ---- /* -Warning: Table system_views.indexes is a virtual table and cannot be recreated with CQL. +Warning: Table system_views.sai_column_indexes is a virtual table and cannot be recreated with CQL. Structure, for reference: -VIRTUAL TABLE system_views.indexes ( +VIRTUAL TABLE system_views.sai_column_indexes ( keyspace_name text, index_name text, analyzer text, - cell_count bigint, column_name text, - indexed_sstable_count int, is_building boolean, is_queryable boolean, is_string boolean, - per_column_disk_size bigint, - per_table_disk_size bigint, table_name text, PRIMARY KEY (keyspace_name, index_name) ) WITH CLUSTERING ORDER BY (index_name ASC) @@ -48,22 +44,22 @@ To view the current data, submit a query such as: [source,language-cql] ---- -SELECT * FROM system_views.indexes; +SELECT * FROM system_views.sai_column_indexes; ---- [source,results] ---- - keyspace_name | index_name | analyzer | cell_count | column_name | indexed_sstable_count | is_building | is_queryable | is_string | per_column_disk_size | per_table_disk_size | table_name ----------------+----------------------+-------------------------------------------------------------+------------+--------------+-----------------------+-------------+--------------+-----------+----------------------+---------------------+------------------ - cycling | age_sai_idx | NoOpAnalyzer{} | 0 | age | 0 | False | True | False | 0 | 0 | cyclist_semi_pro - cycling | country_sai_idx | NonTokenizingAnalyzer{caseSensitive=false, normalized=true} | 0 | country | 0 | False | True | True | 0 | 0 | cyclist_semi_pro - cycling | lastname_sai_idx | NonTokenizingAnalyzer{caseSensitive=false, normalized=true} | 0 | lastname | 0 | False | True | True | 0 | 0 | cyclist_semi_pro - cycling | registration_sai_idx | NoOpAnalyzer{} | 0 | registration | 0 | False | True | False | 0 | 0 | cyclist_semi_pro + keyspace_name | index_name | analyzer | column_name | is_building | is_queryable | is_string | table_name +---------------+----------------------+-------------------------------------------------------------+--------------+-------------+--------------+-----------+------------------ + cycling | age_sai_idx | NoOpAnalyzer{} | age | False | True | False | cyclist_semi_pro + cycling | country_sai_idx | NonTokenizingAnalyzer{caseSensitive=false, normalized=true} | country | False | True | True | cyclist_semi_pro + cycling | lastname_sai_idx | NonTokenizingAnalyzer{caseSensitive=false, normalized=true} | lastname | False | True | True | cyclist_semi_pro + cycling | registration_sai_idx | NoOpAnalyzer{} | registration | False | True | False | cyclist_semi_pro (4 rows) ---- -.system_views.indexes metadata +.system_views.sai_column_indexes metadata [%header, cols="14,10,30"] |=== h| Column name | CQL type | Meaning @@ -80,20 +76,10 @@ h| Column name | CQL type | Meaning | `text` | The `toString` representation of the analyzer used by the index. -| `cell_count` -| `bigint` -| The number of indexed table cells, or the number of index value-key entries. -This is the sum of the number of index entries in each SSTable. - | `column_name` | `text` | The name of the indexed column. -| `indexed_sstable_count` -| `int` -| The number of indexed SSTables. -Note that SSTables without relevant data won't be indexed or counted here. - | `is_building` | `boolean` | Whether there is a on going build for the index. @@ -107,22 +93,14 @@ It won't be possible if the initial task build hasn't finished yet. | `boolean` | Whether the index is for a text field (`ascii`, `text`, or `varchar`). -| `per_column_disk_size` -| `bigint` -| The on-disk size of the index components that are exclusive to the column, in bytes. - -| `per_table_disk_size` -| `bigint` -| The on-disk size of the index components that are shared with other SAI indexes for the same table, in bytes. - | `table_name` | `text` | The name of the table to which the indexed column belongs. |=== -== system_views.sstable_indexes +== system_views.sai_sstable_indexes -The `system_views.sstable_indexes` virtual table has a row per SAI index and SSTable. +The `system_views.sai_sstable_indexes` virtual table has a row per SAI index and SSTable. This view describes individual SSTable indexes, and includes information around disk size, min/max row ID, the min/max ring token, and the write-time version of the index. Use CQL to view the table's description. @@ -130,15 +108,15 @@ Example: [source,language-cql] ---- -DESCRIBE TABLE system_views.sstable_indexes; +DESCRIBE TABLE system_views.sai_sstable_indexes; ---- [source,results] ---- /* -Warning: Table system_views.sstable_indexes is a virtual table and cannot be recreated with CQL. +Warning: Table system_views.sai_sstable_indexes is a virtual table and cannot be recreated with CQL. Structure, for reference: -VIRTUAL TABLE system_views.sstable_indexes ( +VIRTUAL TABLE system_views.sai_sstable_indexes ( keyspace_name text, index_name text, sstable_name text, @@ -162,10 +140,10 @@ To view the current data, submit a query such as: [source,language-cql] ---- -SELECT * FROM system_views.sstable_indexes; +SELECT * FROM system_views.sai_sstable_indexes; ---- -.system_views.sstable_indexes metadata< +.system_views.sai_sstable_indexes metadata< [%header, cols="14,10,30"] |=== h| Column name | CQL type | Meaning @@ -219,9 +197,9 @@ h| Column name | CQL type | Meaning | The name of the table to which the indexed column belongs. |=== -== system_views.sstable_index_segments +== system_views.sai_sstable_index_segments -The `system_views.sstable_index_segments` virtual table has a row per SAI index and SSTable segment. +The `system_views.sai_sstable_index_segments` virtual table has a row per SAI index and SSTable segment. This view describes the segments of the SSTable indexes. It exposes the segment row ID offset and most of the information in the SSTable-level virtual table, specifically at a segment granularity. @@ -230,22 +208,22 @@ Example: [source,language-cql] ---- -DESCRIBE TABLE system_views.sstable_index_segments; +DESCRIBE TABLE system_views.sai_sstable_index_segments; ---- [source,results] ---- /* -Warning: Table system_views.sstable_index_segments is a virtual table and cannot be recreated with CQL. +Warning: Table system_views.sai_sstable_index_segments is a virtual table and cannot be recreated with CQL. Structure, for reference: -VIRTUAL TABLE system_views.sstable_index_segments ( +VIRTUAL TABLE system_views.sai_sstable_index_segments ( keyspace_name text, index_name text, sstable_name text, segment_row_id_offset bigint, cell_count bigint, column_name text, - component_metadata frozen>>, + component_metadata frozen>>>, end_token text, max_sstable_row_id bigint, max_term text, @@ -263,10 +241,10 @@ To view the current data, submit a query such as: [source,language-cql] ---- -SELECT * FROM system_views.sstable_index_segments; +SELECT * FROM system_views.sai_sstable_index_segments; ---- -.system_views.sstable_index_segments metadata +.system_views.sai_sstable_index_segments metadata [%header, cols="10,11,17"] |=== h| Column name | CQL type | Meaning diff --git a/doc/modules/cassandra/partials/sai/queryable-paragraph.adoc b/doc/modules/cassandra/partials/sai/queryable-paragraph.adoc index 0ef92638a5..fd72a74ca7 100644 --- a/doc/modules/cassandra/partials/sai/queryable-paragraph.adoc +++ b/doc/modules/cassandra/partials/sai/queryable-paragraph.adoc @@ -1,10 +1,10 @@ When you `DROP` / recreate an SAI index, you are not blocked from entering queries that do not use the index. However, you cannot use that SAI index (based on the same column) until it has finished building and is queryable. -To determine the current state of a given index, query the `system_views.indexes` virtual table. +To determine the current state of a given index, query the `system_views.sai_column_indexes` virtual table. Example: [source,language-cql] ---- -SELECT is_queryable,is_building FROM system_views.indexes WHERE keyspace_name='keyspace' +SELECT is_queryable,is_building FROM system_views.sai_column_indexes WHERE keyspace_name='keyspace' AND table_name='table' AND index_name='index'; ----