建立及管理資料刊登位置

注意：這項功能適用於 Spanner Enterprise Plus 版本。詳情請參閱 Spanner 版本總覽。

本頁說明如何在 Spanner 中建立及管理資料放置位置。

如要進一步瞭解地理位置分區的運作方式，請參閱地理位置分區總覽。

管理路由中繼資料

應用程式需要讀取或寫入資料時，Spanner 會使用路由中繼資料，找出哪些伺服器持有特定所需資料列。

選擇路由中繼資料的存放位置時，請考量大多數用戶端要求是針對相同區域內的資料還是區域外的資料，以及您是否使用多區域設定。放送位置建立後，就無法變更路由中繼資料設定，這會影響延遲。

per_placement_routing_metadata 選項會根據下列設定，決定路由中繼資料的所在位置：

• TRUE：如果設為 TRUE，轉送中繼資料會與資料位於相同的執行個體分割區。路由中繼資料會依區域分片。這樣一來，Spanner 就不必為路由中繼資料發出區域外呼叫，可減少區域內資料要求 (也就是用戶端和所要求的使用者資料位於同一區域) 的延遲時間。不過，這項設定可能會增加區域外要求、沒有刊登位置列的負向查詢，以及需要全域索引的查詢延遲。

  如果預期大部分要求都是針對與用戶端位於同一區域的使用者資料提出，且預設分割區沒有與所有執行個體分割區共置的讀寫或唯讀區域，建議您使用這項設定。

• FALSE：路由中繼資料集中在預設分割區。

  如果您預期用戶端會經常查詢區域外資料，建議使用這項設定。舉例來說，歐盟地區的用戶端查詢美國使用者的資料。

  如果預設執行個體分割區使用多區域設定，且該設定提供的讀寫或唯讀區域與所有執行個體分割區位於同一位置，也請考慮使用這項設定。使用這項設定時，系統會將完整路由中繼資料的副本，儲存在預設執行個體分割區的每個副本中。因此，所有具有執行個體分區的區域都會有路由中繼資料的副本。這樣一來，區域內和區域外的要求都能在本機查詢路由中繼資料。

注意： 2026 年 7 月前，預設值為 FALSE。2026 年 7 月起，預設值為 TRUE。預設值變更前後建立的資料庫，延遲結果可能有所不同。建議您明確設定這個選項，以免發生非預期的變更。

設定 per_placement_routing_metadata 選項

注意： 如果已有資料刊登位置，設定這個選項就會失敗。

如要在 Google Cloud 控制台中設定 per_placement_routing_metadata，請更新資料庫結構定義中的這個選項。如要瞭解如何更新結構定義，請參閱「更新結構定義」。

per_placement_routing_metadata 選項接受布林值。如果此選項為 TRUE，則路由中繼資料會與資料位於相同的執行個體分割區。如果為 FALSE，則路由中繼資料會位於預設執行個體分區中。

以下範例顯示用來設定這項選項的 GoogleSQL ALTER DATABASE 指令：

ALTER DATABASE DATABASE_NAME SET OPTIONS ( per_placement_routing_metadata = METADATA_BOOLEAN)

更改下列內容：

• DATABASE_NAME：資料庫名稱。
• METADATA_BOOLEAN：per_placement_routing_metadata 的值。如果 TRUE，則路由中繼資料會與資料位於相同的執行個體分割區。如果 FALSE，則路由中繼資料會位於預設執行個體分區中。

建立資料放置位置

建立 Spanner 執行個體分割區和資料庫，並設定 per_placement_routing_metadata 選項後，即可建立刊登位置。

控制台

1. 前往 Google Cloud 控制台的「Instances」(執行個體) 頁面。

   執行個體

2. 選取含有使用者建立執行個體分區的執行個體。

3. 選取要分割資料的資料庫。

4. 在導覽選單中，按一下「Spanner Studio」。

5. 在「Spanner Studio」頁面中，按一下「新增分頁」，或使用空白的編輯器分頁。

6. 輸入 CREATE PLACEMENT(GoogleSQL、PostgreSQL) DDL 陳述式。

   舉例來說，您可以執行下列指令，在執行個體分區 europe-partition 中建立刊登位置資料表 europeplacement：

   GoogleSQL

   CREATE PLACEMENT europeplacement OPTIONS (instance_partition="europe-partition");
   

   PostgreSQL

   CREATE PLACEMENT europeplacement WITH (instance_partition='europe-partition');
   

   選用：您也可以使用「物件總管」窗格查看、搜尋及操作刊登位置物件。詳情請參閱「探索資料」一文。

