twitter icon linked-in icon youtube icon

Cassandra 文件

版本

5.0

您正在檢視預發行版本的說明文件。

ALTER TABLE

修改表格的欄位和屬性。

新增欄位、刪除現有欄位、重新命名欄位，以及修改表格屬性。命令不會傳回任何結果。

ALTER COLUMNFAMILY 已停用。

另請參閱： CREATE TABLE、DROP TABLE、CREATE CUSTOM INDEX（適用於儲存器附加索引 (SAI)）、CREATE INDEX（適用於次要索引 (2i)）

語法

BNF 定義

alter_table_statement::= ALTER TABLE [ IF EXISTS ] table_name alter_table_instruction
alter_table_instruction::= ADD [ IF NOT EXISTS ] column_definition ( ',' column_definition)*
	| DROP [ IF EXISTS ] column_name ( ',' column_name )*
	| RENAME [ IF EXISTS ] column_name to column_name (AND column_name to column_name)*
	| ALTER [ IF EXISTS ] column_name ( column_mask | DROP MASKED )
	| WITH options
column_definition::= column_name cql_type [ column_mask]
column_mask::= MASKED WITH ( DEFAULT | function_name '(' term ( ',' term )* ')' )
ALTER TABLE [<keyspace_name>.]<table_name>
  [ ADD ( <column_definition> | <column_definition_list> ) [ , ... ] ]
  [ DROP <column_name> [ , ... ] ]
  [ [ RENAME <column_name> TO <column_name> ] ]
  [ WITH <table_properties> [ , ... ] ];
語法圖例
圖例
語法慣例 說明

大寫

文字關鍵字。

小寫

非文字。

< >

變數值。以使用者定義的值取代。

[]

選用。方括號 ([]) 包圍選用的命令引數。請勿輸入方括號。

( )

群組。括號 ( ( ) ) 識別可供選擇的群組。請勿輸入括號。

|

或。直線 (|) 分隔其他元素。輸入任一元素。請勿輸入直線。

...

可重複。省略號 ( ... ) 表示您可以根據需要重複語法元素。

'<文字字串>'

