Create a table - Tablestore SDK for Python - Tablestore - Alibaba Cloud ドキュメントセンター

Tablestore SDK for Python を使用してテーブルを作成し、オプションでそのスキーマ、設定、セカンダリインデックス、データ暗号化を構成します。

前提条件

Tablestore SDK for Python をインストールし、クライアントを初期化します。

機能の説明

テーブルを作成するために、create_table メソッドを呼び出します。

def create_table(
    self,
    table_meta,
    table_options,
    reserved_throughput,
    secondary_indexes=None,
    sse_spec=None,
)

次の例では、example_table テーブルを作成します。このテーブルでは、id が主キー列となり、データは期限切れになることはなく、各属性列で保持されるバージョンは 1 つのみです。

table_meta = TableMeta(
    "example_table",
    [("id", "STRING")],
)
table_options = TableOptions(
    time_to_live=-1,
    max_version=1,
    max_time_deviation=86400,
    allow_update=True,
)
reserved_throughput = ReservedThroughput(CapacityUnit(0, 0))

client.create_table(table_meta, table_options, reserved_throughput)

説明

テーブルを作成した後、データ操作を実行する前に、テーブルが読み込まれるまで数秒待つ必要があります。

パラメータ

create_table メソッドには、以下のパラメーターが含まれています。

名前	タイプ	説明
table_meta (必須)	`TableMeta`	テーブルスキーマ。
table_options (必須)	`TableOptions`	テーブル設定。
reserved_throughput (必須)	`予約済みスループット`	予約済みスループット。
secondary_indexes (オプション)	`List[SecondaryIndexMeta]`	テーブルと一緒に作成するセカンダリインデックス。
sse_spec (オプション)	`SSESpecification`	サーバー側の暗号化設定。暗号化はテーブルの作成時にのみ有効にでき、後から無効にすることはできません。この機能を使用するには、Tablestore SDK for Python 6.4.0 以降が必要です。

テーブルスキーマ

table_meta パラメーターは TableMeta 型で、以下のパラメーターが含まれています。

名前	タイプ	説明
table_name (必須)	`str`	テーブルの名前。
schema_of_primary_key (必須)	`List[Tuple]`	プライマリキーのスキーマ。テーブルは 1 ～ 4 個のプライマリキー列を持つことができます。最初のプライマリキー列はパーティションキーであり、プライマリキー列は昇順でソートされます。プライマリキー列は、`STRING`、`INTEGER`、および `BINARY` 型をサポートします。`INTEGER` 型のパーティションキー以外のプライマリキー列は、自動増分プライマリキー列として設定できます。
defined_columns (オプション)	`List[Tuple]`	事前定義列は、`STRING`、`INTEGER`、`BINARY`、`DOUBLE`、および `BOOLEAN` 型をサポートしており、セカンダリインデックスや検索インデックスの作成に使用できます。

プライマリキー列

table_meta.schema_of_primary_key[] の各タプルは、1 つの主キー列を構成し、以下の要素を含みます。

名前	タイプ	説明
name (必須)	`str`	プライマリキー列の名前。
type (必須)	`str`	プライマリキー列の型。有効な値は `STRING`、`INTEGER`、および `BINARY` です。
option (オプション)	`PrimaryKeyOption`	プライマリキーのオプションです。`INTEGER` 型の非パーティションプライマリキー列を `PK_AUTO_INCR` に設定することで、自動インクリメントプライマリキー列にすることができます。

事前定義列

table_meta.defined_columns[] 内の各タプルは、1 つの事前定義列を構成し、以下の要素を含みます。

名前	タイプ	説明
name (必須)	`str`	事前定義列の名前。
type (必須)	`str`	定義済みの列の型。有効な値は `STRING`、`INTEGER`、`BINARY`、`DOUBLE`、および `BOOLEAN` です。

テーブル設定

table_options パラメーターは TableOptions 型で、以下のパラメーターを含みます。

名前	タイプ	説明
time_to_live (オプション)	`int`	データの有効期間 (TTL) を秒単位で指定します。デフォルト値は `-1` で、これはデータが無期限であることを示します。別の値を指定する場合、最小値は `86400` (1 日) です。期限切れのデータは自動的に削除されます。検索インデックスまたはセカンダリインデックスを使用するには、このパラメーターを `-1` に設定するか、`allow_update` を `False` に設定します。
max_version (オプション)	`int`	各属性列で保持するバージョンの最大数で、デフォルト値は `1` です。検索インデックスまたはセカンダリインデックスを使用するには、このパラメーターを `1` に設定します。
max_time_deviation (オプション)	`int`	秒単位の最大バージョン偏差。デフォルト値は `86400` (1 日) です。書き込むデータのタイムスタンプと現在のシステム時刻との差は、最大バージョン偏差の範囲内である必要があります。有効なバージョン範囲は `[max(データ書き込み時刻 - 最大バージョン偏差, データ書き込み時刻 - TTL), データ書き込み時刻 + 最大バージョン偏差)` です。
allow_update (オプション)	`bool`	`update_row` を呼び出してデータを更新できるかどうかを指定します。このパラメーターを指定しない場合、サーバーはデフォルトで更新を許可します。このパラメーターを `False` に設定した場合、 `update_row` を呼び出してデータを更新できません。

