Boto3 > DynamoDB 各クラスのドキュメントについて、メソッドの概要部だけDeeplに突っ込んで翻訳しました。
Clientクラス
Pagenatorクラス
Waitersクラス
Service Resourceクラス
Tableクラス（この記事）
各メソッドの説明文のみ翻訳しています。引数とレスポンスもリファレンスにはまとまっていますが、その部分は翻訳してません。あくまでざっと全体を見て何ができるか、必要なメソッドはどれかを拾うために使ってください。
Table
class DynamoDB.Table(name)
Amazon DynamoDBテーブルを表すリソース:
import boto3
dynamodb = boto3.resource('dynamodb')
table = dynamodb.Table('name')
パラメータ
name (string) -- テーブルの名前識別子(name dentifier)。必ず設定すること。
リソースの利用可能な識別子(identifiers)：
- name
リソースの利用可能な属性：
- archival_summary
- attribute_definitions
- billing_mode_summary
- vcreation_date_time
- global_secondary_indexes
- global_table_version
- item_count
- key_schema
- latest_stream_arn
- latest_stream_label
- local_secondary_indexes
- provisioned_throughput
- replicas
- restore_summary
- sse_description
- stream_specification
- table_arn
- table_class_summary
- table_id
- table_name
- table_size_bytes
- table_status
リソースの利用可能なアクション:
- batch_writer()
- delete()
- delete_item()
- get_available_subresources()
- get_item()
- load()
- put_item()
- query()
- reload()
- scan()
- update()
- update_item()
リソースの利用可能なウェイター:
- wait_until_exists()
- wait_until_not_exists()
識別子(Identifiers)
識別子はリソースのプロパティで、リソースのインスタンス化時に設定されます。識別子の詳細については、Resources Introduction Guideを参照してください。
name
(string) テーブルの名前識別子。必ず設定する必要があります。
属性
属性は、リソースのプロパティへのアクセスを提供します。属性は、load() メソッドによって初めてアクセスされたときに遅延ロード(lazy-load)されます。属性の詳細については、Resources Introduction Guide.を参照してください。
archival_summary
(dict) --
テーブルアーカイブに関する情報を含む。
attribute_definitions
(list) --
AttributeDefinition オブジェクトの配列。これらのオブジェクトは、それぞれテーブルとインデックスキーのスキーマにおけるひとつの属性を記述します。
billing_mode_summary
(dict) --
読み出し/書き込み容量モードの詳細が記載されています。
creation_date_time
(datetime) --
テーブルが作成された日付と時刻。UNIXエポックタイム形式。
global_secondary_indexes
(list) --
テーブル上にグローバルセカンダリインデックスがある場合、そのインデックス。各インデックスは、与えられたパーティションキー値にスコープされています。
global_table_version
(string) --
テーブルがAmazon Web Servicesリージョン間でレプリケートされる場合、使用中のグローバルテーブルのバージョンを表わします。
item_count
(integer) --
指定したテーブルのアイテム数。DynamoDBはこの値をおよそ6時間ごとに更新します。最近の変更はこの値には反映されないかもしれません。
key_schema
(list) --
テーブルの主キー構造。各KeySchemaElementは以下の要素で構成される。
latest_stream_arn
(string) --
このテーブルの最新のストリームを一意に識別するAmazon Resource Name (ARN)。
latest_stream_label
(string) --
このストリームの ISO 8601 フォーマットのタイムスタンプ。
別のテーブルからのストリームが同じタイムスタンプを持つ可能性があるため、LatestStreamLabelはストリームの一意な識別子ではないことに注意してください。ただし、以下の3つの要素の組み合わせは一意であることが保証される。
・Amazon Web Services customer ID
・Table name
・StreamLabel
local_secondary_indexes
(list) --
テーブル上の1つまたは複数のローカルセカンダリインデックスを表します。各インデックスは、指定されたパーティションキー値にスコープされます。1つ以上のローカル・セカンダリー・インデックスを持つテーブルには、アイテム・コレクションのサイズ制限が適用され、与えられたアイテム・コレクション内のデータ量は10GBを超えることはできません。
provisioned_throughput
(dict) --
テーブルのプロビジョニングされたスループット設定。読み取りと書き込みの容量単位で構成され、増加および減少に関するデータも含まれます。
replicas
(list) --
テーブルのレプリカを表す。
restore_summary
(dict) --
リストアに関する詳細が記載されています。
sse_description
(dict) --
指定されたテーブルのサーバー側暗号化状態の説明。
stream_specification
(dict) --
テーブルに対する現在のDynamoDB Streamsの設定です。
table_arn
(string) --
テーブルを一意に識別するAmazon Resource Name (ARN)です。
table_class_summary
(dict) --
テーブルクラスの詳細が記載されている。
table_id
(string) --
バックアップが作成されたテーブルの一意な識別子。
table_name
(string) --
テーブルの名前。
table_size_bytes
(integer) --
指定したテーブルの総サイズをバイト数で表したものです。DynamoDBはこの値をおよそ6時間ごとに更新します。最近の変更はこの値には反映されないかもしれません。
table_status
(string) --
テーブルの現在の状態。
Actions
アクションはリソースに対する操作を呼び出します。識別子や一部の属性から設定された引数の受け渡しを自動的に行うことができる。アクションの詳細については、Resources Introduction Guideを参照してください。
batch_writer(overwrite_by_pkeys=None)
バッチライターオブジェクトを作成する。
Amazon DynamoDBにオブジェクトを一括で書き込むためのコンテキストマネージャーを作成するメソッドです。
バッチライターは、自動的にバッファリングとアイテムの一括送信を処理します。さらに、バッチライターは未処理のアイテムも自動的に処理し、必要に応じて再送信します。追加したいアイテムがあればput_itemを、削除したいアイテムがあればdelete_itemを呼び出すだけでよいのです。
delete()
DeleteTableオペレーションは、テーブルとそのすべてのアイテムを削除します。DeleteTableリクエスト後、DynamoDBが削除を完了するまで、指定されたテーブルはDELETING状態にあります。テーブルがACTIVE状態であれば、削除することができます。テーブルがCREATINGまたはUPDATINGの状態である場合、DynamoDBはResourceInUseExceptionを返します。指定されたテーブルが存在しない場合、DynamoDBはResourceNotFoundExceptionを返します。テーブルがすでにDELETINGの状態である場合は、エラーは返されません。
Note
DynamoDBは、テーブルの削除が完了するまで、DELETING状態のテーブルに対するGetItemやPutItemなどのデータの読み取りおよび書き込み操作を受け付け続ける場合があります。
テーブルを削除すると、そのテーブル上のインデックスもすべて削除されます。
テーブル上でDynamoDB Streamsを有効にしている場合、そのテーブル上の対応するストリームはDISABLEDの状態になり、24時間後にストリームは自動的に削除されます。
テーブルの状態を確認するには、DescribeTableアクションを使用します。
See also: AWS API Documentation
delete_item(**kwargs)
テーブル内の項目を主キーで一つ削除する。項目が存在する場合、あるいは期待される属性値を持つ場合に、その項目を削除する条件付き削除操作を行うことができる。
項目を削除するだけでなく、ReturnValues パラメータを使って項目の属性値も同じ操作で返すことができます。
条件を指定しない限り、DeleteItemはべき乗の操作です。同じアイテムや属性に対して複数回実行しても、エラー応答は発生しません。
条件付き削除は、特定の条件を満たした場合のみアイテムを削除するのに便利です。条件を満たした場合、DynamoDBは削除を実行します。それ以外の場合は、アイテムは削除されません。
See also: AWS API Documentation
get_available_subresources()
この Resource で利用可能なすべてのサブリソースのリストを返します。
get_item(**kwargs)
GetItem 操作は、与えられた主キーを持つアイテムの属性セットを返す。一致する項目がない場合、GetItem はデータを返さず、応答には Item 要素は存在しない。
GetItem は、デフォルトで最終的に一貫性のある読み取りを行います。アプリケーションで強い一貫性のある読み取りを必要とする場合は、ConsistentRead を true に設定します。強い一貫性のある読み込みは、最終的な一貫性のある読み込みよりも時間がかかるかもしれませんが、常に最後に更新された値を返します。
See also: AWS API Documentation
load()
DynamoDB.Client.describe_table()を呼び出して、Tableリソースの属性を更新します。なお、loadとreloadは同じメソッドであり、使い分けが可能です。
See also: AWS API Documentation
put_item(**kwargs)
新しい項目を作成するか、古い項目を新しい項目で置き換えます。新しい項目と同じ主キーを持つ項目が指定されたテーブルに既に存在する場合、新しい項目は既存の項目を完全に置き換える。条件付き put 操作 (指定した主キーを持つ項目が存在しない場合に新しい項目を追加する) や、 既存の項目が特定の属性値を持つ場合にその項目を置き換えることができます。ReturnValuesパラメータを使えば、同じ操作でアイテムの属性値を返すことができます。
項目を追加する場合、必須となる属性は主キー属性のみです。属性値にはNULLは使えません。
空のStringおよびBinary属性値は使用可能です。テーブルまたはインデックスのキー属性として使用する場合、StringおよびBinary型の属性値は0より大きい長さを持つ必要があります。セットタイプの属性は空にすることはできません。
空の値を持つ無効なリクエストは、ValidationException例外で拒否されます。
Note
新しい項目が既存の項目を置き換えるのを防ぐには、attribute_not_exists関数とテーブルのパーティションキーとして使用されている属性の名前を含む条件式を使用します。すべてのレコードはその属性を含んでいなければならないので、attribute_not_exists関数は一致する項目が存在しない場合にのみ成功します。
PutItemの詳細については、Amazon DynamoDB開発者ガイドのWorking with Itemsを参照してください。
See also: AWS API Documentation
query(**kwargs)
パーティションキー属性の名前と、その属性の値を1つだけ指定する必要があります。クエリーはそのパーティション・キー値を持つすべてのアイテムを返します。オプションで、ソートキー属性を提供し、比較演算子を使用して検索結果を絞り込むことができます。
KeyConditionExpression パラメータを使用して、パーティション・キーに特定の値を指定します。Query操作は、そのパーティション・キー値を持つテーブルまたはインデックスからすべての項目を返します。オプションで、KeyConditionExpression にソート・キー値と比較演算子を指定することにより、クエリー操作の範囲を狭めることができます。Query の結果をさらに絞り込むために、オプションで FilterExpression を指定することができます。FilterExpression は、結果内のどの項目が返されるかを決定します。その他の結果はすべて破棄されます。
Query 操作は、常に結果セットを返します。一致する項目がない場合、結果セットは空になります。結果を返さないクエリは、そのタイプの読み取り操作のための最小限の読み取り容量ユニットを消費します。
Note
DynamoDBは、アプリケーションに返されるデータ量ではなく、アイテムサイズに基づいて消費される読み込み容量単位を計算します。消費される容量ユニットの数は、すべての属性を要求しても（デフォルトの動作）、それらの一部だけを要求しても（投影式を使用）同じになります。また、FilterExpression を使用してもしなくても、この数は同じになります。
クエリーの結果は、常にソートキーの値でソートされる。ソートキーのデータ型が Number の場合は数値順に、それ以外の場合は UTF-8 バイト順に結果が返されます。デフォルトでは、ソート順は昇順である。逆順にするには、ScanIndexForward パラメータを false に設定する。
1回の Query 操作で、設定された最大アイテム数 (Limit パラメータを使用した場合) または最大 1 MB のデータを読み取り、FilterExpression を使用して結果に任意のフィルタリングを適用します。LastEvaluatedKey が応答内に存在する場合、結果セットをページ分割する必要があります。詳細は、Amazon DynamoDB Developer Guide の Paginating the Results を参照してください。
FilterExpression は、Query が終了した後、結果が返される前に適用されます。FilterExpression には、パーティション・キーまたはソート・キーの属性を含めることはできません。これらの属性は、KeyConditionExpression で指定する必要があります。
Note
Query操作は、結果のページに対して読み取られたすべての項目がフィルタリングされた場合、空の結果セットとLastEvaluatedKeyを返すことがあります。
テーブル、ローカルセカンダリインデックス、またはグローバルセカンダリインデックスに問い合わせることができます。テーブルまたはローカルのセカンダリインデックスに対する問い合わせでは、ConsistentReadパラメータをtrueに設定すると、強い整合性のある結果を得ることができます。グローバルセカンダリインデックスは最終的に一貫性のある読み取りのみをサポートします。したがって、グローバルセカンダリインデックスへの問い合わせの際には ConsistentRead を指定しないでください。
See also: AWS API Documentation
reload()
DynamoDB.Client.describe_table()を呼び出して、Tableリソースの属性を更新します。なお、loadとreloadは同じメソッドであり、同じように使うことができます。
See also: AWS API Documentation
scan(**kwargs)
Scanオペレーションは、テーブルまたはセカンダリインデックス内のすべてのアイテムにアクセスして、1つまたは複数のアイテムおよびアイテムの属性を返します。DynamoDBが返すアイテムの数を減らすには、FilterExpressionオペレーションを指定します。
スキャンされたアイテムの合計数がデータセットの最大サイズ制限である1MBを超えた場合、スキャンは停止し、結果はLastEvaluatedKey値としてユーザーに返され、次の操作でスキャンを継続することができます。結果には、制限を超えたアイテムの数も含まれます。スキャンの結果、フィルタ条件を満たすテーブルデータがない場合もあります。
1 回のスキャン操作で、設定された最大項目数 (Limit パラメータを使用した場合) または最大 1 MB のデータを読み取り、その結果に対して FilterExpression を使用して任意のフィルタリングを適用します。応答に LastEvaluatedKey が存在する場合、結果セットをページ分割する必要があります。詳細は、Amazon DynamoDB Developer Guide の Paginating the Results を参照してください。
Scan操作はシーケンシャルに進みますが、大きなテーブルやセカンダリインデックスでより速いパフォーマンスを得るために、アプリケーションはSegmentとTotalSegmentsパラメータを指定して、パラレルScan操作を要求することができます。詳細については、Amazon DynamoDB開発者ガイドのParallel Scanを参照してください。
Scanは、テーブルのデータにアクセスする際に最終的に一貫した読み取りを使用するため、結果セットには操作の開始直前のテーブルのデータへの変更が含まれない場合があります。Scan開始時点の一貫したデータコピーが必要な場合は、ConsistentReadパラメータをtrueに設定します。
See also: AWS API Documentation
update(**kwargs)
指定したテーブルのプロビジョニングスループット設定、グローバルセカンダリインデックス設定、DynamoDB Streams設定を変更します。
一度に実行できるのは、以下の操作のいずれか1つだけです。
・テーブルのプロビジョニングスループット設定を変更します。
・テーブルからグローバルセカンダリーインデックスを削除する。
・テーブル上に新しいグローバルセカンダリインデックスを作成します。インデックスのバックフィルを開始した後、UpdateTable を使用して他の操作を実行することができます。
UpdateTableは非同期処理であり、実行中にテーブルの状態がACTIVEからUPDATINGに変化します。UPDATING の間は、別の UpdateTable 要求を発行することはできません。テーブルが ACTIVE 状態に戻ると、UpdateTable 操作は完了します。
See also: AWS API Documentation
update_item(**kwargs)
既存の項目の属性を編集し、まだ存在しない場合は新しい項目をテーブルに追加する。属性値の設定、削除、追加が可能である。また、既存の項目に対して条件付き更新を行うこともできる（新しい属性の名前と値のペアが存在しない場合はそれを挿入し、既存の名前と値のペアが特定の期待される属性値を持っている場合はそれを置き換える）。
また、ReturnValues パラメータを使用して、同じ UpdateItem 操作でアイテムの属性値を返すこともできます。
See also: AWS API Documentation
Waiters
Waiters は、リソースが特定の状態になるのを待つためのインターフェイスを提供します。ウェイターの詳細については、リソース入門ガイドを参照してください。
wait_until_exists()
このTableが存在するまで待ちます。このメソッドは、ポーリングするDynamoDB.Waiter.table_exists.wait()を呼び出します。DynamoDB.Client.describe_table()を20秒ごとにポーリングし、成功した状態になるまで待ちます。25回チェックに失敗すると、エラーが返されます。
See also: AWS API Documentation
wait_until_not_exists()
このTableが存在しなくなるまで待ちます。このメソッドは、ポーリングするDynamoDB.Waiter.table_not_exists.wait()を呼び出します。DynamoDB.Client.describe_table()を20秒ごとにポーリングし、成功した状態になるまで待ちます。25回チェックに失敗すると、エラーが返されます。
See also: AWS API Documentation