AWS Developer Tools Blog
Creating Amazon DynamoDB Tables with PowerShell
Version 2.0 of the AWS Tools for Windows PowerShell contains new cmdlets that allow you to manage tables in Amazon DynamoDB. The cmdlets all share the same noun prefix, DDB, and can be discovered using Get-Command:
PS C:> Get-Command -Module AWSPowerShell -Noun DDB*
CommandType Name ModuleName
----------- ---- ----------
Cmdlet Add-DDBIndexSchema AWSPowerShell
Cmdlet Add-DDBKeySchema AWSPowerShell
Cmdlet Get-DDBTable AWSPowerShell
Cmdlet Get-DDBTables AWSPowerShell
Cmdlet New-DDBTable AWSPowerShell
Cmdlet New-DDBTableSchema AWSPowerShell
Cmdlet Remove-DDBTable AWSPowerShell
Cmdlet Update-DDBTable AWSPowerShell
This post looks at the New-DDBTable cmdlet and the schema builder cmdlets — New-DDBTableSchema, Add-DDBKeySchema, and Add-DDBIndexSchema — that you can use in a pipeline to make table definition and creation simple and fluent.
Defining Schema
The schema builder cmdlets allow you to define the schema for your table and can be used in a PowerShell pipeline to incrementally refine and extend the schema you require. The schema object is then passed to New-DDBTable (either in the pipeline or as the value for the -Schema parameter) to create the table you need. Behind the scenes, these cmdlets and New-DDBTable infer and wire up the correct settings for your table with respect to hash keys (on the table itself or in the indexes) without you needing to manually add this information.
Let’s take a look at the syntax for the schema builder cmdlets (parameters inside [] are optional; for parameters that accept a range of values, the allowable values are shown in {} separated by |):
# takes no parameters, returns a new Amazon.PowerShell.Cmdlets.DDB.Model.TableSchema object
New-DDBTableSchema
# The schema definition object may be piped to the cmdlet or passed as the value for -Schema
Add-DDBKeySchema -KeyName "keyname"
-KeyDataType { "N" | "S" | "B" }
[ -KeyType { "hash" | "range" } ]
-Schema Amazon.PowerShell.Cmdlets.DDB.Model.TableSchema
# The schema definition object may be piped to the cmdlet or passed as the value for -Schema
Add-DDBIndexSchema -IndexName "indexName"
-RangeKeyName "keyName"
-RangeKeyDataType { "N" | "S" | "B" }
[ -ProjectionType { "keys_only" | "include" | "all" } ]
[ -NonKeyAttribute @( "attrib1", "attrib2", ... ) ]
-Schema Amazon.PowerShell.Cmdlets.DDB.Model.TableSchema
Not all of the parameters for each cmdlet are required as the cmdlets accept certain defaults. For example, the default key type for Add-DDBKeySchema is “hash”. For Add-DDBIndexSchema, -ProjectionType is optional (and -NonKeyAttribute is needed only if -ProjectionType is set to “include”). If you’re familiar with the Amazon DynamoDB API, you’ll probably recognize the type codes used with -KeyDataType and -RangeKeyDataType. You can find the API reference for the CreateTable operation here.
Using the Create a Table example shown on the CreateTable API reference page, here’s how we can easily define the schema using these cmdlets in a pipeline:
PS C:> New-DDBTableSchema `
| Add-DDBKeySchema -KeyName "ForumName" -KeyDataType "S" `
| Add-DDBKeySchema -KeyName "Subject" -KeyType "range" -KeyDataType "S" `
| Add-DDBIndexSchema -IndexName "LastPostIndex" `
-RangeKeyName "LastPostDateTime" `
-RangeKeyDataType "S" `
-ProjectionType "keys_only"
AttributeSchema KeySchema LocalSecondaryIndexSchema GlobalSecondaryIndexSchema
--------------- --------- ------------------------- --------------------------
{ForumName, Subject, LastPost... {ForumName, Subject} {LastPostIndex} {}
PS C:>
As you can see from the output, the cmdlets took the empty schema object created by New-DDBTableSchema and extended it with the data that New-DDBTable will need. One thing to note is that, apart from New-DDBTableSchema, the cmdlets can be run in any order, any number of times. This gives you complete freedom to experiment at the console without needing to define all the keys up front and then define the index schema and so on. You can also clone the schema object and stash away a basic template that you can then further refine for multiple different tables (the Clone() method on the schema object makes a deep copy of the data it contains).
Creating the Table
Once the schema is defined, it can be passed to New-DDBTable to request that the table be created. The schema can be passed into New-DDBTable using a pipeline or by passing the schema object to the -Schema parameter. Here is the syntax for New-DDBTable:
# The schema definition object may be piped to the cmdlet or passed as the value for -Schema
New-DDBTable -TableName "tableName"
-Schema Amazon.PowerShell.Cmdlets.DDB.Model.TableSchema
-ReadCapacity value
-WriteCapacity value
As you can see, it’s pretty simple. To use the previous example schema definition—but this time actually create the table—we can extend our pipeline like this:
PS C:> New-DDBTableSchema `
| Add-DDBKeySchema -KeyName "ForumName" -KeyDataType "S" `
| Add-DDBKeySchema -KeyName "Subject" -KeyType "range" -KeyDataType "S" `
| Add-DDBIndexSchema -IndexName "LastPostIndex" `
-RangeKeyName "LastPostDateTime" `
-RangeKeyDataType "S" `
-ProjectionType "keys_only" `
| New-DDBTable "Threads" -ReadCapacity 10 -WriteCapacity 5
AttributeDefinitions : {ForumName, LastPostDateTime, Subject}
TableName : Threads
KeySchema : {ForumName, Subject}
TableStatus : CREATING
CreationDateTime : 11/29/2013 5:47:31 PM
ProvisionedThroughput: Amazon.DynamoDBv2.Model.ProvisionedThroughputDescription
TableSizeBytes : 0
ItemCount : 0
LocalSecondaryIndexes: {LastPostIndex}
GlobalSecondaryIndexes: {}
PS C:>
By default Add-DDBIndexSchema constructs local secondary indices. To have the cmdlet construct a global secondary index schema entry instead, you simply add the -Global switch plus the required provisioning -ReadCapacity and -WriteCapacity parameter values you need. You can also optionally specify -HashKeyName and -HashKeyDataType instead of, or in addition to, the range key parameters:
...
| Add-DDBIndexSchema -Global `
-IndexName "myGlobalIndex" `
-HashKeyName "hashKeyName" `
-HashKeyDataType "N" `
-RangeKeyName "rangeKeyName" `
-RangeKeyDataType "S" `
-ProjectionType "keys_only" `
-Global `
-ReadCapacity 5 `
-WriteCapacity 5 `
...
Let us know in the comments what you think about the fluent-style cmdlet piping, or how well these DynamoDB cmdlets fit your scripting needs.