7. 按一下「執行」。

gcloud

如要使用 Google Cloud CLI 指令建立刊登位置，請使用 gcloud spanner databases ddl update。

舉例來說，在執行個體分區 europe-partition 中建立刊登位置：

GoogleSQL

gcloud spanner databases ddl update example-db \
  --instance=test-instance \
  --ddl="CREATE PLACEMENT europeplacement OPTIONS (instance_partition='europe-partition')"

PostgreSQL

gcloud spanner databases ddl update example-db \
  --instance=test-instance \
  --ddl="CREATE PLACEMENT europeplacement WITH (instance_partition='europe-partition')"

設定刊登位置的預設領導者

如果刊登位置位於多區域，您可以設定刊登位置的預設主要區域。新的主要區域必須是多區域放置位置內的兩個讀寫區域之一。詳情請參閱「多區域可用設定」表格。

如未設定主要區域，刊登位置會使用位置指定的預設主要區域。如需各個多區域位置的主要區域清單，請參閱「多區域可用設定」表格。預設主要區域會以 L 表示。舉例來說，nam8 的預設主要區域位於洛杉磯(us-west2)。以下說明如何將其設為奧勒岡州(us-west1)。

控制台

1. 前往 Google Cloud 控制台的「Instances」(執行個體) 頁面。

   執行個體

2. 選取含有使用者建立執行個體分區的執行個體。

3. 選取要分割資料的資料庫。

4. 在導覽選單中，按一下「Spanner Studio」。

5. 在「Spanner Studio」頁面中，按一下「新增分頁」，或使用空白的編輯器分頁。

6. 輸入 CREATE PLACEMENT(GoogleSQL、PostgreSQL) DDL 陳述式。

   舉例來說，您可以執行下列指令，在執行個體分區 nam8-partition 中建立放置位置資料表 nam8placement，並將預設領導者位置設為 us-west1：

   GoogleSQL

   CREATE PLACEMENT `nam8placement`
     OPTIONS (instance_partition="nam8-partition", default_leader="us-west1");
   

   PostgreSQL

   CREATE PLACEMENT nam8placement WITH (instance_partition='nam8-partition', default_leader='us-west1');
   

   選用：您也可以使用「物件總管」窗格查看、搜尋及操作刊登位置物件。詳情請參閱「探索資料」一文。

7. 按一下「執行」。

gcloud

如要使用 gcloud CLI 指令建立位置，請使用 gcloud spanner databases ddl update。

舉例來說，在執行個體分割區 nam8-partition 中建立刊登位置資料表 nam8placement，並將預設領導者位置設為 us-west1：

GoogleSQL

gcloud spanner databases ddl update example-db \
  --instance=test-instance \
  --ddl="CREATE PLACEMENT nam8placement \
     OPTIONS (instance_partition='nam8-partition', default_leader='us-west1')"

PostgreSQL

gcloud spanner databases ddl update example-db \
  --instance=test-instance \
  --ddl="CREATE PLACEMENT nam8placement WITH (instance_partition='nam8-partition', default_leader='us-west1')"

捨棄資料放置位置

放置位置前，請務必先移除位置中的所有列資料。完成後，您可以使用 Google Cloud 控制台或 gcloud CLI 捨棄刊登位置。

控制台

1. 在導覽選單中，按一下「Spanner Studio」。
2. 在「Spanner Studio」頁面中，按一下「新增分頁」，或使用空白的編輯器分頁。

3. 輸入 DROP PLACEMENT(GoogleSQL、PostgreSQL) DDL 陳述式。

   舉例來說，您可以執行下列指令來捨棄刊登位置表格 europeplacement：

   GoogleSQL

   DROP PLACEMENT europeplacement;
   

   PostgreSQL

   DROP PLACEMENT europeplacement;
   

gcloud

如要使用 gcloud CLI 指令捨棄位置，請使用 gcloud spanner databases ddl update。

舉例來說，捨棄刊登位置 europeplacement：

gcloud spanner databases ddl update example-db \
  --instance=test-instance \
  --ddl="DROP PLACEMENT europeplacement"

放置錯誤

