0.7より前のリリースではCassandraのストレージ設定はconf/storage-conf.xmlに記述されていました。バージョン0.7では、ストレージ設定はconf/cassandra.yamlに記述されます。

設定の読み込み

config-converter

• bin/config-converterはstorage-conf.xmlを可能な限り忠実にYAML形式に変換します。このツールはあなたのxmlファイルがconf/storage-conf.xmlに配置されており、また出力先がconf/cassandra.yamlであることを想定しています。ただし、0.7において多くのプロパティのスコープが変更されたため（例えば、endpoint_snitchはKS単位ではなくグローバルスコープに、gc_grace_secondsはグローバルからKeyspace単位に変わっています）、自動生成されたyamlファイルは使用前に必ず精査してください。

-Dcassandra.config

• Cassandraの起動時に、Java VMのパラメータとして渡すことにより、任意の設定ファイルをロードすることができます。具体的には、-Dcassandra.conf=<your value here>という形式でパラメータを与えます。値にはclasspath上のファイル、ローカル又はリモートのURLを指定できます。幾つかの例を次に示します：

  値	意味
  -Dcassandra.config=alternate-cassandra.yaml	cassandraのclasspath上に alternate-cassandra.yaml が存在すればそれをロードします。
  -Dcassandra.config=http://www.example.com/remote-cassandra.yaml	リモートホストから設定ファイルをロードします。
  -Dcassandra.config=file:///home/me/external-local-cassandra.yaml	cassandraのclasspath上にないローカルの設定ファイルをロードします。

"私のkeyspaceはどこ?"

• LiveSchemaUpdates。次のコマンドでスキーマを一度にロードすることができます。:

  bin/schematool HOST PORT import

設定の概要

• ここでは重要な設定項目にのみ絞って解説し、すべての設定値についてはカバーしません。疑問があれば、標準のcassandra.yamlに豊富に記述されているコメントを確認してください。

クラスタ単位（グローバル）の設定

• authenticator

  • プラグイン可能なユーザ認証を指定します。ここではThriftの'login'メソッド呼び出しの必要性の有無、またログイン時に必要なパラメータについて定義します。デフォルトの'AllowAllAuthenticator'を使用した場合、ユーザは'login'メソッドを呼ぶ必要がありません。即ち、すべてのユーザが任意の捜査を実行可能です。他のビルトインのオプションには'SimpleAuthenticator'があります。このユーザ認証設定ではユーザはloginを呼び出す必要があり、プロパティファイルに設定されたユーザ名とパスワードが必要になります。

    プロパティ名	デフォルト値
    authenticator	org.apache.cassandra.auth.AllowAllAuthenticator

• auto_bootstrap

  • seedノード以外の新規ノードについて、この設定を'true'に指定して起動することにより、そのノードは自動的に適切なデータをレプリケートします。（InitialTokenが指定されていない場合、追加されたノードは最も収容量の多いノードの半分のTokenレンジを引き受けます。）ブートストラップなしでノードを起動した場合、以降のブートストラップの際に誤って使用されないように、自分自身をブートストラップ済みとしてマークします。（データとcommitlogディレクトリを削除すればリセットできます。） 既にデータが格納されているクラスタに新しいノードを追加する場合は、これを'true'に設定すべきです。

    プロパティ名	デフォルト値
    auto_bootstrap	false

• cluster_name

  • クラスタの名称です。ノードが誤って他の論理クラスタに参加しないようにするために使用されます。

• commitlog_directory、data_file_directories、saved_caches_directory

  • できるだけcommitlog用のディスクとデータ格納用のディスクは分けてください。commitlogの性能は「追記のみ」という動作に依存しており、データに対するランダムアクセスと混在させた場合書き込み性能に悪影響を与えます。'saved_caches_directory' にはカラムファミリの 'savedキャッシュ' が保存されます。詳しくは 'key/row_cache_save_period_in_seconds' を参照してください。

    プロパティ名	デフォルト値
    commitlog_directory	/var/lib/cassandra/commitlog
    data_file_directories	/var/lib/cassandra/data
    saved_caches_directory	/var/lib/cassandra/saved_caches

• concurrent_reads and concurrent_writes

  • 多くのシステムと異なり、CassandraではReadよりWriteのほうが速いため、より多くのWriteを並列に実行できます。経験則に従えば、一つのプロセッサコアごとにconcurrent_readsを4つづつ増やせばよいと思います。Write性能が問題になるまで'concurrent_writes'はいじらないほうがいいでしょう。とはいえ、一般的にはCassandraクラスタ専用環境ではリングのCPUコア数の合計以上の値にするとよいでしょう。

    プロパティ名	デフォルト値
    concurrent_reads	8
    concurrent_writes	32

