Table Store Python SDK 建立資料表 - Tablestore

使用 Python SDK 建立資料表，並按需配置表結構、表配置、二級索引和資料加密。

前提條件

功能說明

調用 create_table 方法建立資料表。

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

以下樣本建立主鍵列為 id 的 example_table 資料表。表中資料永不到期，每個屬性列最多保留一個版本。

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（必選）	`ReservedThroughput`	預留讀寫輸送量。
secondary_indexes（可選）	`List[SecondaryIndexMeta]`	隨資料表建立的二級索引列表。
sse_spec（可選）	`SSESpecification`	服務端加密配置。資料加密只能在建立資料表時開啟，建立後無法關閉。此功能需要 Python SDK 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[] 使用元組配置一個主鍵列，包含以下元素。

名稱	類型	說明
name（必選）	`str`	主鍵列名稱。
type（必選）	`str`	主鍵列類型。取值為 `STRING`、`INTEGER` 或 `BINARY`。
option（可選）	`PrimaryKeyOption`	主鍵列選項。將非分區鍵的 `INTEGER` 類型主鍵列設定為 `PK_AUTO_INCR` 時，該列為自增主鍵列。

預定義列

table_meta.defined_columns[] 使用元組配置一個預定義列，包含以下元素。

名稱	類型	說明
name（必選）	`str`	預定義列名稱。
type（必選）	`str`	預定義列類型。取值為 `STRING`、`INTEGER`、`BINARY`、`DOUBLE` 或 `BOOLEAN`。

表配置

table_options 的類型為 TableOptions，包含以下參數。

名稱	類型	說明
time_to_live（可選）	`int`	資料生命週期，單位為秒，預設值為 `-1`。設定為 `-1` 表示資料永不到期；設定為其他值時，最小值為 `86400`（1 天），超出生命週期的資料將被自動清除。使用多元索引或二級索引時，必須設定為 `-1`，或將 `allow_update` 設定為 `False`。
max_version（可選）	`int`	每個屬性列最多保留的版本數，預設值為 `1`。使用多元索引或二級索引時，必須設定為 `1`。
max_time_deviation（可選）	`int`	有效版本偏差，單位為秒，預設值為 `86400`（1 天）。寫入資料的時間戳記與系統目前時間的差值必須在有效版本偏差範圍內。屬性列資料的有效版本範圍為 `[max(資料寫入時間-有效版本偏差, 資料寫入時間-資料生命週期), 資料寫入時間+有效版本偏差)`。
allow_update（可選）	`bool`	是否允許通過 `update_row` 方法更新資料。不設定時，服務端預設允許更新；設定為 `False` 時，無法通過 `update_row` 方法更新資料。

預留讀寫輸送量

reserved_throughput 的類型為 ReservedThroughput，包含以下參數。

名稱	類型	說明
capacity_unit（必選）	`CapacityUnit`	預留讀寫輸送量，單位為 CU。預設讀 CU 和寫 CU 均為 `0`；僅 CU 模式的高效能型執行個體支援設定非零值。

容量單元

reserved_throughput.capacity_unit 的類型為 CapacityUnit，包含以下參數。

名稱	類型	說明
read（可選）	`int`	預留讀輸送量，單位為 CU，預設值為 `0`。
write（可選）	`int`	預留寫輸送量，單位為 CU，預設值為 `0`。

二級索引

secondary_indexes[] 的類型為 SecondaryIndexMeta，包含以下參數。

名稱	類型	說明
index_name（必選）	`str`	索引名稱。
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`	加密類型。取值為 `SSE_KMS_SERVICE`（KMS 服務祕密金鑰加密）或 `SSE_BYOK`（BYOK 加密）。開啟資料加密時必須設定。
key_id（可選）	`str`	使用者主要金鑰 ID。使用 BYOK 加密時必須設定。
role_arn（可選）	`str`	RAM 角色 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 加密資料表。

重要

資料加密只能在建立資料表時開啟，建立完成後無法關閉。

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

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