En esta página, se describe cómo puedes crear y administrar puntos de división en tu base de datos. Puedes crear puntos de división para dividir previamente tu base de datos y prepararte para un aumento previsto en el tráfico. Para obtener más información sobre la división previa, consulta la Descripción general de la división previa.
Antes de comenzar
-
Para obtener el permiso que necesitas para crear y administrar puntos de división, pídele a tu administrador que te otorgue el rol de IAM de administrador de bases de datos de Cloud Spanner (
roles/spanner.databaseAdmin
) en tu instancia. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.Este rol predefinido contiene el permiso
spanner.databases.addSplitPoints
, que se requiere para crear y administrar puntos de división.También puedes obtener este permiso con roles personalizados o con otros roles predefinidos.
En los ejemplos de gcloud CLI de esta página, se supone que hiciste lo siguiente:
- Configuraste la CLI de gcloud para usarla con Spanner. Si no tienes experiencia en el uso de gcloud CLI con Spanner, consulta Crea y consulta una base de datos con la CLI de gcloud.
Ya configuraste gcloud CLI con tu proyecto. Por ejemplo:
gcloud config set core/project PROJECT_ID
Asegúrate de que tu instancia de Spanner tenga suficientes nodos para admitir el aumento previsto del tráfico. Para obtener más información, consulta la Descripción general de la división previa.
Cómo crear puntos de división
Puedes crear puntos de división con Google Cloud CLI o las APIs de REST.
gcloud
Si deseas crear puntos de división con Google Cloud CLI, debes crear un archivo que contenga todas las divisiones y proporcionar la ruta de acceso en el comando de gcloud CLI. El archivo no debe superar el límite de la API de 100 puntos por solicitud a la API. Para obtener más información, consulta Cuotas y límites.
El archivo debe usar el siguiente formato para especificar los puntos de división:
ObjectType ObjectName (SplitValue1)
ObjectType ObjectName (SplitValue2)
ObjectType ObjectName (SplitValueN)
Reemplaza las siguientes variables cuando crees el archivo:
- ObjectType: Es el tipo de objeto en el que deseas agregar divisiones. Los valores válidos son
TABLE
yINDEX
. - ObjectName: Es el nombre de la tabla o el índice de la base de datos.
- SplitValue1..N: Son los valores de los puntos de división en los que deseas introducir las divisiones.
Usa las siguientes reglas cuando crees los valores de los puntos de división en el archivo:
- Los valores de cadena deben estar entre comillas simples. Por ejemplo,
'splitKeyPart'
- Los valores booleanos deben ser
true
ofalse
. - Los valores de los tipos de datos
INT64
yNUMERIC
de Spanner deben estar entre comillas simples. Por ejemplo:'123'
o'99.99'
. - Todos los demás valores numéricos deben escribirse sin comillas simples. Por ejemplo,
1.287
. - Los valores de marca de tiempo deben proporcionarse en formato
'2020-06-18T17:24:53Z'
entre comillas simples. - Los valores de división deben estar entre paréntesis.
- El orden de los valores de las claves de división debe ser el mismo que el de la clave primaria.
- Si el valor de división debe tener una coma, debes escapar la coma con un carácter "\".
- Para dividir índices, puedes proporcionar la clave del índice o el índice completo y la clave de la tabla completa.
- Siempre debes usar la clave completa cuando especifiques el punto de división.
A continuación, se muestra un archivo de ejemplo que indica cómo se especifican los puntos de división:
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')
Antes de usar cualquiera de los datos de comando a continuación, realiza los siguientes reemplazos:
- SPLITS_FILE: Es la ruta de acceso al archivo de divisiones.
- INSTANCE_ID: El ID de la instancia.
- DATABASE_ID: Es el ID de la base de datos.
-
EXPIRATION_DATE:
(opcional) Es la fecha de vencimiento de los puntos de división. Acepta una marca de tiempo en el formato
'2020-06-18T17:24:53Z'
. - INITIATOR: (Opcional) Es el iniciador de los puntos de división.
Ejecuta el siguiente comando:
Linux, macOS o 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
Puedes usar el método projects.instances.databases.addSplitPoints
para crear puntos de división.
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
- PROJECT_ID: El ID del proyecto.
- INSTANCE_ID: El ID de la instancia.
- DATABASE_ID: Es el ID de la base de datos.
Método HTTP y URL:
POST https://spanner.googleapis.com/v1/projects//instances/ /databases/ :addSplitPoints
Cuerpo JSON de la solicitud:
{ "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 ] } } ] } ] }
Para enviar tu solicitud, expande una de estas opciones:
Deberías recibir un código de estado exitoso (2xx) y una respuesta vacía.
Bibliotecas cliente
Go
Java
Node.js
Python
Posibles situaciones de error
Las siguientes situaciones pueden generar un error cuando se crean puntos de división:
- La división a nivel del índice tiene un nombre de tabla incorrecto en la entrada.
- El punto de división a nivel de la tabla tiene más de una clave.
- El punto de división a nivel del índice tiene más de dos claves.
- Los puntos de división se definen en tablas o índices que no se definen en el esquema de la base de datos.
- La solicitud contiene puntos de división duplicados.
Para obtener información sobre las cuotas y los límites, consulta Cuotas y límites.
Cómo ver los puntos de división
Puedes ver todos los puntos de división creados en tu base de datos con la consola deGoogle Cloud o gcloud CLI:
Console
Para obtener el recuento de puntos de división consultando la vista SPANNER_SYS.USER_SPLIT_POINTS
en la consola de Google Cloud , haz lo siguiente:
Abre la página Instancias de Spanner.
Selecciona los nombres de la instancia y la base de datos de Spanner que deseas consultar.
Haz clic en Spanner Studio en el panel de navegación izquierdo.
Escribe la siguiente consulta en el campo de texto:
SELECT * FROM SPANNER_SYS.USER_SPLIT_POINTS
Haz clic en Ejecutar consulta.
Aparecerá un resultado similar al siguiente:
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 | Índice: T_IDX en T, clave de índice: (10), clave de tabla principal: (<begin>,<begin>,<begin>,<begin>,<begin>,<begin>,<begin>) | 2025-03-08T07:33:23.861682Z |
T | T_IDX | CloudAddSplitPointsAPI | Índice: T_IDX en T, clave de índice: (9091), clave de tabla principal: (4567,123,4.2,2024-04-30T17:00:00-07:00,1,2024-05-01,a) | 2025-03-08T07:35:25.990007Z |
gcloud
Ejecuta el siguiente comando de gcloud CLI para ver los puntos de división en tu base de datos:
gcloud spanner databases splits list DATABASE_ID \
--instance INSTANCE_ID
Reemplaza las siguientes variables cuando ejecutes este comando:
- INSTANCE_ID: Es el ID de la instancia de Spanner.
- DATABASE_ID: Es el ID de la base de datos de Spanner.
Aparecerá una respuesta similar a la siguiente:
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
Cómo hacer que un punto de división deje de estar disponible
Puedes establecer una hora de vencimiento para cada punto de división que crees. Para obtener más información, consulta Vencimiento del punto de división. Puedes hacer que venzan los puntos de división con Google Cloud CLI o las APIs de REST.
gcloud
Si deseas hacer que venzan los puntos de división con Google Cloud CLI, debes crear un archivo que contenga todas las divisiones que deseas que venzan y proporcionar su ruta de acceso con el parámetro splits-file
en el comando de gcloud CLI. El archivo no debe superar el límite de la API de 100 puntos por solicitud a la API. Para obtener más información, consulta Cuotas y límites.
El archivo debe usar el siguiente formato para especificar los puntos de división:
ObjectType ObjectName (SplitValue)
ObjectType ObjectName (SplitValue)
ObjectType ObjectName (SplitValue)
Reemplaza las siguientes variables cuando crees el archivo:
- ObjectType: Es el tipo de objeto de la división que deseas que venza. Los valores válidos son
TABLE
yINDEX
. - ObjectName: Es el nombre de la tabla o el índice de la base de datos.
- SplitValue: Es el valor del punto de división que deseas que venza.
Usa las siguientes reglas cuando crees los valores de los puntos de división en el archivo:
- Los valores de cadena deben estar entre comillas simples. Por ejemplo,
'splitKeyPart'
- Los valores booleanos pueden ser
true
ofalse
. - Los valores de los tipos de datos
INT64
yNUMERIC
de Spanner deben estar entre comillas simples. Por ejemplo:'123'
o'99.99'
. - Todos los demás valores numéricos deben escribirse sin comillas simples. Por ejemplo,
1.287
. - Los valores de marca de tiempo deben proporcionarse en formato
'2020-06-18T17:24:53Z'
entre comillas simples. - Los valores de división deben estar entre paréntesis.
- El orden de los valores de las claves de división debe ser el mismo que el de la clave primaria.
- Si el valor de división debe tener una coma, debes escapar la coma con un carácter "\".
- Para dividir índices, puedes proporcionar la clave del índice o el índice completo y la clave de la tabla completa.
- Siempre debes usar la clave completa cuando especifiques el punto de división.
A continuación, se muestra un archivo de ejemplo que indica cómo se especifican los puntos de división:
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')
Antes de usar cualquiera de los datos de comando a continuación, realiza los siguientes reemplazos:
- SPLITS_FILE: Es la ruta de acceso al archivo de divisiones.
- INSTANCE_ID: El ID de la instancia.
- DATABASE_ID: Es el ID de la base de datos.
-
EXPIRATION_DATE:
(opcional) Es la fecha de vencimiento de los puntos de división. Acepta una marca de tiempo en el formato
'2020-06-18T17:24:53Z'
. - INITIATOR: (Opcional) Es el iniciador de los puntos de división.
Ejecuta el siguiente comando:
Linux, macOS o 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
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
- PROJECT_ID: El ID del proyecto.
- INSTANCE_ID: El ID de la instancia.
- DATABASE_ID: Es el ID de la base de datos.
Método HTTP y URL:
POST https://spanner.googleapis.com/v1/projects//instances/ /databases/ :addSplitPoints
Cuerpo JSON de la solicitud:
{ "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 ] } } ] } ] }
Para enviar tu solicitud, expande una de estas opciones:
Deberías recibir un código de estado exitoso (2xx) y una respuesta vacía.