• commitlog_rotation_threshold_in_mb、commitlog_sync、commitlog_sync_period_in_ms、 commitlog_sync_batch_window_in_ms

  • commitlog_rotation_threshold_in_mb はどのくらいの頻度で新しいcommitlogセグメントが生成されるかを決定します。一般的にはこの値を変更すべきではありませんが、この値を小さくすると僅かではありますがシステムのメモリ使用量を節約できます。

    CommitLogSync には periodic か batch を指定できます。batchモードではCassandraはcommitlogがfsyncされるまでwrite ackを返しません。CommitLogSyncBatchWindowInMS ミリ秒の間他のwriteが到着するのを待ったあと、fsyncを実行します。

    Cassandraはwriteを複数のノードに対して実施するため「writeしたデータが物理的にディスクに格納される前」の障害でデータが失われる危険性は実際には一般的なデータベースほど顕著ではありません。もう一つのオプション'periodic'を選択するとwriteに対して直ちにackを返します。CommitLog は単純にCommitLogSyncPeriodInMs ミリ秒ごとにfsyncされます。通常はデフォルト値の1000msで問題ないでしょう。JMXでCommitLog PendingTasksを監視して、一つのsyncが完了する前に次のsyncが発生する状況が多発しているようであればこの値を増やすことを検討してください。

    プロパティ名	デフォルト値
    commitlog_rotation_threshold_in_mb	128
    commitlog_sync	periodic
    commitlog_sync_period_in_ms	1000

• disk_access_mode

  • 0.7ではデフォルト値の 'auto' が推奨値です。

• dynamic_snitch and endpoint_snitch

  • endpoint_snitch: このプロパティに IEndPointSnitch を実装したクラスを指定することにより、2つのノードが同じデータセンターに存在するか、あるいは同じラックに収容されているかの判定条件を制御できます。Cassandraパッケージのorg.apache.cassandra.locator以下に4種類のSnitchが標準で添付されています。

  • org.apache.cassandra.locator.SimpleSnitch 何もしません。

  • org.apache.cassandra.locator.RackInferringSnitch IPアドレスの第2オクテットがデータセンター、第3オクテットがラックに対応すると仮定して判定します。

  • org.apache.cassandra.locator.PropertyFileSnitch cassandra-topology.propertiesに明示的に設定された近傍定義（proximities）に従います。

  • org.apache.cassandra.locator.Ec2Snitch Amazon EC2ノードからリージョンとゾーンを読み取り、それらをデータセンターとラックと見なします。あなたの環境をEC2で動かしていない場合には使用しないでください。

    dynamic_snitch: 上記のsnitchをdynamic snitchでラッピングするかどうかを指定するbooleanです。dynamic snitchは対向ノードの読み込み遅延を監視し、遅いノードからの読み出しを避けます。

    プロパティ名	デフォルト値
    endpoint_snitch	org.apache.cassandra.locator.SimpleSnitch
    dynamic_snitch	false

• listen_address

  • このプロパティをコメントアウトするとInetAddress.getLocalHost()が使用されます。ノードのネットワーク設定が正しければこれでうまく動きます。（hostnameに紐づいたアドレスを使用します。）クラウドサービス上でシステムを構築する場合は正しいインターフェースを明示的に指定した方がいいでしょう。

    プロパティ名	デフォルト値
    listen_address	localhost （他のホストからこのノードにアクセスする為には、この値を変更する必要があります。）

• memtable_flush_after_mins、memtable_operations_in_millions、memtable_throughput_in_mb

  • memtable_flush_after_mins: ダーティなmeltableがフラッシュされずにいる最大時間（分）です。（commit logセグメントからの読み込み後、未だフラッシュしていないデータがmemtableに存在する限り、そのcommit logセグメントは削除できません）この値が小さすぎると、サイズやカウントのスレッショルドに到達する前に同時にmemtableのフラッシュが発生してしまいます。本番環境では大きな値、例えば1440程度がおすすめです。

    memtable_operations_in_millions: memtableをディスクにフラッシュする前にカラムファミリに格納可能な最大のカラム数を100万を単位として指定します。これもmemtableごとの設定になります。メモリ使用量を調整するにはMemtableSizeInMBを使用してください。

    memtable_throughput_in_mb: memtableをディスクにフラッシュする前にカラムファミリに格納可能な最大のデータサイズをMB単位で指定します。memtableはカラムファミリごとに用意されます。この閾値は単純に格納されたデータサイズにのみ依存し、実際のヒープメモリの使用量を基準にはしていません。（カラムのインデックスを作成するため、メモリサイズ上いくらかのオーバーヘッドが発生します。）併せてMemtableThresholdsを参照してください。 memtable_operations_in_millionsもmemtable_throughput_in_mbもデフォルト値はブート時のヒープ割当によって決まります。

    プロパティ名	デフォルト値
    memtable_flush_after_mins	60
    memtable_operations_in_millions	HeapSize/2**29 * 0.3
    memtable_throughput_in_mb	HeapSize/2**23