予約済みスループット

reserved_throughput パラメーターは ReservedThroughput 型で、次のパラメーターが含まれています。

名前	タイプ	説明
capacity_unit (必須)	`CapacityUnit`	キャパシティーユニット (CU) 単位の予約スループット。デフォルトの読み取りおよび書き込み CU は、どちらも `0` です。0 以外の値は、CU モードの高性能インスタンスでのみサポートされます。

キャパシティーユニット

reserved_throughput.capacity_unit パラメーターは CapacityUnit タイプで、次のパラメーターが含まれます。

名前	タイプ	説明
read (オプション)	`int`	CU 単位の予約済み読み取りスループット。デフォルト値は `0` です。
write (オプション)	`int`	CU 単位の予約済み書き込みスループット。デフォルト値は `0` です。

セカンダリインデックス

secondary_indexes[] の各要素は SecondaryIndexMeta 型で、以下のパラメーターを含みます。

名前	タイプ	説明
index_name (必須)	`文字列`	インデックスの名前。
primary_key_names (必須)	`List[str]`	インデックスのプライマリキー列。テーブルのプライマリキー列と事前定義列を使用できます。ローカルセカンダリインデックスの場合、インデックスの最初のプライマリキー列はテーブルの最初のプライマリキー列と同じである必要があります。
defined_column_names (オプション)	`List[str]`	インデックスに含まれる事前定義列。列はテーブル内ですでに定義されている必要があります。
index_type (オプション)	`SecondaryIndexType`	インデックスのタイプ。有効な値は、グローバルセカンダリインデックスのデフォルト値である `GLOBAL_INDEX` と、ローカルセカンダリインデックス用の `LOCAL_INDEX` です。

サーバー側の暗号化設定

sse_spec パラメーターは SSESpecification 型で、次のパラメーターが含まれています。

名前	タイプ	説明
enable (オプション)	`bool`	データ暗号化を有効にするかどうかを指定します。デフォルト値は `False` です。
key_type (オプション)	`SSEKeyType`	暗号化タイプ。有効な値は、KMS マネージドキー暗号化の `SSE_KMS_SERVICE` と、Bring-Your-Own-Key (BYOK) 暗号化の `SSE_BYOK` です。このパラメーターは、暗号化が有効な場合に必須です。
key_id (オプション)	`str`	カスタマーマスターキー ID。BYOK 暗号化の場合、このパラメータは必須です。
role_arn (オプション)	`str`	RAM ロールの Alibaba Cloud Resource Name (ARN)。BYOK 暗号化の場合、このパラメータは必須です。

例

テーブルスキーマとデータバージョンの構成

次の例では、事前定義された列 name を追加し、各属性列に対して最大 3 つのバージョンを保持します。

table_meta = TableMeta(
    "example_table",
    [("id", "STRING")],
    [("name", "STRING")],
)
table_options = TableOptions(
    time_to_live=-1,
    max_version=3,
    max_time_deviation=86400,
    allow_update=True,
)
reserved_throughput = ReservedThroughput(CapacityUnit(0, 0))

client.create_table(table_meta, table_options, reserved_throughput)

テーブルと一緒にセカンダリインデックスを作成

次の例では、テーブルとともにローカルセカンダリインデックスを作成します。テーブルとセカンダリインデックスの両方の最初のプライマリキー列は id です。

table_meta = TableMeta(
    "example_table",
    [("id", "STRING"), ("device_id", "INTEGER")],
    [("status", "STRING")],
)
table_options = TableOptions(time_to_live=-1, max_version=1)
reserved_throughput = ReservedThroughput(CapacityUnit(0, 0))
secondary_indexes = [
    SecondaryIndexMeta(
        "example_local_index",
        ["id", "device_id"],
        ["status"],
        index_type=SecondaryIndexType.LOCAL_INDEX,
    )
]

client.create_table(
    table_meta,
    table_options,
    reserved_throughput,
    secondary_indexes=secondary_indexes,
)

テーブルの暗号化

次の例では、KMS マネージドキーと BYOK (Bring-Your-Own-Key) を使用してテーブルを暗호화します。

重要

暗号化は、テーブルの作成時にのみ有効にでき、後から無効にすることはできません。

KMS マネージドキー

sse_spec = SSESpecification(
    enable=True,
    key_type=SSEKeyType.SSE_KMS_SERVICE,
)

client.create_table(
    table_meta,
    table_options,
    reserved_throughput,
    sse_spec=sse_spec,
)

Bring-Your-Own-Key (BYOK) 暗号化

BYOK 暗号化を使用する前に、カスタマーマスターキー ID と RAM ロール ARN を取得してください。詳細については、「データ暗号化」をご参照ください。

sse_spec = SSESpecification(
    enable=True,
    key_type=SSEKeyType.SSE_BYOK,
    key_id="key-example",
    role_arn="acs:ram::1234567890123456:role/example-role",
)

client.create_table(
    table_meta,
    table_options,
    reserved_throughput,
    sse_spec=sse_spec,
)