twitter icon linked-in icon youtube icon

Cassandra ドキュメント

バージョン

5.0

これはプレリリース版のドキュメントです。

ALTER TABLE

テーブルの列とプロパティを変更します。

新しい列の追加、既存の列の削除、列の名前変更、およびテーブルプロパティの変更を行います。コマンドは結果を返しません。

ALTER COLUMNFAMILY は非推奨です。

参照: CREATE TABLE, DROP TABLE, CREATE CUSTOM INDEX (Storage-Attached Indexes (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 ステートメントを終了します。

[--]

コマンドラインオプションをコマンド引数から区切るには、2 つのハイフン (--) を使用します。この構文は、引数がコマンドラインオプションと間違われる可能性がある場合に役立ちます。

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

検索 CQL のみ: 一重引用符 (') は、XML スキーマ宣言全体を囲みます。

@<xml_entity>='<xml_entity_type>'

検索 CQL のみ: スキーマファイルおよび solrConfig ファイルで XML 要素を上書きするエンティティとリテラル値を識別します。

必須パラメータ

table_name

変更するテーブルの名前。

column_name

変更、削除、または追加する列の名前。

column_definition

テーブル名の後の括弧で囲み、カンマ区切りのリストを使用して複数の列を定義します。すべてのテーブルには少なくとも1つのプライマリキー列が必要です。各列は次の構文を使用して定義します: column_name cql_type_definition [STATIC | PRIMARY KEY] [, ...]

制限事項

  • テーブルには少なくとも 1 つの PRIMARY KEY が必要です。

  • PRIMARY KEY が列定義の最後にある場合、その列はテーブルの唯一のプライマリキーであり、パーティションキー[パーティションキー]として定義されます。

  • 静的列はプライマリキーにできません。

  • プライマリキーには、フリーズされたコレクションを含めることができます。

    column_name

    テーブル内の各列に一意の名前を使用します。大文字小文字を保持するか、特殊文字を使用するには、名前を二重引用符で囲みます。

    cql_type_definition

    列で許可されるデータの型を定義します。CQL データ型またはユーザー定義型を参照してください。

    STATIC

    オプションで、列には単一の値があります。

    PRIMARY KEY

    PRIMARY KEY が 1 つの列の場合、列定義の最後に PRIMARY KEY を追加します。これは、テーブルを作成するために必要なスキーマ情報のみです。プライマリキーが 1 つの場合、それはパーティションキーです。データはこの列の一意の値によって分割および保存されます: column_name cql_type_definition PRIMARY KEY。

    または、複合プライマリキーを宣言するのと同じ方法で、1 つの列のみで構成されるプライマリキーを宣言することもできます。

オプションパラメータ

keyspace_name

変更するテーブルを含むキースペースの名前。名前が指定されていない場合、現在のキースペースが使用されます。

ADD ( <column_definition> | <column_definition_list> )

1つ以上の列を追加し、列のデータ型を設定します。列名の後にデータ型を指定します。列の値は自動的に null に設定されます。複数の列を追加するには、括弧内にカンマ区切りの列リストを使用します。

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

制限事項: テーブルの作成後、プライマリキーへの列の追加はサポートされていません。

DROP ( <column> | <column_list> )

1つ以上の列を削除します。行に含まれる値も削除され、回復できません。複数の列を削除するには、括弧内にカンマ区切りの列リストを使用します。

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（Time To Live）を秒単位で指定します。ゼロは無効を意味します。設定可能な最大値は630720000（20年）です。2018年以降、有効期限のタイムスタンプはストレージエンジンでサポートされる最大値を超える可能性があります。以下の警告を参照してください。値がゼロより大きい場合、テーブル全体でTTLが有効になり、各列に有効期限のタイムスタンプが追加されます。データが更新されるたびに新しいTTLタイムスタンプが計算され、すべてのデータの有効期限が切れると行が削除されます。

デフォルト値: 0 (無効)。

データベースのストレージエンジンは、2038年問題のため、TTLタイムスタンプを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

高速読み取り保護を設定します。通常の読み取りリクエストは、整合性レベルを満たすのに十分なレプリカノードにのみ送信されます。高速読み取り保護では、整合性レベルが満たされた後でも、追加の読み取りリクエストが他のレプリカに送信されます。speculative_retryプロパティは、これらの追加の読み取りリクエストのトリガーを指定します。

  • ALWAYS：コーディネーターノードは、そのテーブルの読み取りごとに、他のすべてのレプリカに追加の読み取りリクエストを送信します。

  • <X>パーセンタイル：各テーブルの典型的な読み取りレイテンシー（ミリ秒単位）を追跡します。コーディネーターノードは、読み取り中のテーブルの典型的なレイテンシー時間を取得し、その数値のXパーセントを計算します。コーディネーターは、応答なしに待機するミリ秒数が計算された数値を超える場合、冗長な読み取りリクエストを送信します。

    たとえば、Table_Aのspeculative_retryプロパティが80パーセンタイルに設定されており、そのテーブルの典型的なレイテンシーが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 = { <サブプロパティ名> : <値> [ , ... ] }

詳細については、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
};

投機的再試行の変更

投機的再試行の95パーセンタイルにcyclist_baseテーブルを変更します

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

投機的再試行に10ミリ秒を使用するようにcyclist_baseテーブルを変更します

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は連番）を作成します。

コンパクションロギングサービスは、次のタイプのコンパクションイベントに関する詳細情報を記録します

  • type:enable

    以前にフラッシュされた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"]
    }
 ]
}

  • type: flush

    各テーブルのCompactionStrategyを含め、memtableからディスク上の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

    コンパクションイベントをログに記録します。

    {"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

    コンパクション戦略の保留中のタスク数をリストします。

    {"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 Software Foundationは、Apache License 2.0の条件に基づいて運営されています。Apache、Apacheの羽根のロゴ、Apache Cassandra、Cassandra、およびCassandraのロゴは、Apache Software Foundationの登録商標または商標です。