DynamoDBCSV

はじめに

これはDynamoDBのテーブルデータをCSVでより簡単にインポート/エクスポートするためのコマンドラインユーティリティです。

インストール

Pythonの実行できる環境が必要です。

$ pip install dynamodb-csv
$ dynamodb-csv -h
usage: dynamodb-csv [-h] [-v] [-i] [-e] [--truncate] [--move] -t [TABLE ...] [-idx INDEX] [-f FILE] [-o OUTPUT] [--ignore]
               [--profile PROFILE]

Import CSV file into DynamoDB table utilities

optional arguments:
  -h, --help            show this help message and exit
  -v, --version         show version
  -i, --imp             mode import
  -e, --exp             mode export
  --truncate            mode truncate
  --move                mode move
  -t [TABLE ...], --table [TABLE ...]
                        DynamoDB table name
  -idx INDEX, --index INDEX
                        DynamoDB index name
  -f FILE, --file FILE  UTF-8 CSV file path required import mode
  -o OUTPUT, --output OUTPUT
                        output file path required export mode
  --ignore              ignore import error
  --profile PROFILE     using AWS profile

または、Dockerを使うこともできます。

# Linux
$ docker run --rm -v ${PWD}/:/local danishi/dynamodb-csv:latest -h

# Windows
> docker run --rm -v %cd%/:/local danishi/dynamodb-csv:latest -h

GitHub Packagesからもイメージを取得できます。

接続設定ファイル

config.ini.exampleをコピーしてconfig.iniを作成し、接続先情報を記述します。

[AWS]
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
REGION=your_dynamodb_table_region
# Option
#ENDPOINT_URL=http://dynamodb-local:8000

ENDPOINT_URLを指定してDynamoDB-localの利用も可能です。

ただし、--profileでAWS名前付きプロファイルを指定した場合は、このファイルの作成は不要です。

$ dynamodb-csv -i -t my_table -f sample.csv --profile default

CSV定義ファイル

インポート/エクスポート操作のためにDynamoDBテーブルの属性情報と合わせたCSV定義ファイルを作成する必要があります。インポートを行う場合は合わせてUTF-8で取り込むCSVファイルを作成します。

例

CSVファイル
- sample.csv
CSV定義ファイル
- sample.csv.spec : インポートの定義
- sample_exp.csv.spec : エクスポートの定義
- sample_gsi_exp.csv.spec : GSIを使ったエクスポートの定義
- sample_query_exp.csv.spec : パーティションキーを使ったクエリー指定のエクスポートの定義
- sample_query_exp2.csv.spec : ソートキーを使ったクエリー指定のエクスポートの定義

定義ファイルの型とDynamoDBの型は厳密に一致しません。
下記の表を参考にしてください。

CSVの型	DynamoDBの型	値の例
String : S	String	`foo`
Integer : I	Number	`1`
Decimal : D	Number	`1.23`
Boolean : B	Boolean	`TRUE`
Json : J	Map	`[{""string"" : ""value""},{""number"" : 100}]`
StringList : SL	List	`foo bar baz`
StringSet : SS	String Set	`foo bar baz`
DecimalList : DL	List	`10 10.1 20`
DecimalSet : DS	Number Set	`10 10.1 20`

またバイナリ型はサポートされていません。
インポート時のNullの扱いは後述します。

コマンド実行例

テスト用テーブルの作成

$ aws dynamodb create-table --cli-input-json file://my_table.json --region ap-northeast-1

インポート

$ dynamodb-csv -i -t my_table -f sample.csv

ignoreオプションを付けると、CSV行をインポートする際にエラーがあった場合も処理中断せず、その行を無視して進めます。

$ dynamodb-csv -i -t my_table -f sample.csv --ignore

ignoreオプションを付けた場合インポート速度が遅くなります。

空文字の扱い

デフォルトではCSVに空の値があると空でセットします。
これをNullに変換したり、属性自体をセットさせないためのオプションがあります。

[IMPORT_OPTION]
ConvertBlankToNullAttrs=NullValue,JsonValue
ConvertBlankToDropAttrs=DecimalValue

エクスポート

$ dynamodb-csv -e -t my_table -o sample_exp.csv

GSIを使ったエクスポート

$ dynamodb-csv -e -t my_table -idx NumberSK-index -o sample_gsi_exp.csv

パーティションキーを使ったクエリー指定のエクスポートの定義

$ dynamodb-csv -e -t my_table -idx NumberSK-index -o sample_query_exp.csv

# sample_query_exp.csv data format specification
# Integer : I
# String : S
# Decimal : D
# Json : J

[QUERY_OPTION]
PKAttribute=NumberSK
PKAttributeValue=1
PKAttributeType=I

[CSV_SPEC]
NumberSK=I
StringPK=S
DecimalValue=D
JsonValue=J

クエリー条件

クエリー条件として以下が指定できます。

キー	説明	例
`PKAttribute`	パーティションキー属性名
`PKAttributeValue`	パーティションキー属性値
`PKAttributeType`	パーティションキー属性のデータ型
`SKAttribute`	ソートキー属性名
`SKAttributeValues`	ソートキー属性値（複数可）	例: `foo` or `foo,bar`
`SKAttributeType`	ソートキー属性のデータ型
`SKAttributeExpression`	ソートキーへのクエリー条件	指定の例: `begins_with` `between` `eq` `gt` `gte` `lt` `lte`

ソートキーを使ったクエリー指定のエクスポートの定義

$ dynamodb-csv -e -t my_table -o sample_query_exp2.csv

[QUERY_OPTION]
PKAttribute=StringPK
PKAttributeValue=bar
PKAttributeType=S
SKAttribute=NumberSK
SKAttributeValues=50,100
SKAttributeType=I
SKAttributeExpression=between

テーブルのクリア

テーブルの項目を全て削除できます。

$ dynamodb-csv --truncate -t my_table

テーブルアイテムの移動

テーブルから別のテーブルへアイテムを全て移動（コピー）できます。
事前に移動先のテーブルの作成とパーティションキー及びソートキーの定義を合わせておく必要があります。

$ dynamodb-csv --move -t my_table_from my_table_to