Working with keyspaces in Amazon Keyspaces - Amazon Keyspaces (for Apache Cassandra)
System keyspacesCreating keyspaces
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Working with keyspaces in Amazon Keyspaces

This section provides details about working with keyspaces in Amazon Keyspaces (for Apache Cassandra).

Working with system keyspaces in Amazon Keyspaces

Amazon Keyspaces uses four system keyspaces:

  • system

  • system_schema

  • system_schema_mcs

  • system_multiregion_info

The following sections provide details about the system keyspaces and the system tables that are supported in Amazon Keyspaces.

system

This is a Cassandra keyspace. Amazon Keyspaces uses the following tables.

Table names Column names Comments

local

key, bootstrapped, broadcast_address, cluster_name, cql_version, data_center, gossip_generation, host_id, listen_address, native_protocol_version, partitioner, rack, release_version, rpc_address, schema_version, thrift_version, tokens, truncated_at

Information about the local keyspace.

peers

peer, data_center, host_id, preferred_ip, rack, release_version, rpc_address, schema_version, tokens

Query this table to see the available endpoints. For example, if you're connecting through a public endpoint, you see a list of nine available IP addresses. If you're connecting through a FIPS endpoint, you see a list of three IP addresses. If you're connecting through an Amazon PrivateLink VPC endpoint, you see the list of IP addresses that you have configured. For more information, see Populating system.peers table entries with interface VPC endpoint information.

size_estimates

keyspace_name, table_name, range_start, range_end, mean_partition_size, partitions_count

 This table defines the total size and number of partitions for each token range for every table. This is needed for the Apache Cassandra Spark Connector, which uses the estimated partition size to distribute the work.

prepared_statements

prepared_id, logged_keyspace, query_string

This table contains information about saved queries.

system_schema

This is a Cassandra keyspace. Amazon Keyspaces uses the following tables.

Table names Column names Comments

keyspaces

keyspace_name, durable_writes, replication

Information about a specific keyspace.

tables

keyspace_name, table_name, bloom_filter_fp_chance, caching, comment, compaction, compression, crc_check_chance, dclocal_read_repair_chance, default_time_to_live, extensions, flags, gc_grace_seconds, id, max_index_interval, memtable_flush_period_in_ms, min_index_interval, read_repair_chance, speculative_retry

Information about a specific table.

columns

keyspace_name, table_name, column_name, clustering_order, column_name_bytes, kind, position, type

Information about a specific column.

system_schema_mcs

This is an Amazon Keyspaces keyspace that stores information about Amazon or Amazon Keyspaces specific settings.

Table names Column names Comments

keyspaces

keyspace_name, durable_writes, replication

Query this table to find out programmatically if a keyspace has been created. For more information, see Creating keyspaces in Amazon Keyspaces.

tables

keyspace_name, creation_time, speculative_retry, cdc, gc_grace_seconds, crc_check_chance, min_index_interval, bloom_filter_fp_chance, flags, custom_properties, dclocal_read_repair_chance, table_name, caching, default_time_to_live, read_repair_chance, max_index_interval, extensions, compaction, comment, id, compression, memtable_flush_period_in_ms, status

Query this table to find out the status of a specific table. For more information, see Creating tables in Amazon Keyspaces.

You can also query this table to list settings that are specific to Amazon Keyspaces and are stored as custom_properties. For example:

  • capacity_mode

  • client_side_timestamps

  • encryption_specification

  • point_in_time_recovery

  • ttl

tables_history

keyspace_name, table_name, event_time, creation_time, custom_properties, event

Query this table to learn about schema changes for a specific table.

columns

keyspace_name, table_name, column_name, clustering_order, column_name_bytes, kind, position, type

This table is identical to the Cassandra table in the system_schema keyspace.

tags

resource_id, keyspace_name, resource_name, resource_type, tags

Query this table to find out if a keyspace has tags. For more information, see Adding tags to new or existing keyspaces and tables using CQL.

autoscaling

keyspace_name, table_name, provisioned_read_capacity_autoscaling_update, provisioned_write_capacity_autoscaling_update

Query this table to get the auto scaling settings of a provisioned table. Note that these settings won't be available until the table is active. To query this table, you have to specify keyspace_name and table_name in the WHERE clause. For more information, see Managing Amazon Keyspaces auto scaling with Cassandra Query Language (CQL).

system_multiregion_info

This is an Amazon Keyspaces keyspace that stores information about Multi-Region Replication.

Table names Column names Comments

tables

keyspace_name, table_name, region, status

This table contains information about multi-Region tables—for example, the Amazon Web Services Regions that the table is replicated in and the table's status. You can also query this table to list settings that are specific to Amazon Keyspaces that are stored as custom_properties. For example:

  • capacity_mode

To query this table, you have to specify keyspace_name and table_name in the WHERE clause. For more information, see Creating a multi-Region keyspace (CQL).

autoscaling

keyspace_name, table_name, provisioned_read_capacity_autoscaling_update, provisioned_write_capacity_autoscaling_update, region

Query this table to get the auto scaling settings of a multi-Region provisioned table. Note that these settings won't be available until the table is active. To query this table, you have to specify keyspace_name and table_name in the WHERE clause. For more information, see Using CQL to create and manage multi-Region tables.

Creating keyspaces in Amazon Keyspaces

Amazon Keyspaces performs data definition language (DDL) operations, such as creating and deleting keyspaces, asynchronously.

You can monitor the creation status of new keyspaces in the Amazon Web Services Management Console, which indicates when a keyspace is pending or active. You can also monitor the creation status of a new keyspace programmatically by using the system_schema_mcs keyspace. A keyspace becomes visible in the system_schema_mcs keyspaces table when it's ready for use.

The recommended design pattern to check when a new keyspace is ready for use is to poll the Amazon Keyspaces system_schema_mcs keyspaces table (system_schema_mcs.*). For a list of DDL statements for keyspaces, see the Keyspaces section in the CQL language reference.

The following query shows whether a keyspace has been successfully created.

SELECT * FROM system_schema_mcs.keyspaces WHERE keyspace_name = 'mykeyspace';

For a keyspace that has been successfully created, the output of the query looks like the following.


keyspace_name | durable_writes  | replication
--------------+-----------------+--------------
   mykeyspace | true            |{...} 1 item