如果版位正在使用中，DROP PLACEMENT 作業就會失敗，並顯示類似「Statement failed: Placement PLACEMENT_NAME can't be dropped because it is in use by placement table PLACEMENT_TABLE_NAME.」(陳述式失敗：版位 PLACEMENT_NAME 無法捨棄，因為版位表格 PLACEMENT_TABLE_NAME 正在使用中) 的錯誤訊息。如果遇到這個錯誤，請完成下列步驟：

1. 修改應用程式，停止插入或更新要捨棄的刊登位置資料列。

2. 請採取下列任一項做法：

   • 使用分區 DML 陳述式 (如下所示)，將使用要刪除刊登位置的現有刊登位置資料列移至其他刊登位置：

     UPDATE PLACEMENT_TABLE_NAME SET LOCATION = NEW_PLACEMENT_NAME
     WHERE LOCATION = ORIGINAL_PLACEMENT_NAME;
     

   • 使用分區 DML 陳述式刪除刊登位置資料列，例如：

     DELETE FROM PLACEMENT_TABLE_NAME
     WHERE LOCATION = ORIGINAL_PLACEMENT_NAME;
     

     先前的刊登位置專屬 DML 陳述式僅適用於分區 DML。這些陳述式會像一般 DML 陳述式一樣失敗。詳情請參閱「限制」一節。您也可以使用修改作業 API 移動或捨棄刊登位置列。

取消 DROP PLACEMENT 作業

在長時間執行的作業從資料庫結構定義中完全刪除刊登位置之前，您隨時可以取消 DROP PLACEMENT 作業。如要瞭解如何取得長時間執行的作業 ID 來檢查狀態，或取消作業，請參閱「管理及監控長時間執行的作業」。

建立含有放置位置鍵的資料表

控制台

1. 在導覽選單中，按一下「Spanner Studio」。
2. 在「Spanner Studio」頁面中，按一下「新增分頁」，或使用空白的編輯器分頁。

3. 輸入 CREATE TABLE (GoogleSQL、PostgreSQL) DDL 陳述式。

   舉例來說，您可以建立 Singers 資料表，使用刊登位置鍵將歌手資料分區：

   GoogleSQL

   CREATE TABLE Singers (
     SingerId INT64 NOT NULL,
     SingerName STRING(MAX) NOT NULL,
     ...
     Location STRING(MAX) NOT NULL PLACEMENT KEY
   ) PRIMARY KEY (SingerId);
   

   PostgreSQL

   CREATE TABLE Singers (
     SingerId bigint PRIMARY KEY,
     SingerName varchar(1024),
     ...
     Location varchar(1024) NOT NULL PLACEMENT KEY
   );
   

gcloud

如要建立資料表，請使用 gcloud spanner databases ddl update。

舉例來說，您可以建立 Singers 資料表，使用刊登位置鍵將歌手資料分區：

GoogleSQL

gcloud spanner databases ddl update example-db \
  --instance=test-instance \
  --ddl="CREATE TABLE Singers ( SingerId INT64 NOT NULL, SingerName STRING(MAX) NOT NULL, Location STRING(MAX) NOT NULL PLACEMENT KEY ) PRIMARY KEY (SingerId);"

PostgreSQL

gcloud spanner databases ddl update example-db \
  --instance=test-instance \
  --ddl="CREATE TABLE Singers ( SingerId bigint PRIMARY KEY, SingerName varchar(1024), Location varchar(1024) NOT NULL PLACEMENT KEY );"

使用刊登位置鍵編輯表格

您無法從資料表捨棄刊登位置鍵。資料表建立後，您也無法在其中新增放置位置鍵。不過，您可以使用 ALTER TABLE (GoogleSQL、PostgreSQL) DDL 陳述式變更資料表中的其他欄位，例如新增及捨棄非放置鍵欄。

使用刊登位置鍵刪除資料表

如要刪除含有刊登位置鍵的資料表，請先完成下列步驟：

1. 刪除刊登位置表格中的所有資料列。
2. 等待資料庫通過 version_retention_period。詳情請參閱「時間點復原」。 然後按照下列步驟操作：

控制台

1. 在導覽選單中，按一下「Spanner Studio」。
2. 在「Spanner Studio」頁面中，按一下「新增分頁」，或使用空白的編輯器分頁。

3. 輸入 DROP TABLE (GoogleSQL、PostgreSQL) DDL 陳述式。

   舉例來說，如要捨棄 Singers 資料表，請執行以下指令：

   DROP TABLE Singers;
   