單引號 (') 標記必須包含 CQL 陳述式中的文字字串。使用單引號保留大寫。

{ <金鑰> : <值> }

地圖集合。大括號 ({ }) 包含地圖集合或鍵值對。冒號分隔鍵和值。

<datatype2

集合、清單、地圖或元組。尖括號 ( < > ) 包含集合、清單、地圖或元組中的資料類型。以逗號分隔資料類型。

<cql_statement>;

結束 CQL 陳述式。分號 (;) 終止所有 CQL 陳述式。

[--]

使用兩個連字號 ( -- ) 分隔命令列選項和命令引數。當引數可能被誤認為命令列選項時，此語法很有用。

' <<schema\> ... </schema\>> '

僅搜尋 CQL：單引號 (') 包圍整個 XML 架構宣告。

@<xml_entity>='<xml_entity_type>'

僅搜尋 CQL：識別實體和文字值以覆寫架構和 solrConfig 檔案中的 XML 元素。

必要參數

table_name

要變更的表格名稱。

column_name

要變更、刪除或新增的欄位名稱。

column_definition

在表格名稱後以括號括起來，使用逗號分隔清單來定義多個欄位。所有表格都必須至少有一個 主鍵 欄位。每個欄位使用下列語法定義：column_name cql_type_definition [STATIC | PRIMARY KEY] [, ...]

限制

  • 表格必須至少有一個 PRIMARY KEY。

  • 當 PRIMARY KEY 在欄位定義的結尾時，該欄位是表格唯一的 [分區鍵](https://cloud.google.com/bigtable/docs/overview#partitioning)（分區鍵）。

  • 靜態欄位不能是主鍵。

  • 主鍵可以包含凍結的集合。

    column_name

    對表格中的每個欄位使用唯一名稱。若要保留大小寫或使用特殊字元，請將名稱用雙引號括起來。

    cql_type_definition

    定義欄位中允許的資料類型。請參閱 CQL 資料類型 或 使用者定義的類型。

    STATIC

    選用，欄位有一個單一值。

    PRIMARY KEY

    當 PRIMARY KEY 是單一欄位時，將 PRIMARY KEY 附加到欄位定義的結尾。這只是建立表格所需的架構資訊。當有一個主鍵時，它就是分區鍵；資料會依據此欄位中的唯一值進行分割和儲存：column_name cql_type_definition PRIMARY KEY。

    或者，您可以宣告僅包含一欄的主鍵，方式與宣告複合主鍵相同。

選用參數

keyspace_name

包含要變更之資料表的鍵空間名稱。如果未指定名稱，則使用目前的鍵空間。

ADD ( <column_definition> | <column_definition_list> )

新增一或多個欄位，並設定欄位資料類型。指定欄位名稱，後接資料類型。欄位值會自動設定為 null。若要新增多個欄位，請使用置於括號內的逗號分隔欄位清單。

<column_name> <cql_type> [ , ]
[ <column_name> <cql_type> [ , ... ]

限制：在建立資料表後，不支援將欄位新增至主鍵。

DROP ( <column> | <column_list> )

刪除一或多個欄位。欄位中包含的值也會被刪除，且無法復原。若要刪除多個欄位，請使用置於括號內的逗號分隔欄位清單。

RENAME <column_name> TO <column_name>

變更主鍵欄位名稱，並保留現有值。

限制：不支援在具體化檢視基本資料表或具有次要索引的資料表上使用。

table_options

調整資料處理，包括 I/O 作業、壓縮和壓縮。資料表屬性選項使用下列語法

  • 單一值：<option_name> = '<value>'

  • 多個值：<option_name> = { '<subproperty>' : '<value>' [, ...] } [AND ...]

    簡單的 JSON 格式，以逗號分隔的清單中包含的鍵值對，並以大括號括住。

如果未指定值，則使用預設值。

在 CREATE TABLE (或 ALTER TABLE) CQL 陳述式中，使用 WITH 子句定義資料表屬性選項。使用 AND 分隔多個值。

CREATE TABLE [<keyspace_name>.]<table_name>
WITH option_name = '<value>'
AND option_name = {<option_map>};
bloom_filter_fp_chance = <N>

SSTable 布隆過濾器 的偽陽性機率。當客戶端要求資料時，布隆過濾器會在執行磁碟 I/O 之前檢查列是否存在。值介於 0 到 1.0，其中：0 是用於啟用最大布隆過濾器（使用最多記憶體）的最小值，而 1.0 是用於停用布隆過濾器的最大值。

建議設定：0.1。較高的值會產生遞減報酬。

預設值：bloom_filter_fp_chance = '0.01'

caching = { 'keys' : 'value', 'rows_per_partition' : 'value'}

最佳化快取記憶體的使用，無需手動調整。根據大小和存取頻率對快取資料加權。將此設定與 cassandra.yaml 檔案中的全域快取屬性配合使用。有效值

  • ALL-- 所有主鍵或列

  • NONE-- 沒有主鍵或列

  • <N>： （僅分區中的列） - 指定一個整數 預設： { 'keys': 'ALL', 'rows_per_partition': 'NONE' }

cdc

在資料表上建立變更資料擷取 (CDC) 記錄。

有效值

  • TRUE- 建立 CDC 記錄

  • FALSE- 不建立 CDC 記錄

comment = '說明資料表的文字'

提供資料表的說明文件。

輸入資料表設計為滿足的查詢類型說明。
default_time_to_live

以秒為單位的 TTL (生存時間)，其中零表示停用。可設定的最大值為 630720000 (20 年)。從 2018 年開始，到期時間戳記可能會超過儲存引擎支援的最大值；請參閱以下警告。如果值大於零，則會為整個資料表啟用 TTL，並將到期時間戳記新增至每個欄位。每次更新資料時，就會計算新的 TTL 時間戳記，且在所有資料到期後，就會移除列。

預設值： 0 (停用)。

由於 2038 年問題，資料庫儲存引擎只能對時間戳記編碼至 2038 年 1 月 19 日 03:14:07 UTC。TTL 日期溢位政策會決定是否拒絕或插入到期時間戳記晚於最大日期的請求。
gc_grace_seconds

資料標記為墓碑 (刪除標記) 後，符合垃圾回收資格前的秒數。預設值： 864000 (10 天)。預設值會讓資料庫有時間在刪除前最大化一致性。

寬限期內的墓碑記錄會從 提示 或 批次變更 中排除。

在單一節點叢集中，此屬性可以安全地設定為零。您也可以針對資料未明確刪除的資料表降低此值 - 例如，僅包含設定 TTL 的資料的資料表，或設定 default_time_to_live 的資料表。不過，如果您降低 gc_grace_seconds 值，請考慮它與這些操作的互動

  • 提示重播：當一個節點當機然後再重新啟動時，其他節點會重播在它沒有回應時排隊的寫入作業（稱為提示）。資料庫不會重播建立後超過 gc_grace_seconds 的提示。max_hint_window 設定在cassandra.yaml 檔案中設定收集沒有回應節點提示的時間限制（預設為 3 小時）。

  • 批次重播：就像提示佇列一樣，批次作業會儲存資料庫變更，這些變更會依序重播。與提示一樣，資料庫不會重播建立後超過 gc_grace_seconds 的批次變更。如果您的應用程式使用批次作業，請考慮減少 gc_grace_seconds 會增加批次寫入作業可能會還原已刪除資料的機會。cassandra.yaml 檔案中的 configuration/cass_yaml_file.html#batchlog_replay_throttle[batchlog_replay_throttle] 屬性可以控制批次重播程序。然而，最重要的因素是您使用的批次大小和範圍。

memtable_flush_period_in_ms

與資料表相關聯的memtable在清除之前的毫秒數。當 memtable_flush_period_in_ms=0 時，memtable 會在以下情況下清除

  • 達到清除閾值時

  • 關閉時

  • 在 nodetool flush 時

  • 當提交記錄填滿時 預設：0

min_index_interval

索引摘要中索引項目之間的最小差距。較低的 min_index_interval 表示索引摘要包含索引中的更多項目，這讓資料庫可以搜尋較少的索引項目來執行讀取。較大的索引摘要也可能使用更多記憶體。min_index_interval 的值是索引最密集的可能抽樣。

max_index_interval

如果所有索引摘要的總記憶體使用量達到這個值，Apache Cassandra 會將最冷 SSTable 的索引摘要減少到 max_index_interval 設定的最大值。max_index_interval 是與記憶體壓力相關的最稀疏可能抽樣。

speculative_retry

設定快速讀取保護。正常的讀取要求只會傳送給足夠的複本節點來滿足一致性層級。在快速讀取保護中，額外的讀取要求會傳送給其他複本，即使已經達到一致性層級。推測重試屬性會指定這些額外讀取要求的觸發器。

  • ALWAYS：協調節點會在每次讀取該資料表之後，將額外的讀取要求傳送給所有其他複本。

  • <X>百分位數：追蹤每個表格的典型讀取延遲時間（以毫秒為單位）。協調器節點會擷取正在讀取的表格的典型延遲時間，並計算該數值的 X 百分比。如果協調器等待回應的時間超過計算出的數值，協調器會傳送重複的讀取要求。

    例如，如果 Table_A 的 speculative_retry 屬性設為 80percentile，而該表格的典型延遲時間為 60 毫秒，則處理 Table_A 讀取的協調器節點會先傳送正常的讀取要求，如果在 48 毫秒（60 毫秒的 80%）內未收到任何回應，則會傳送重複的讀取要求。

  • <N> 毫秒：如果協調器節點在 N 毫秒內未收到任何回應，則協調器節點會傳送額外的讀取要求給所有其他複本。

  • NONE：協調器節點在讀取該表格後不會傳送額外的讀取要求。

壓縮策略

UCS

LCS

STCS

TWCS
table_properties

您可以修改現有表格的屬性。有些屬性是設為值的單一選項

<option_name> = <value> [ AND ... ]

例如，speculative_retry = '10ms'。將字串屬性的值用單引號括起來。

其他表格屬性使用 JSON 地圖設定：option_name = { <subproperty_name> : <value> [ , ... ] }

請參閱 table_options 以取得更多詳細資料。

使用注意事項

限制

  • 只能重新命名主鍵中的分群欄位。

  • 無法變更欄位的資料類型。

  • 對於有實體化檢視的表格，即使該欄位未用於實體化檢視，也無法從表格中刪除欄位。

  • 無法重新命名或刪除有依賴次要索引的欄位。

  • 請勿新增與現有欄位同名但資料類型不同的欄位。這會阻止提交記錄重播，並損毀舊資料的現有 SSTable。

範例

本節使用 cyclist_races 表格。

新增欄位

若要新增欄位，請使用 ADD 指令

ALTER TABLE cycling.cyclist_races
ADD manager UUID;

若要新增集合類型的欄位

ALTER TABLE cycling.cyclist_races
ADD completed list<text>;

此操作不會驗證現有資料。

限制：您無法使用 ADD 指令新增

  • 與現有欄位同名的欄位

  • 如果表格沒有叢集欄位，則為靜態欄位。

刪除欄位

若要從表格中移除欄位，請使用 DROP 指令

ALTER TABLE cycling.cyclist_races
DROP manager;

DROP 會從表格定義中移除欄位。刪除欄位後，該欄位將立即無法查詢。資料庫會在下一次壓縮期間刪除欄位資料。

限制

  • 如果您刪除欄位後又重新新增，Apache Cassandra 就不會還原刪除欄位之前寫入的值。

  • 請勿重新新增包含客戶端產生時間戳記的已刪除欄位；您可以重新新增包含由 寫入時間功能產生的時間戳記的欄位。

重新命名欄位

若要在 race_times 表格中重新命名欄位

ALTER TABLE cycling.race_times
RENAME race_date TO date;

限制：下列限制適用於 RENAME

  • 您只能重新命名叢集欄位，這些欄位是主鍵的一部分。

  • 您無法重新命名分割鍵，因為分割鍵會決定節點上的資料儲存位置。如果需要不同的分割名稱，則必須重新建立表格並移轉資料。

    由於 SSTable 是不可變的，因此在使用 RENAME 時有許多限制。若要變更磁碟上資料的狀態，必須重新寫入所有內容。

  • 您可以為重新命名的欄位建立索引。

  • 如果已在欄位上建立索引，則無法重新命名該欄位。

  • 您無法重新命名靜態欄位。

修改表格屬性

若要變更現有表格的屬性，請使用 ALTER TABLE 和 WITH。您可以指定

例如，若要使用 WITH 新增註解至 cyclist_base 表格

ALTER TABLE cycling.cyclist_base
WITH comment = 'basic cyclist information';

將文字屬性值置於單引號中。

修改壓縮和壓實

使用屬性對應來變更 comments 表格的壓縮或壓實設定

ALTER TABLE cycling.cyclist_base
WITH comment = 'basic cyclist information';

將每個金鑰的名稱用單引號括起來。如果值是字串，也將字串用引號括起來。

如果您變更具有現有資料的表格的壓實策略，資料庫會使用新的策略重寫所有現有的 SSTable。這可能需要數小時，對生產系統而言可能會造成重大問題。如需將此中斷降至最低的策略，請參閱 如何變更生產叢集上的壓實策略 和 變更壓實策略的影響。

變更快取

將 comments 表格中每個分區要儲存在列快取中的列數設定為 10 列

ALTER TABLE cycling.comments
WITH caching = {
  'keys' : 'NONE',
  'rows_per_partition' : 10
};

變更推測重試

將 `cyclist_base` 表格修改為第 95 個百分位數以進行推測重試

ALTER TABLE cycling.cyclist_base
WITH speculative_retry = '95percentile';

將 `cyclist_base` 表格修改為使用 10 毫秒進行推測重試

ALTER TABLE cycling.cyclist_base
WITH speculative_retry = '10ms';

啟用和停用背景壓實

下列範例將 `enabled` 屬性設定為 `false` 以停用背景壓實

ALTER TABLE cycling.comments
WITH COMPACTION = {
  'class' : 'SizeTieredCompactionStrategy',
  'enabled' : 'false'
};

停用背景壓實可能會造成危害：沒有背景壓實，資料庫不會回收磁碟空間，並可能允許 殭屍 蔓延。儘管壓實會使用 I/O，但在大多數情況下最好讓它保持啟用狀態。

讀取延伸壓實記錄

將 `log_all` 子屬性設定為 `true` 以在專用記錄檔中收集節點上壓實活動的深入資訊。

如果您在任何節點上任何表格中啟用延伸壓實記錄，則會在叢集中的所有節點上所有表格中啟用。

當啟用延伸壓實時，資料庫會在 home/logs 中建立一個名為 compaction-%d.log 的檔案（其中 `%d` 是順序編號）。

壓縮記錄服務記錄下列壓縮事件類型的詳細資訊

  • 類型：啟用

    列出先前已快取的 SSTable。

    {"type":"enable","keyspace":"test","table":"t","time":1470071098866,"strategies":
  [    {"strategyId":"0","type":"LeveledCompactionStrategy","tables":[],"repaired":true,"folders":
      ["/home/carl/oss/cassandra/bin/../data/data"]},
    {"strategyId":"1","type":"LeveledCompactionStrategy","tables":[],"repaired":false,"folders":
      ["/home/carl/oss/cassandra/bin/../data/data"]
    }
 ]
}

  • 類型：快取

    記錄從記憶體表格快取到磁碟上 SSTable 的快取事件，包括每個表格的壓縮策略。

    {"type":"flush","keyspace":"test","table":"t","time":1470083335639,"tables":
  [    {"strategyId":"1","table":
      {"generation":1,"version":"mb","size":106846362,"details":
        {"level":0,"min_token":"-9221834874718566760","max_token":"9221396997139245178"}
      }
    }
 ]
}

  • 類型：壓縮

    記錄壓縮事件。

    {"type":"compaction","keyspace":"test","table":"t","time":1470083660267,
 "start":"1470083660188","end":"1470083660267","input":
  [    {"strategyId":"1","table":
      {"generation":1372,"version":"mb","size":1064979,"details":
        {"level":1,"min_token":"7199305267944662291","max_token":"7323434447996777057"}
      }
    }
 ],"output":
  [    {"strategyId":"1","table":
      {"generation":1404,"version":"mb","size":1064306,"details":
        {"level":2,"min_token":"7199305267944662291","max_token":"7323434447996777057"}
      }
    }
 ]
}

  • 類型：待處理

    列出壓縮策略的待處理任務數目。

    {"type":"pending","keyspace":"test","table":"t",
 "time":1470083447967,"strategyId":"1","pending":200}

檢閱表格定義

使用 DESCRIBE 或 DESC 查看表格定義。

DESC cycling.comments;

會傳回表格詳細資料，包括欄位名稱。

CREATE TABLE cycling.comments (
    id uuid,
    created_at timestamp,
    comment text,
    commenter text,
    record_id timeuuid,
    PRIMARY KEY (id, created_at)
) WITH CLUSTERING ORDER BY (created_at DESC)
    AND bloom_filter_fp_chance = 0.01
    AND caching = {'keys': 'NONE', 'rows_per_partition': '10'}
    AND comment = ''
    AND compaction = {'class': 'org.apache.cassandra.db.compaction.SizeTieredCompactionStrategy', 'enabled': 'true', 'max_threshold': '32', 'min_threshold': '4'}
    AND compression = {'chunk_length_in_kb': '64', 'class': 'org.apache.cassandra.io.compress.DeflateCompressor'}
    AND crc_check_chance = 1.0
    AND default_time_to_live = 0
    AND gc_grace_seconds = 864000
    AND max_index_interval = 2048
    AND memtable_flush_period_in_ms = 0
    AND min_index_interval = 128
    AND speculative_retry = '99PERCENTILE';
ASF
基礎
活動
授權
感謝
安全性
隱私權
贊助

© 2009- Apache 軟體基金會根據 Apache 授權 2.0 的條款。Apache、Apache 羽毛標誌、Apache Cassandra、Cassandra 和 Cassandra 標誌，都是 Apache 軟體基金會的註冊商標或商標。