Usa el lenguaje de definición de datos (DDL) de Cloud Spanner si quieres:
- Crear una base de datos.
- Crear, modificar o eliminar tablas en una base de datos.
- Agregar, modificar o eliminar columnas en una tabla.
- Crear o eliminar índices en una base de datos.
Sintaxis de DDL
statement: { create_database | create_table | create_index | alter_table | drop_table | drop_index } create_database: CREATE DATABASE database_id create_table: CREATE TABLE table_name ( [column_def, ...] ) primary_key [, cluster] column_def: column_name (scalar_type | array_type) [NOT NULL] primary_key: PRIMARY KEY ( [key_part, ...] ) key_part: column_name [{ ASC | DESC }] cluster: INTERLEAVE IN PARENT table_name [ ON DELETE { CASCADE | NO ACTION } ] scalar_type: { BOOL | INT64 | FLOAT64 | STRING( length ) | BYTES( length ) | DATE | TIMESTAMP } length: { int64_value | MAX } array_type: ARRAY< scalar_type > create_index: CREATE [UNIQUE] [NULL_FILTERED] INDEX index_name ON table_name ( key_part [ASC | DESC] [, ...] ) [ storing_clause ] [ , interleave_clause ] storing_clause: STORING ( column_name [, ...] ) interleave_clause: INTERLEAVE IN table_name alter_table: ALTER TABLE table_name table_alteration table_alteration: { ADD COLUMN column_def | ALTER COLUMN column_def | DROP COLUMN column_name | SET ON DELETE { CASCADE | NO ACTION } } drop_table: DROP TABLE table_name drop_index: DROP INDEX index_name int64_value: { decimal_value | hex_value } decimal_value: [-]0—9+ hex_value: [-]0x{0—9|a—f|A—F}+ database_id: {a—z}[{a—z|0—9|_|-}+]{a—z|0—9} table_name, column_name, index_name: {a—z|A—Z}[{a—z|A—Z|0—9|_}+]
Notación:
- Los corchetes "[ ]" indican cláusulas opcionales.
- Los paréntesis "( )" indican paréntesis literales.
- La barra vertical "|" indica un operador OR lógico.
- Las llaves "{ }" contienen un conjunto de opciones.
- Una coma seguida de puntos suspensivos entre corchetes "[, ...]" indica que el elemento anterior puede repetirse en una lista separada por comas.
- Una coma "," indica la coma literal.
- Las comillas angulares "<>" indican comillas angulares literales.
- Un guion largo "—" indica un intervalo de valores entre los elementos que hay a cada lado.
- El signo más "+" indica que el elemento anterior puede repetirse.
Palabras clave reservadas
Algunas palabras, como los nombres de tipo, se reservan en el DDL de Cloud Spanner. Si necesitas utilizar una palabra clave reservada como identificador en el esquema, escríbelo entre acentos graves (`
). Para obtener la lista completa de palabras clave reservadas en Cloud Spanner, consulta Estructura léxica y sintaxis .
Por ejemplo:
CREATE TABLE MyTable ( RowId INT64 NOT NULL, `Int64` INT64 ) PRIMARY KEY (RowId)
Instrucciones DATABASE
CREAR BASE DE DATOS
Al crear una base de datos de Cloud Spanner, se debe proporcionar una instrucción CREATE DATABASE
, que define el ID de la base de datos:
CREATE DATABASE database_id database_id: {a—z}[{a—z|0—9|_|-}+]{a—z|0—9}
ID de la base de datos:
- Debe empezar con una letra en minúscula.
- Puede contener letras en minúscula, números, guiones bajos y guiones, pero no letras en mayúscula.
- No puede terminar con un guion bajo o guion.
- Debe escribirse entre acentos graves (
`
) si es una palabra reservada o contiene un guion. - Puede tener entre 2 y 30 caracteres de largo.
- No se puede cambiar después de crearlo.
Tipos de datos
Escalares
La sintaxis para usar un tipo escalar en DDL es:
{ BOOL | INT64 | FLOAT64 | STRING( length ) | BYTES( length ) | DATE | TIMESTAMP } length: { int64_value | MAX } int64_value: { decimal_value | hex_value } decimal_value: [-]0—9+ hex_value: [-]0x{0—9|a—f|A—F}+
int64_value
s:
- Puede estar en el intervalo de -9.223.372.036.854.775.808 a 9.223.372.036.854.775.807.
- Puede ser un valor hexadecimal, antepuesto con "0x" (distinción entre mayúsculas y minúsculas).
STRING
STRING
es una cadena de caracteres Unicode de longitud variable. Su valor debe ser una cadena Unicode válida. Es necesario especificar la longitud, y representa el número máximo de caracteres Unicode (no bytes) que se pueden almacenar en el campo.
Notas:
-
Las escrituras en la columna se validan y se rechazarán si el nuevo valor no es una cadena Unicode válida o supera la longitud especificada.
-
length
puede ser un número entero en el intervalo [1, 2621440] (2,5 mebichars) -
Para un campo cuya longitud es impredecible o no necesita restringirse, puedes establecer la
length
en el valor de convenienciaMAX
, que es equivalente a 2621440 para fines de validación.Solo la longitud real de la cadena almacenada afecta los costes de almacenamiento. El uso de
MAX
no utiliza ninguna capacidad de almacenamiento adicional. -
Cloud Spanner requiere que las cadenas Unicode estén codificadas en formato UTF-8 al recibirlas en el servidor.
-
La recopilación se realiza mediante el valor numérico del carácter Unicode (técnicamente por punto de código, que es ligeramente diferente debido a la combinación de caracteres). Para cadenas ASCII, este es el orden de clasificación tradicional.
-
Se puede reducir la longitud de una columna después de haber creado la tabla, pero, para ello, Cloud Spanner debe validar que los datos están dentro de la restricción de longitud.
BYTES
BYTES
es una cadena binaria de longitud variable. Es necesario especificar la longitud, y representa el número máximo de bytes que se puede almacenar en el campo.
Notas:
-
Las escrituras en la columna se validan y rechazan si el nuevo valor supera la longitud especificada.
-
length
puede ser un número entero en el intervalo [1, 10485760] (10 MiB) o el valor de convenienciaMAX
, que equivale a 10485760 para fines de validación.Solo los bytes almacenados reales afectan a los costes de almacenamiento. El uso de
MAX
no utiliza ninguna capacidad de almacenamiento adicional. -
Se puede reducir la longitud de una columna después de haber creado la tabla, pero, para ello, Cloud Spanner debe validar que los datos están dentro de la restricción de longitud.
DATE
- Una fecha que no depende de la zona horaria.
- El rango [0001-01-01, 9999-12-31] es el intervalo legal para las fechas. Una escritura en una columna de fecha se rechaza si el valor está fuera de ese intervalo.
- Consulta más información y el formato canónico en Tipos de datos .
TIMESTAMP
- Una marca de tiempo con precisión de nanosegundos.
- No depende de la zona horaria, en el intervalo [0001-01-01 00:00:00 a 10000-01-01 00:00:00].
- Consulta más información y el formato canónico en Tipos de datos .
Arrays
La sintaxis para usar el tipo ARRAY
en DDL es:
ARRAY< scalar_type >
Cloud Spanner admite matrices de escalares. El objetivo principal de las matrices es almacenar un conjunto de valores de una manera eficiente en cuanto a espacio. Las matrices no están diseñadas para proporcionar acceso individual a elementos. Para leer o escribir un solo elemento, se debe leer o escribir toda la matriz.
Si la aplicación utiliza estructuras de datos como vectores o campos repetidos, su estado se puede mantener fácilmente en una matriz de Cloud Spanner.
Aquí se muestra un ejemplo de una definición alternativa de Singers
que usa varias columnas de tipo ARRAY
:
CREATE TABLE Singers ( SingerId INT64, FeaturedSingerIds ARRAY<INT64>, SongNames ARRAY<STRING(MAX)>, ) PRIMARY KEY (SingerId) ...;
Notas:
- Las matrices con subtipo
ARRAY
(matrices anidadas) no son compatibles. - Las matrices, al igual que los valores escalares, nunca pueden ocupar más de 10 MiB en total.
- Las matrices no se pueden usar como columnas de claves.
Instrucciones TABLE
CREATE TABLE
Usa la instrucción CREATE TABLE
para definir tablas.
CREATE TABLE table_name( [column_def, ...] ) primary_key [, cluster] column_def: column_name (scalar_type | array_type) [NOT NULL] primary_key: PRIMARY KEY ( [key_part, ...] ) key_part: column_name [{ ASC | DESC }] cluster: INTERLEAVE IN PARENT table_name [ ON DELETE { CASCADE | NO ACTION } ] table_name and column_name: {a—z|A—Z}[{a—z|A—Z|0—9|_}+]
Notas:
-
Agregar la anotación
DESC
en un nombre de columna de claves principales cambia el diseño físico de los datos de orden ascendente (predeterminado) a orden descendente. -
INTERLEAVE IN PARENT
define una relación de tabla secundaria a principal, lo cual genera un intercalado físico de fojas principales y secundarias. El posicionamiento de las columnas de claves principales de una matriz principal debe coincidir, tanto en nombre como en tipo, con un prefijo de las columnas de claves principales de cualquier tabla secundaria. -
La cláusula
ON DELETE
opcional define el comportamiento de las filas enChildTable
cuando una mutación intenta eliminar la fila principal. Las opciones compatibles son:-
CASCADE
: las filas secundarias se eliminan. -
NO ACTION
: las filas secundarias no se eliminan. Si la eliminación de un elemento principal dejaría filas secundarias sueltas, lo que violaría la integridad referencial principal a secundaria, la escritura fallará.
La cláusula
ON DELETE
se puede omitir, en cuyo caso se utiliza el valor predeterminado deON DELETE NO ACTION
. -
-
Una anotación
NOT NULL
hace que se requiera una columna para todas las mutaciones que insertan una nueva fila. No se puede agregar una columnaNOT NULL
a una tabla que ya exista. (Sin embargo, como solución alternativa, se puede agregar una columna que acepte valores nulos, llenar esa columna con escrituras en todas las filas y actualizar el esquema con una anotaciónNOT NULL
en esa columna). -
Nombres de tabla y columna:
- Pueden tener entre 1 y 128 caracteres de largo.
- Deben comenzar con una letra mayúscula o minúscula.
- Pueden contener letras mayúsculas y minúsculas, números y guiones bajos, pero no guiones.
- No se distinguen entre mayúsculas y minúsculas. Por ejemplo, no se puede crear tablas llamadas
mytable
yMyTable
en la misma base de datos o usar nombres de columnasmycolumn
yMyColumn
en la misma tabla.
ALTER TABLE
Usa la instrucción ALTER TABLE
para cambiar las definiciones de la tabla.
ALTER TABLE table_name table_alteration table_alteration: { ADD COLUMN column_def | ALTER COLUMN column_def | DROP COLUMN column_name | SET ON DELETE { CASCADE | NO ACTION } }
DROP TABLE
Utiliza la instrucción DROP TABLE
para eliminar tablas. DROP TABLE
no es recuperable.
DROP TABLE table_name
Instrucciones INDEX
CREATE INDEX
Usa la instrucción CREATE INDEX
para definir índices secundarios.
Sintaxis
CREATE [UNIQUE] [NULL_FILTERED] INDEX index_name ON table_name ( key_part [, ...] ) [ storing_clause ] [ , interleave_clause ] storing_clause: STORING ( column_name [, ...] ) interleave_clause: INTERLEAVE IN table_name index_name: {a—z|A—Z}[{a—z|A—Z|0—9|_}+]
Notas:
-
UNIQUE
indica que este índice secundario aplica una restricciónUNIQUE
a los datos que se indexan. La restricciónUNIQUE
provoca que cualquier transacción que genere una clave de índice duplicada se rechace. Para obtener más información consulta Índices únicos. -
NULL_FILTERED
indica que este índice secundario no indexa valoresNULL
. Para obtener más información consulta Indexación de NULL. -
INTERLEAVE IN
define una tabla para intercalar el índice. SiT
es la tabla en la que se intercala el índice, entonces:T
debe ser un elemento principal de la tabla que se indexa, y- La clave principal de
T
debe ser el prefijo clave del índice.
¿Cuándo se debería crear un índice intercalado? Si la clave de índice que se desea utilizar para las operaciones de índice coincide con la clave de una tabla, puede que sea conveniente intercalar el índice en esa tabla si la fila en la tabla tiene una relación de localización de datos con las filas indexadas correspondientes.
Por ejemplo, si se desea indexar todas las filas de
Songs
para una fila particular deSingers
, las claves de índice contendríanSingerId
ySongName
y el índice sería un buen candidato para el intercalado enSingers
si se busca información con frecuencia sobre un cantante mientras buscan canciones de ese cantante desde el índice. La definición deSongsBySingerSongName
en Crear un índice secundario es un ejemplo para crear un índice intercalado de ese tipo.Al igual que las tablas intercaladas, las entradas en índices intercalados se almacenan con la fila correspondiente de la tabla principal. Para obtener más detalles consulta Divisiones de base de datos.
-
DESC
define el análisis en orden descendente para la columna de índice correspondiente. Al analizar una tabla a través de una columna de índice marcada comoDESC
, las filas analizadas aparecen en orden descendente con respecto a esta columna de índice. Si no se especifica un orden de clasificación, el valor predeterminado es ascendente (ASC
). -
STORING
proporciona un mecanismo para duplicar datos de la tabla en uno o más índices secundarios en esa tabla. Al precio de almacenamiento adicional, esto puede reducir la latencia de lectura cuando se buscan datos con un índice secundario, ya que elimina la necesidad de recuperar datos de la tabla principal después de haber encontrado las entradas deseadas en el índice. Consulta la cláusula ALMACENAMIENTO como ejemplo. -
Nombres de índice:
- Pueden tener entre 1 y 128 caracteres de largo.
- Deben comenzar con una letra mayúscula o minúscula.
- Pueden contener letras mayúsculas y minúsculas, números y guiones bajos, pero no guiones.
- No se distinguen entre mayúsculas y minúsculas. Por ejemplo, no se puede crear índices llamados
myindex
yMyIndex
en la misma base de datos.
DROP INDEX
Usa la instrucción DROP INDEX
para eliminar un índice secundario.
DROP INDEX index_name