gcloud

如要捨棄資料表，請使用 gcloud spanner databases ddl update。

舉例來說，如要捨棄 Singers 資料表，請執行以下指令：

gcloud spanner databases ddl update example-db \
  --instance=test-instance \
  --ddl="DROP TABLE Singers"

在刊登位置表格中插入資料列

控制台

1. 在導覽選單中，按一下「Spanner Studio」。
2. 在「Spanner Studio」頁面中，按一下「新增分頁」，或使用空白的編輯器分頁。

3. 輸入 INSERT INTO (GoogleSQL、PostgreSQL) DDL 陳述式。

   舉例來說，將歌手 Marc Richards 新增至 Singers 資料表，並在 europeplacement 中進行分割：

   INSERT INTO Singers(SingerId, SingerName, Location)
   VALUES (1, 'Marc Richards', 'europeplacement')
   

gcloud

如要將資料寫入資料表，請使用 gcloud spanner rows insert。

舉例來說，將歌手 Marc Richards 新增至 Singers 資料表，並在 europeplacement 中進行分割：

gcloud spanner rows insert --table=Singers --database=example-db \
  --instance=test-instance --data=SingerId=1,SingerName='Marc Richards',Location='europeplacement'

更新刊登位置表格中的資料列

控制台

1. 在導覽選單中，按一下「Spanner Studio」。
2. 在「Spanner Studio」頁面中，按一下「新增分頁」，或使用空白的編輯器分頁。

3. 使用 DML 或變異更新刊登位置資料表中的資料。

   舉例來說，將 Singers 資料表中 singerid=1 的名稱更新為 Catalina Smith：

   UPDATE Singers s
   SET s.name='Catalina Smith'
   WHERE s.id=1;
   

gcloud

如要更新刊登位置表格中的資料，請使用 gcloud spanner rows update。

舉例來說，將 Singers 資料表中 singerid=1 的名稱更新為 Catalina Smith：

gcloud spanner rows update --table=Singers --database=example-db \
  --instance=test-instance --data=SingerId=1,SingerName='Catalina Smith'

移動刊登位置表格中的資料列

控制台

1. 如果還沒有執行個體分割區和放置位置，請建立新的。
2. 在導覽選單中，按一下「Spanner Studio」。
3. 在「Spanner Studio」頁面中，按一下「新增分頁」，或使用空白的編輯器分頁。

4. 使用 DML 或變異將資料移至新的執行個體分區。

   舉例來說，將 Singers 資料表中的 singerid=1 移至 asiaplacement：

   UPDATE Singers s
   SET s.location='asiaplacement'
   WHERE s.id=1;
   

gcloud

建立執行個體分割區和放置位置 (要將資料移至該處) 後，請使用 gcloud spanner rows update。

舉例來說，將 Singers 資料表中的 singerid=1 移至 asiaplacement：

gcloud spanner rows update --table=Singers --database=example-db \
  --instance=test-instance --data=SingerId=1,Location='asiaplacement'

刪除刊登位置表格中的資料列

控制台

1. 在導覽選單中，按一下「Spanner Studio」。
2. 在「Spanner Studio」頁面中，按一下「新增分頁」，或使用空白的編輯器分頁。

3. 使用 DML 或變異刪除資料。

   舉例來說，刪除 Singers 表格中的 singerid=1：

   DELETE FROM Singers s
   WHERE s.id=1;
   

gcloud

如要刪除資料，請使用 gcloud spanner rows delete。

舉例來說，刪除 Singers 表格中的 singerid=1：

gcloud spanner rows delete --table=Singers --database=example-db \
  --instance=test-instance --keys=1

查詢刊登位置資料表中的資料

控制台

1. 在導覽選單中，按一下「Spanner Studio」。
2. 在「Spanner Studio」頁面中，按一下「新增分頁」，或使用空白的編輯器分頁。

3. 執行查詢。

   舉例來說，查詢 Singers 資料表：

   SELECT * FROM Singers s WHERE s.SingerId=1;
   

gcloud

如要查詢資料，請使用 gcloud spanner databases execute-sql。

舉例來說，查詢 Singers 資料表：

gcloud spanner databases execute-sql example-db \
  --instance=test-instance \
  --sql='SELECT * FROM Singers s WHERE s.SingerId=1'

後續步驟

• 進一步瞭解地理位置分割。

• 瞭解如何建立及管理執行個體分割區。