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).

Using the Amazon CLI to connect to Amazon Keyspaces

You can use the Amazon Command Line Interface (Amazon CLI) to control multiple Amazon services from the command line and automate them through scripts. With Amazon Keyspaces you can use the Amazon CLI for data definition language (DDL) operations, such as creating a table. In addition, you can use infrastructure as code (IaC) services and tools such as Amazon CloudFormation and Terraform.

Before you can use the Amazon CLI with Amazon Keyspaces, you must get an access key ID and secret access key. For more information, see Create and configure Amazon credentials for Amazon Keyspaces.

For a complete listing of all the commands available for Amazon Keyspaces in the Amazon CLI, see the Amazon CLI Command Reference.

Downloading and Configuring the Amazon CLI

The Amazon CLI is available at https://www.amazonaws.cn/cli. It runs on Windows, macOS, or Linux. After downloading the Amazon CLI, follow these steps to install and configure it:

Using the Amazon CLI with Amazon Keyspaces

The command line format consists of a Amazon Keyspaces operation name followed by the parameters for that operation. The Amazon CLI supports a shorthand syntax for the parameter values, as well as JSON. The following Amazon Keyspaces examples use Amazon CLI shorthand syntax. For more information, see Using shorthand syntax with the Amazon CLI.

The following command creates a keyspace with the name catalog.

aws keyspaces create-keyspace --keyspace-name 'catalog'

The command returns the resource Amazon Resource Name (ARN) in the output.

{
    "resourceArn": "arn:aws:cassandra:us-east-1:111222333444:/keyspace/catalog/"
}

To confirm that the keyspace catalog exists, you can use the following command.

aws keyspaces get-keyspace --keyspace-name 'catalog'

The output of the command returns the following values.

{
    "keyspaceName": "catalog",
    "resourceArn": "arn:aws:cassandra:us-east-1:111222333444:/keyspace/catalog/"
}

The following command creates a table with the name book_awards. The partition key of the table consists of the columns year and award and the clustering key consists of the columns category and rank, both clustering columns use the ascending sort order. (For easier readability, long commands in this section are broken into separate lines.)

aws keyspaces create-table --keyspace-name 'catalog' --table-name 'book_awards' 
            --schema-definition 'allColumns=[{name=year,type=int},{name=award,type=text},{name=rank,type=int},
            {name=category,type=text}, {name=author,type=text},{name=book_title,type=text},{name=publisher,type=text}],
            partitionKeys=[{name=year},{name=award}],clusteringKeys=[{name=category,orderBy=ASC},{name=rank,orderBy=ASC}]'

This command results in the following output.

{
    "resourceArn": "arn:aws:cassandra:us-east-1:111222333444:/keyspace/catalog/table/book_awards"
}

To confirm the metadata and properties of the table, you can use the following command.

aws keyspaces get-table --keyspace-name 'catalog' --table-name 'book_awards'

This command returns the following output.

{
    "keyspaceName": "catalog",
    "tableName": "book_awards",
    "resourceArn": "arn:aws:cassandra:us-east-1:111222333444:/keyspace/catalog/table/book_awards",
    "creationTimestamp": 1645564368.628,
    "status": "ACTIVE",
    "schemaDefinition": {
        "allColumns": [
            {
                "name": "year",
                "type": "int"
            },
            {
                "name": "award",
                "type": "text"
            },
            {
                "name": "category",
                "type": "text"
            },
            {
                "name": "rank",
                "type": "int"
            },
            {
                "name": "author",
                "type": "text"
            },
            {
                "name": "book_title",
                "type": "text"
            },
            {
                "name": "publisher",
                "type": "text"
            }
        ],
        "partitionKeys": [
            {
                "name": "year"
            },
            {
                "name": "award"
            }
        ],
        "clusteringKeys": [
            {
                "name": "category",
                "orderBy": "ASC"
            },
            {
                "name": "rank",
                "orderBy": "ASC"
            }
        ],
        "staticColumns": []
    },
    "capacitySpecification": {
        "throughputMode": "PAY_PER_REQUEST",
        "lastUpdateToPayPerRequestTimestamp": 1645564368.628
    },
    "encryptionSpecification": {
        "type": "AWS_OWNED_KMS_KEY"
    },
    "pointInTimeRecovery": {
        "status": "DISABLED"
    },
    "ttl": {
        "status": "ENABLED"
    },
    "defaultTimeToLive": 0,
    "comment": {
        "message": ""
    }
}

When creating tables with complex schemas, it can be helpful to load the table's schema definition from a JSON file. The following is an example of this. Download the schema definition example JSON file from schema_definition.zip and extract schema_definition.json, taking note of the path to the file. In this example, the schema definition JSON file is located in the current directory. For different file path options, see How to load parameters from a file.

aws keyspaces create-table --keyspace-name 'catalog' 
            --table-name 'book_awards' --schema-definition 'file://schema_definition.json'

The following examples show how to create a simple table with the name myTable with additional options. Note that the commands are broken down into separate rows to improve readability. This command shows how to create a table and:

aws keyspaces create-table --keyspace-name 'catalog' --table-name 'myTable' 
            --schema-definition 'allColumns=[{name=id,type=int},{name=name,type=text},{name=date,type=timestamp}],partitionKeys=[{name=id}]' 
            --capacity-specification 'throughputMode=PROVISIONED,readCapacityUnits=5,writeCapacityUnits=5' 
            --point-in-time-recovery 'status=ENABLED' 
            --default-time-to-live '31536000' 
            --tags 'key=env,value=test' 'key=dpt,value=sec'

This example shows how to create a new table that uses a customer managed key for encryption and has TTL enabled to allow you to set expiration dates for columns and rows. To run this sample, you must replace the resource ARN for the customer managed Amazon KMS key with your own key and ensure Amazon Keyspaces has access to it.

aws keyspaces create-table --keyspace-name 'catalog' --table-name 'myTable' 
            --schema-definition 'allColumns=[{name=id,type=int},{name=name,type=text},{name=date,type=timestamp}],partitionKeys=[{name=id}]' 
            --encryption-specification 'type=CUSTOMER_MANAGED_KMS_KEY,kmsKeyIdentifier=arn:aws:kms:us-east-1:111222333444:key/11111111-2222-3333-4444-555555555555'  
            --ttl 'status=ENABLED'