Apache Cassandra™ Documentation February 16, 2012 © 2012 DataStax. All rights reserved. ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! Apache,!Apache!Cassandra,!Apache!Hadoop,!Hadoop!and!the!eye!logo! are!trademarks!of!the!Apache!Software!Foundation! Contents Apache Cassandra 1.0 Documentation 1 Introduction to Apache Cassandra 1 Getting Started with Cassandra 1 Java Prerequisites 1 Download the Software 1 Install the Software 1 Start the Cassandra Server 1 Login to Cassandra 1 Create a Keyspace (database) 1 Create a Column Family 2 Insert, Update, Delete, Read Data 2 Getting Started with Cassandra and DataStax Community Edition 2 Installing a Single-Node Instance of Cassandra 2 Checking for a Java Installation 2 Installing the DataStax Community Binaries on Linux 3 Configuring and Starting a Single-Node Cluster on Linux 4 Installing the DataStax Community Binaries on Mac 5 Installing the DataStax Community Binaries on Windows 5 Configuring and Starting DataStax OpsCenter 5 Running the Portfolio Demo Sample Application 6 About the Portfolio Demo Use Case 6 Running the Demo Web Application 6 Exploring the Sample Data Model 7 Looking at the Schema Definitions in Cassandra-CLI 8 DataStax Community Release Notes 8 What's New 8 Prerequisites 8 Understanding the Cassandra Architecture 8 About Internode Communications (Gossip) 8 About Cluster Membership and Seed Nodes 9 About Failure Detection and Recovery 9 About Data Partitioning in Cassandra 10 About Partitioning in Multi-Data Center Clusters 10 Understanding the Partitioner Types 12 About the Random Partitioner 12 About Ordered Partitioners 13 About Replication in Cassandra 13 About Replica Placement Strategy 14 SimpleStrategy 14 NetworkTopologyStrategy 14 About Snitches 17 SimpleSnitch 18 DseSimpleSnitch 18 RackInferringSnitch 18 PropertyFileSnitch 19 EC2Snitch 19 EC2MultiRegionSnitch 19 About Dynamic Snitching 19 About Client Requests in Cassandra 19 About Write Requests 20 About Multi-Data Center Write Requests 20 About Read Requests 21 Planning a Cassandra Cluster Deployment 22 Selecting Hardware 22 Memory 22 CPU 22 Disk 23 Network 23 Planning an Amazon EC2 Cluster 23 Capacity Planning 24 Calculating Usable Disk Capacity 24 Calculating User Data Size 24 Choosing Node Configuration Options 25 Storage Settings 25 Gossip Settings 25 Purging Gossip State on a Node 25 Partitioner Settings 25 Snitch Settings 26 Configuring the PropertyFileSnitch 26 Choosing Keyspace Replication Options 27 Installing and Initializing a Cassandra Cluster 27 Installing Cassandra Using the Packaged Releases 27 Creating the Cassandra User and Configuring sudo 27 Installing Cassandra RPM Packages 28 Installing Sun JRE on RedHat Systems 28 Installing Cassandra Debian Packages 29 Installing Sun JRE on Ubuntu Systems 30 About Packaged Installs 31 Next Steps 31 Installing the Cassandra Tarball Distribution 31 About Cassandra Binary Installations 32 Installing JNA 32 Next Steps 32 Initializing a Cassandra Cluster on Amazon EC2 Using the DataStax AMI 32 Creating an EC2 Security Group for DataStax Community Edition 33 Launching the DataStax Community AMI 34 Connecting to Your Cassandra EC2 Instance 35 Configuring and Starting a Cassandra Cluster 38 Initializing a Multi-Node or Multi-Data Center Cluster 38 Calculating Tokens 39 Calculating Tokens for Multiple Racks 40 Calculating Tokens for a Single Data Center 40 Calculating Tokens for a Multi-Data Center Cluster 41 Starting and Stopping a Cassandra Node 42 Starting/Stopping Cassandra as a Stand-Alone Process 42 Starting/Stopping Cassandra as a Service 42 Upgrading Cassandra 43 Best Practices for Upgrading Cassandra 43 Upgrading Cassandra: 0.8.x to 1.0.x 43 New and Changed Parameters between 0.8 and 1.0 44 Upgrading Between Minor Releases of Cassandra 1.0.x 45 Understanding the Cassandra Data Model 45 The Cassandra Data Model 45 Comparing the Cassandra Data Model to a Relational Database 45 About Keyspaces 47 Defining Keyspaces 47 About Column Families 48 About Columns 49 About Special Columns (Counter, Expiring, Super) 49 About Expiring Columns 49 About Counter Columns 50 About Super Columns 50 About Data Types (Comparators and Validators) 50 About Validators 51 About Comparators 51 About Column Family Compression 52 When to Use Compression 52 Configuring Compression on a Column Family 52 About Indexes in Cassandra 52 About Primary Indexes 53 About Secondary Indexes 53 Building and Using Secondary Indexes 53 Planning Your Data Model 54 Start with Queries 54 Denormalize to Optimize 54 Planning for Concurrent Writes 54 Using Natural or Surrogate Row Keys 54 UUID Types for Column Names 55 Managing and Accessing Data in Cassandra 55 About Writes in Cassandra 55 About Compaction 55 About Transactions and Concurrency Control 55 About Inserts and Updates 56 About Deletes 56 About Hinted Handoff Writes 57 About Reads in Cassandra 57 About Data Consistency in Cassandra 58 Tunable Consistency for Client Requests 58 About Write Consistency 58 About Read Consistency 58 Choosing Client Consistency Levels 59 Consistency Levels for Multi-Data Center Clusters 59 Specifying Client Consistency Levels 60 About Cassandra's Built-in Consistency Repair Features 60 Cassandra Client APIs 60 About Cassandra CLI 60 About CQL 61 Other High-Level Clients 61 Java: Hector Client API 61 Python: Pycassa Client API 61 PHP: Phpcassa Client API 61 Getting Started Using the Cassandra CLI 61 Creating a Keyspace 62 Creating a Column Family 62 Creating a Counter Column Family 63 Inserting Rows and Columns 63 Reading Rows and Columns 64 Setting an Expiring Column 64 Indexing a Column 64 Deleting Rows and Columns 65 Dropping Column Families and Keyspaces 65 Getting Started with CQL 65 Starting the CQL Command-Line Program (cqlsh) 65 Running CQL Commands with cqlsh 66 Creating a Keyspace 66 Creating a Column Family 66 Inserting and Retrieving Columns 66 Adding Columns with ALTER COLUMNFAMILY 66 Altering Column Metadata 67 Specifying Column Expiration with TTL 67 Dropping Column Metadata 67 Indexing a Column 67 Deleting Columns and Rows 67 Dropping Column Families and Keyspaces 68 Configuration 68 Node and Cluster Configuration (cassandra.yaml) 68 Node and Cluster Initialization Properties 70 auto_bootstrap 70 broadcast_address 70 cluster_name 70 commitlog_directory 70 data_file_directories 70 initial_token 70 listen_address 70 partitioner 71 rpc_address 71 rpc_port 71 saved_caches_directory 71 seed_provider 71 seeds 71 storage_port 71 endpoint_snitch 71 Performance Tuning Properties 72 column_index_size_in_kb 72 commitlog_sync 72 commitlog_sync_period_in_ms 72 commitlog_total_space_in_mb 72 compaction_preheat_key_cache 72 compaction_throughput_mb_per_sec 72 concurrent_compactors 72 concurrent_reads 72 concurrent_writes 72 flush_largest_memtables_at 73 in_memory_compaction_limit_in_mb 73 index_interval 73 memtable_flush_queue_size 73 memtable_flush_writers 73 memtable_total_space_in_mb 73 multithreaded_compaction 73 reduce_cache_capacity_to 73 reduce_cache_sizes_at 73 sliced_buffer_size_in_kb 74 stream_throughput_outbound_megabits_per_sec 74 Remote Procedure Call Tuning Properties 74 request_scheduler 74 request_scheduler_id 74 request_scheduler_options 74 throttle_limit 74 default_weight 74 weights 74 rpc_keepalive 74 rpc_max_threads 75 rpc_min_threads 75 rpc_recv_buff_size_in_bytes 75 rpc_send_buff_size_in_bytes 75 rpc_timeout_in_ms 75 rpc_server_type 75 thrift_framed_transport_size_in_mb 75 thrift_max_message_length_in_mb 75 Internode Communication and Fault Detection Properties 75 dynamic_snitch 75 dynamic_snitch_badness_threshold 75 dynamic_snitch_reset_interval_in_ms 76 dynamic_snitch_update_interval_in_ms 76 hinted_handoff_enabled 76 hinted_handoff_throttle_delay_in_ms 76 max_hint_window_in_ms 76 phi_convict_threshold 76 Automatic Backup Properties 76 incremental_backups 76 snapshot_before_compaction 76 Security Properties 76 authenticator 76 authority 77 internode_encryption 77 keystore 77 keystore_password 77 truststore 77 truststore_password 77 Keyspace and Column Family Storage Configuration 77 Keyspace Attributes 78 name 78 placement_strategy 78 strategy_options 78 Column Family Attributes 79 column_metadata 79 column_type 80 comment 80 compaction_strategy 80 compaction_strategy_options 80 comparator 81 compare_subcolumns_with 81 compression_options 81 default_validation_class 81 gc_grace_seconds 81 key_cache_save_period_in_seconds 81 keys_cached 82 key_validation_class 82 name 82 read_repair_chance 82 replicate_on_write 82 max_compaction_threshold 82 min_compaction_threshold 82 memtable_flush_after_mins 82 memtable_operations_in_millions 82 memtable_throughput_in_mb 83 rows_cached 83 row_cache_provider 83 row_cache_save_period_in_seconds 83 Java and System Environment Settings Configuration 83 Heap Sizing Options 83 JMX Options 83 Further Reading on JVM Tuning 84 Authentication and Authorization Configuration 84 access.properties 84 passwd.properties 85 Logging Configuration 85 Logging Levels via the Properties File 85 Logging Levels via JMX 85 Operations 86 Monitoring a Cassandra Cluster 86 Monitoring Using DataStax OpsCenter 86 Monitoring Using nodetool 87 Monitoring Using JConsole 88 Compaction Metrics 89 Thread Pool Statistics 90 Read/Write Latency Metrics 90 ColumnFamily Statistics 90 Monitoring and Adjusting Cache Performance 91 Tuning Cassandra 91 Tuning the Cache 92 How Caching Works 92 Configuring the Column Family Key Cache 92 Configuring the Column Family Row Cache 92 Data Modeling Considerations for Cache Tuning 93 Hardware and OS Considerations for Cache Tuning 93 Estimating Cache Sizes 93 Tuning Write Performance (Memtables) 93 Tuning Java Heap Size 93 Tuning Java Garbage Collection 94