• partitioner

  • partitioner: クラスパスに配置されている任意のIPartitionerを指定できます。Cassandraパッケージには標準でorg.apache.cassandra.dht.RandomPartitioner、org.apache.cassandra.dht.OrderPreservingPartitioner、org.apache.cassandra.dht.CollatingOrderPreservingPartitionerが含まれています。（CollatingOrderPreservingPartitionerはネイティブバイト値ではなく、EN.USの規則に従って順序づけを行います。）レンジクエリを行うには順序を保存する（Order-Preserving）Partitionerを指定する必要があります。 注意！この設定を変更するとPartitionerはディスク上のsstableのフォーマットを変更するので、データディレクトリを削除して再作成する必要があります。 あなたが順序を保存するPartitionerを使用中で、キーの分散特性を理解しているなら、このノードが使用するトークンを指定することができます。（キーはキー値に最も「近い」トークンを持つノードに送られます。つまりキー空間内で均等な間隔でトークンを配置すればクラスターノード間で均等にキーが分散します。）この設定はノードを最初に起動した時のみ確認されます。

    RandomPartitionerはトークンをハッシュ値によって分散しますが、クラスターノードの数が少ない場合には特に有用です。

    RandomPartitionerを使用した場合Cassandraは内部的にMD5ハッシュを使用してリング上のキー配置を決定します。InitialTokenを適切に設定することでハッシュ空間をリング上のノード数で均等に分割することができます。例えばリングに10台のノードがある場合、それぞれのノードはハッシュの最大値の1/10づつを境に処理を受け持つように構成すれば、負荷はほぼ均等になるでしょう。

    OrderPreservingPartitionerを使用した場合キーはリング上の配置を決定します。この構成の欠点は、仮に行がシーケンシャルなキーで挿入された場合、すべてのトラフィックが同じノードに集中するということです。

    プロパティ名	デフォルト値
    partitioner	org.apache.cassandra.dht.RandomPartitioner

    負荷の均等分散を保証したい場合は、トークンを明示的に指定することをお勧めします。

• seeds

  • autobootstrapをtrueに設定してブートストラッピングを行う場合は、絶対に自ノードのアドレスをseedsに設定しないように注意してください！

• thrift_framed_transport_size_in_mb

  • この値を0以外に設定するとThriftにおいてframedトランスポートを使用することを意味します。0に設定するとunframedトランスポートを使用します。

    プロパティ名	デフォルト値
    thrift_framed_transport_size_in_mb	15

Keyspace単位の設定

• name

  • Keyspace名を指定する必須フィールドです。ダッシュ（-）を使用することはできません。

• replica_placement_strategy、replication_factor

  • replica_placement_strategy: IReplicaPlacementStrategyを実装したクラスを指定することによりレプリケーションノードの選択方法を変えることができます。標準ではorg.apache.cassandra.locator.RackUnawareStrategyと org.apache.cassandra.locator.RackAwareStrategyを用意しています。org.apache.cassandra.locator.RackAwareStrategyを使用すると一つのレプリカは他のデータセンターのノードが使用され、その他のレプリカは同じデータセンター内の別のラックのノードを使用します。

    replication_factor: レプリケーションファクタ（RF）はデータを配置するノード数の合計であることに注意してください。つまり、RFが1の場合はデータは1つのノードにしか保存されません。RFは「レプリケーション先」のノード数を意味しているわけではありません。RFには2以上を指定することを強くお勧めします。有効なノード数は（合計ノード数 / RF）であることに注意してください。

    プロパティ名	デフォルト値
    replica_placement_strategy	org.apache.cassandra.locator.RackUnawareStrategy
    replication_factor	1

カラムファミリ単位の設定

• comment、name

  • これらのプロパティを設定するとカラムファミリをプレーンテキストでdescribeできます。

