本頁說明如何在資料庫中建立及管理分割點。您可以建立分割點,預先分割資料庫,為預期流量增加做好準備。如要進一步瞭解預先分割,請參閱預先分割總覽。
事前準備
-
如要取得建立及管理分割點所需的權限,請要求管理員授予您執行個體的 Cloud Spanner 資料庫管理員 (
roles/spanner.databaseAdmin
) IAM 角色。如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和機構的存取權」。這個預先定義的角色具備
spanner.databases.addSplitPoints
權限,可建立及管理分割點。 本頁面的 gcloud CLI 範例具有以下假設:
- 您已設定 gcloud CLI,可搭配 Spanner 使用。如果您是第一次使用 gcloud CLI 搭配 Spanner,請參閱「使用 gcloud CLI 建立及查詢資料庫」。
您已使用專案設定 gcloud CLI。例如:
gcloud config set core/project PROJECT_ID
請確認 Spanner 執行個體有足夠的節點,可支援預期增加的流量。詳情請參閱預先分割總覽。
建立分割點
您可以使用 Google Cloud CLI 或 REST API 建立分割點。
gcloud
如要使用 Google Cloud CLI 建立分割點,請建立包含所有分割點的檔案,並在 gcloud CLI 指令中提供路徑。檔案不得超過 API 限制,即每個 API 要求 100 點。詳情請參閱配額與限制。
檔案必須使用以下格式指定分割點:
ObjectType ObjectName (SplitValue1)
ObjectType ObjectName (SplitValue2)
ObjectType ObjectName (SplitValueN)
建立檔案時,請替換下列變數:
- ObjectType:要新增分割的物件類型。有效值為
TABLE
和INDEX
。 - ObjectName:資料庫資料表或索引的名稱。
- SplitValue1..N:要導入分割的分割點值。
在檔案中建立分割點值時,請遵守下列規則:
- 字串值必須加上單引號。例如
'splitKeyPart'
。 - 布林值必須為
true
或false
。 INT64
和NUMERIC
Spanner 資料類型值必須以單引號括住。例如'123'
或'99.99'
。- 其他數字值則不需加上單引號。例如
1.287
。 - 時間戳記值應以單引號括住,並採用
'2020-06-18T17:24:53Z'
格式。 - 分割值必須以半形括號括住。
- 分割鍵值順序必須與主鍵順序相同。
- 如果分割值需要半形逗號,請使用 `\` 字元逸出半形逗號。
- 如要分割索引,您可以提供索引鍵或整個索引和完整的資料表鍵。
- 指定分割點時,您一律必須使用完整鍵。
以下是範例檔案,說明如何指定分割點:
TABLE Singers ('c32ca57a-786c-2268-09d4-95182a9930be')
TABLE Singers ('bb98c7e2-8240-b780-346d-c5d63886594a')
INDEX Order ('5b8bac71-0cb2-95e9-e1b0-89a027525460')
TABLE Payment ('6cf41f21-2d77-318f-c504-816f0068db8b')
INDEX Indx_A (2152120141932780000)
TABLE TableD (0,'7ef9d̦b22-d0e5-6041-8937-4bc6a7ef9db2')
INDEX IndexXYZ ('8762203435012030000',NULL,NULL)
INDEX IndexABC (0, '2020-06-18T17:24:53Z', '2020-06-18T17:24:53Z') TableKey
(123,'ab\,c')
使用下方的任何指令資料之前,請先替換以下項目:
- SPLITS_FILE:分割檔案的路徑。
- INSTANCE_ID:執行個體 ID。
- DATABASE_ID:資料庫 ID。
-
EXPIRATION_DATE:
(選填) 分攤點數的到期日。接受
'2020-06-18T17:24:53Z'
格式的時間戳記。 - INITIATOR:(選用) 分割點的啟動者。
執行下列指令:
Linux、macOS 或 Cloud Shell
gcloud spanner databases splits add DATABASE_ID \ --splits-file=SPLITS_FILE \ --instance=INSTANCE_ID \ --split-expiration-date=EXPIRATION_DATE \ --initiator=INITIATOR
Windows (PowerShell)
gcloud spanner databases splits add DATABASE_ID ` --splits-file=SPLITS_FILE ` --instance=INSTANCE_ID ` --split-expiration-date=EXPIRATION_DATE ` --initiator=INITIATOR
Windows (cmd.exe)
gcloud spanner databases splits add DATABASE_ID ^ --splits-file=SPLITS_FILE ^ --instance=INSTANCE_ID ^ --split-expiration-date=EXPIRATION_DATE ^ --initiator=INITIATOR
REST v1
您可以使用 projects.instances.databases.addSplitPoints
方法建立分割點。
使用任何要求資料之前,請先替換以下項目:
- PROJECT_ID:專案 ID。
- INSTANCE_ID:執行個體 ID。
- DATABASE_ID:資料庫 ID。
HTTP 方法和網址:
POST https://spanner.googleapis.com/v1/projects//instances/ /databases/ :addSplitPoints
JSON 要求主體:
{ "split_points": [ { "table": "T1", "index": "T1_IDX", "expire_time": "2023-04-22T10:00:20.021Z", "keys": [ { "key_parts": { "values": [ 3 ] } }, { "key_parts": { "values": [ 10 ] } } ] }, { "table": "T2", "expire_time": "2023-04-22T10:00:20.021Z", "keys": [ { "key_parts": { "values": [ 50 ] } } ] } ] }
如要傳送要求,請展開以下其中一個選項:
您應該會收到執行成功的狀態碼 (2xx) 和空白回應。
用戶端程式庫
Go
Java
Node.js
Python
可能發生的錯誤情境
在下列情況下建立分割點時,可能會發生錯誤:
- 索引層級分割的輸入內容中,資料表名稱有誤。
- 表格層級分割點有多個鍵。
- 索引層級分割點超過兩個鍵。
- 分割點是在資料庫結構定義中未定義的資料表或索引上定義。
- 要求包含重複的分割點。
如要瞭解配額和限制,請參閱配額和限制。
查看分割點
您可以使用Google Cloud 控制台或 gcloud CLI,查看資料庫中建立的所有分割點:
控制台
如要查詢 Google Cloud 控制台中的 SPANNER_SYS.USER_SPLIT_POINTS
檢視畫面,取得分割點數量,請按照下列步驟操作:
開啟 Spanner 執行個體頁面。
選取要查詢的 Spanner 執行個體和資料庫名稱。
按一下左側導覽面板中的「Spanner Studio」。
在文字欄位中輸入下列查詢:
SELECT * FROM SPANNER_SYS.USER_SPLIT_POINTS
點選「執行查詢」
系統會顯示類似以下內容的結果:
TABLE_NAME | INDEX_NAME | INITIATOR | SPLIT_KEY | EXPIRE_TIME |
---|---|---|---|---|
T | CloudAddSplitPointsAPI | T(90,153,4,2024-04-30T17:00:00-07:00,1,2024-05-01,a) | 2025-03-06T09:58:58.007201Z | |
T | T_IDX | CloudAddSplitPointsAPI | 索引:T 上的 T_IDX,索引鍵:(10),主要資料表鍵:(<begin>,<begin>,<begin>,<begin>,<begin>,<begin>,<begin>) | 2025-03-08T07:33:23.861682Z |
T | T_IDX | CloudAddSplitPointsAPI | 索引:T_IDX on T,索引鍵:(9091),主要資料表鍵:(4567,123,4.2,2024-04-30T17:00:00-07:00,1,2024-05-01,a) | 2025-03-08T07:35:25.990007Z |
gcloud
執行下列 gcloud CLI 指令,即可查看資料庫中的分割點:
gcloud spanner databases splits list DATABASE_ID \
--instance INSTANCE_ID
執行這項指令時,請替換下列變數:
- INSTANCE_ID:Spanner 執行個體 ID。
- DATABASE_ID:Spanner 資料庫 ID。
系統會顯示類似以下的回應:
TABLE_NAME: T
INDEX_NAME:
INITIATOR: CloudAddSplitPointsAPI
SPLIT_KEY: T(90,153,4,2024-04-30T17:00:00-07:00,1,2024-05-01,a)
EXPIRE_TIME: 2025-03-06T09:58:58.007201Z
TABLE_NAME: T
INDEX_NAME: T_IDX
INITIATOR: CloudAddSplitPointsAPI
SPLIT_KEY: Index: T_IDX on T, Index Key: (10), Primary Table Key: (<begin>,<begin>,<begin>,<begin>,<begin>,<begin>,<begin>)
EXPIRE_TIME: 2025-03-08T07:33:23.861682Z
TABLE_NAME: T
INDEX_NAME: T_IDX
INITIATOR: CloudAddSplitPointsAPI
SPLIT_KEY: Index: T_IDX on T, Index Key: (9091), Primary Table Key: (4567,123,4.2,2024-04-30T17:00:00-07:00,1,2024-05-01,a)
EXPIRE_TIME: 2025-03-08T07:35:25.990007Z
如何讓分割點失效
您可以為建立的每個分割點設定到期時間。詳情請參閱「分割點到期」。您可以使用 Google Cloud CLI 或 REST API,讓分割點過期。
gcloud
如要使用 Google Cloud CLI 讓分割點過期,請建立檔案,其中包含所有要過期的分割點,並在 gcloud CLI 指令中使用 splits-file
參數提供檔案路徑。檔案不得超過 API 限制,即每個 API 要求 100 點。詳情請參閱配額與限制。
檔案必須使用以下格式指定分割點:
ObjectType ObjectName (SplitValue)
ObjectType ObjectName (SplitValue)
ObjectType ObjectName (SplitValue)
建立檔案時,請替換下列變數:
- ObjectType:要過期的分割物件類型。有效值為
TABLE
和INDEX
。 - ObjectName:資料庫資料表或索引的名稱。
- SplitValue:要過期的分割點值。
在檔案中建立分割點值時,請遵守下列規則:
- 字串值必須加上單引號。例如
'splitKeyPart'
。 - 布林值可以是
true
或false
。 INT64
和NUMERIC
Spanner 資料類型值必須以單引號括住。例如'123'
或'99.99'
。- 其他數字值則不需加上單引號。例如
1.287
。 - 時間戳記值應以單引號括住,並採用
'2020-06-18T17:24:53Z'
格式。 - 分割值必須以半形括號括住。
- 分割鍵值順序必須與主鍵順序相同。
- 如果分割值需要半形逗號,請使用 `\` 字元逸出半形逗號。
- 如要分割索引,您可以提供索引鍵或整個索引和完整的資料表鍵。
- 指定分割點時,您一律必須使用完整鍵。
以下是範例檔案,說明如何指定分割點:
TABLE Singers ('c32ca57a-786c-2268-09d4-95182a9930be')
TABLE Singers ('bb98c7e2-8240-b780-346d-c5d63886594a')
INDEX Order ('5b8bac71-0cb2-95e9-e1b0-89a027525460')
TABLE Payment ('6cf41f21-2d77-318f-c504-816f0068db8b')
INDEX Indx_A (2152120141932780000)
TABLE TableD (0,'7ef9db22-d0e5-6041-8937-4bc6a7ef9db2')
INDEX IndexXYZ ('8762203435012030000',NULL,NULL)
INDEX IndexABC (0, '2020-06-18T17:24:53Z', '2020-06-18T17:24:53Z') TableKey
(123,'ab\,c')
使用下方的任何指令資料之前,請先替換以下項目:
- SPLITS_FILE:分割檔案的路徑。
- INSTANCE_ID:執行個體 ID。
- DATABASE_ID:資料庫 ID。
-
EXPIRATION_DATE:
(選填) 分攤點數的到期日。接受
'2020-06-18T17:24:53Z'
格式的時間戳記。 - INITIATOR:(選用) 分割點的啟動者。
執行下列指令:
Linux、macOS 或 Cloud Shell
gcloud spanner databases splits add DATABASE_ID \ --splits-file=SPLITS_FILE \ --instance=INSTANCE_ID \ --split-expiration-date=EXPIRATION_DATE \ --initiator=INITIATOR
Windows (PowerShell)
gcloud spanner databases splits add DATABASE_ID ` --splits-file=SPLITS_FILE ` --instance=INSTANCE_ID ` --split-expiration-date=EXPIRATION_DATE ` --initiator=INITIATOR
Windows (cmd.exe)
gcloud spanner databases splits add DATABASE_ID ^ --splits-file=SPLITS_FILE ^ --instance=INSTANCE_ID ^ --split-expiration-date=EXPIRATION_DATE ^ --initiator=INITIATOR
REST v1
使用任何要求資料之前,請先替換以下項目:
- PROJECT_ID:專案 ID。
- INSTANCE_ID:執行個體 ID。
- DATABASE_ID:資料庫 ID。
HTTP 方法和網址:
POST https://spanner.googleapis.com/v1/projects//instances/ /databases/ :addSplitPoints
JSON 要求主體:
{ "split_points": [ { "table": "T1", "index": "T1_IDX", "expire_time": "2023-04-22T10:00:20.021Z", "keys": [ { "key_parts": { "values": [ 3 ] } }, { "key_parts": { "values": [ 10 ] } } ] }, { "table": "T2", "expire_time": "2023-04-22T10:00:20.021Z", "keys": [ { "key_parts": { "values": [ 50 ] } } ] } ] }
如要傳送要求,請展開以下其中一個選項:
您應該會收到執行成功的狀態碼 (2xx) 和空白回應。