• compare_with

  • CompareWith属性はカラムをスライシングする際にどのようにソートするかを指定します。標準はBytesTypeであり、それぞれのカラムをバイト値で比較します。他にはAsciiType、UTF8Type、LexicalUUIDType、TimeUUIDType、LongTypeから選択できます。org.apache.cassandra.db.marshal.AbstractTypeから派生させたクラスを指定することでカスタムのソート順序を指定することもできます。

  • SuperColumnsには類似のCompareSubcolumnsWith属性があります。

  • BytesType: バイト値による単純なソートです。バリデーションは行いません。

  • AsciiType: BytesTypeと似ていますが、入力がUS-ASCIIかバリデートします。

  • UTF8Type: UTF8でエンコードされた文字列としてソートします。

  • LongType: 64bit long値としてソートします。

  • LexicalUUIDType: 128bit UUIDとして、レキシカルにソートします。

  • TimeUUIDType: 128bit version 1 UUIDとして、タイムスタンプとしてソートします。 バリデータとして同じタイプが用意されています。

• default_validation_class

  • カラム単位の設定におけるvalidation_classプロパティと組み合わせて、カラム値のデータタイプをバリデートします。

    プロパティ名	デフォルト値
    default_validation_class	BytesType （何もしません）

• gc_grace_seconds

  • ガベージコレクションの削除マーカを待つ時間を指定します。この値は削除マーカがすべてのレプリカノードに確実に伝搬するために十分な秒数を設定してください。この際、一時的なハードウェア障害などによる遅延も考慮に入れてください。標準の値は10日です。

    プロパティ名	デフォルト値
    gc_grace_seconds	864000 （10日）

• keys_cached、rows_cached

  • キャッシュに収容するキー、行の個数を指定します。設定値は絶対値か、もしくは比率（0以上1以下のdouble値）で指定できます。 キーキャッシュがヒットするたびに1回のディスクシークを省けます。行キャッシュがヒットするたびに少なくとも2回以上のディスクシークを省けます。キーキャッシュは設定量に比較して大きな効果が期待できるので、例えば1.0（すべてキャッシュ）など、大きな値に設定する価値があります。 行キャッシュはキャッシュヒット時の効果は大きいですが、行データをすべてメモリに格納する必要があるためメモリを多く消費します。行キャッシュはアクセスが集中する行がある場合や、静的な行がある場合に限って設定するのがよいでしょう。

    プロパティ名	デフォルト値
    keys_cached	200000
    rows_cached	0 （無効）

• key_cache_save_period_in_seconds、row_cache_save_period_in_seconds

  • Cassandraがどのくらいの頻度でキャッシュをsaved_caches_directoryに保存するかを指定します。ディスクに保存されたキャッシュは起動の速度を大幅に短縮します。またキーキャッシュの場合は比較的IOコストが少なくてすみます。行キャッシュの保存はIOコストが高く、用途は限定されます。

    プロパティ名	デフォルト値
    key_cache_save_period_in_seconds	3600 （1時間）
    row_cache_save_period_in_seconds	0 （無効）

• min_compaction_threshold、max_compaction_threshold

  • この設定によりマイナーコンパクションのサイズと頻度が決まります。minとmaxはそれぞれ一度にマージ対象とするテーブルの個数の下限と上限を指定します。minを増やすとマイナーコンパクションに必要となるメモリ量が増え、実行頻度は減ります。maxを減らすと逆の効果があります。

    ノート: minimumとmaxmumを0に設定するとマイナーコンパクションを無効にします。自己責任で設定してください！

    プロパティ名	デフォルト値
    min_compaction_threshold	4
    max_compaction_threshold	32

• preload_row_cache

  • 起動時に行キャッシュをシーケンシャルリードでロードするか否かを指定します。実行時にランダムシークが発生することに比べれば性能の改善が期待できますが、行キャッシュの大きさが大きい場合にはロードに長い時間がかかります。

    プロパティ名	デフォルト値
    preload_row_cache	false

• read_repair_chance

  • 0.7以前ではリードリペアはすべての読み込みリクエストで実行するか、もしくはまったく実行しないかでした。今後はこのプロパティにより0以上1以下のdouble値でリードリペアが実行される確率を指定できます。

    プロパティ名	デフォルト値
    read_repair_chance	1.0

カラム単位の設定

• index_name、index_type

  • このプロパティはセカンダリインデックスを制御します。セカンダリインデックスを使用する場合は両方の値を設定する必要があります。nameには覚えやすくカラムファミリ内で一意な名前を指定してください。typeに設定可能な値は現在はKEYSのみです。詳しくはSecondaryIndexesを参照してください。

    プロパティ名	デフォルト値
    index_name	なし
    index_type	なし

• name

  • 包含するカラムファミリのすべての行のカラムのうち、このnameを持つカラムについて、バリデータ（及びオプションで自動インデクサ）を関連づけます。必須プロパティです。

• validation_class

  • カラムファミリ設定の中のdefault_validation_classとの組み合わせで使用します。この名前を持つカラムが生成されるたびに、ここで指定されたバリデーションクラスのvalidate()メソッドで値を検査します。必須プロパティです。