Lenguaje de definición de datos

Usa el lenguaje de definición de datos (DDL) de Cloud Spanner para realizar estas acciones:

  • Crear una base de datos
  • Crear, modificar o descartar tablas en una base de datos
  • Agregar, modificar o descartar columnas en una tabla
  • Crear o descartar í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] [options_def]

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 >

options_def:
  OPTIONS (allow_commit_timestamp = { true | null })

create_index:
    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

alter_table:
    ALTER TABLE table_name { table_alteration | table_column_alteration }

table_alteration:
{ ADD COLUMN column_def | DROP COLUMN column_name |
      SET ON DELETE { CASCADE | NO ACTION } }

table_column_alteration:
    ALTER COLUMN column_name { { scalar_type | array_type } [NOT NULL] | SET options_def }

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 OR lógico.
  • Las llaves “{ }” encierran un conjunto de opciones.
  • Una coma seguida de una elipsis indica que el elemento anterior puede repetirse en una lista separada por comas. item [, ...] indica uno o más elementos, y [item, ...] indica cero o más elementos.
  • Una coma “,” indica la coma literal.
  • Los corchetes angulares “<>” indican corchetes angulares literales.
  • Un guion largo “—” indica un rango de valores entre los elementos a cada lado.
  • El signo más “+” indica que el elemento anterior puede repetirse.

Palabras clave reservadas

Algunas palabras, como los nombres de tipos, están reservadas en el DDL de Cloud Spanner. Si necesitas usar una palabra clave reservada como un identificador en tu esquema, enciérrela 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);

Declaraciones DATABASE

CREATE DATABASE

Cuando creas una base de datos de Cloud Spanner, debes proporcionar una declaració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 comenzar con una letra en minúscula.
  • Puede contener letras minúsculas, números, guiones bajos y guiones, pero no letras mayúsculas.
  • No puede terminar con guion bajo o guion.
  • Debe estar encerrado entre acentos graves (`) si es una palabra reservada o contiene un guion.
  • Puede tener entre 2 y 30 caracteres.
  • No se puede cambiar después de crearlo.

Tipos de datos

Escalares

Esta es la sintaxis para usar un tipo escalar en DDL:

{ 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}+

Un valor int64_value debe corresponder a un número entero de -9,223,372,036,854,775,808 (-263) a 9,223,372,036,854,775,807 (263 − 1). Se puede especificar con notación decimal o hexadecimal. El formato hexadecimal requiere un prefijo 0x, con una x en minúscula.

STRING

STRING es una string de caracteres Unicode de longitud variable. Su valor debe ser una string Unicode válida. La longitud es obligatoria y representa la cantidad máxima de caracteres Unicode (no bytes) que se pueden almacenar en el campo.

Notas:

  • Las operaciones de escrituras en la columna se validan y se rechazarán si el valor nuevo no es una string Unicode válida o superar la longitud especificada.

  • length puede ser un número entero en el rango [1, 2621440] (2.5 MB).

  • Puedes configurar length en el valor de conveniencia MAX, que es equivalente a 2621440 con fines de validación para un campo cuya longitud es impredecible o no necesita limitarse.

    Solo la longitud real de la string almacenada afecta los costos de almacenamiento. El uso de MAX no utiliza ninguna capacidad de almacenamiento adicional.

  • Cloud Spanner requiere que las strings Unicode estén codificadas en UTF-8 cuando se reciben en el servidor.

  • La intercalación se realiza mediante un valor numérico de caracteres Unicode (técnicamente por punto de código, que es sutilmente diferente debido a una combinación de caracteres). Para las string ASCII, este es el orden de clasificación tradicional.

  • Puedes reducir la longitud de una columna después de crearla, pero para ello, Cloud Spanner debe validar que los datos existentes estén dentro de la restricción de longitud.

BYTES

BYTES es una string binaria de longitud variable. La longitud es obligatoria y representa la cantidad máxima de bytes que se pueden almacenar en el campo.

Notas:

  • Las operaciones de escrituras en la columna se validan y se rechazan si el valor nuevo supera la longitud especificada.

  • length puede ser un número entero en el rango [1, 10485760] (10 MB) o el valor de conveniencia MAX, que es equivalente a 10485760 con fines de validación.

    Solo los bytes reales almacenados afectan los costos de almacenamiento. El uso de MAX no utiliza ninguna capacidad de almacenamiento adicional.

  • Puedes reducir la longitud de una columna después de crearla, pero para ello, Cloud Spanner debe validar que los datos existentes estén dentro de la restricción de longitud.

DATE

  • Es una fecha independiente de la zona horaria.
  • El rango [0001-01-01, 9999-12-31] es el intervalo legal para las fechas. Se rechaza la operación de escritura en una columna de fecha si el valor no se encuentra entre ese intervalo.
  • Consulta más información y el formato canónico en Tipos de datos.

TIMESTAMP

  • Es una marca de tiempo con precisión de nanosegundos.
  • La zona horaria es independiente, en el rango [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.

Arreglos

Esta es la sintaxis para usar el tipo ARRAY en DDL:

ARRAY< scalar_type >

Cloud Spanner admite arreglos de escalares. El propósito principal de los arreglos es almacenar una colección de valores de manera eficiente en el espacio. Los arreglos no están diseñados para proporcionar acceso a elementos individuales. Para leer o escribir un solo elemento, debes leer o escribir todo el arreglo.

Si tu aplicación usa estructuras de datos, como vectores o campos repetidos, puedes conservar su estado en un arreglo de Cloud Spanner.

A continuación, se muestra un ejemplo de una definición alternativa de Singers que utiliza varias columnas del tipo ARRAY:

CREATE TABLE Singers (
  SingerId INT64,
  FeaturedSingerIds ARRAY<INT64>,
  SongNames ARRAY<STRING(MAX)>,
) PRIMARY KEY (SingerId) ...;

Notas:

  • No se admiten arreglos con el subtipo ARRAY (arreglos anidados).
  • Los arreglos, al igual que los valores de escalares, nunca pueden tener más de 10 MiB en total.
  • No se pueden usar arreglos como columnas de clave.

  • En una declaración CREATE TABLE, puedes crear columnas de tipo ARRAY con una anotación NOT NULL.

    Después de crear la tabla, no puedes agregar una columna de tipo ARRAY con una anotación NOT NULL ni agregar una anotación NOT NULL a una columna existente de tipo .

Declaraciones TABLE

CREATE TABLE

Usa la declaració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] [options_def]

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|_}+]

options_def:
  OPTIONS (allow_commit_timestamp = { true | null })

Notas:

  • Agregar la anotación DESC en un nombre de columna de clave primaria 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 de elemento superior a secundario, lo que da como resultado una intercalación física de las filas superior y secundaria. Las columnas de clave primaria de un elemento superior deben coincidir posicionalmente, tanto en nombre como en tipo, con un prefijo de las columnas de clave primaria de cualquier elemento secundario. La adición de filas a la tabla secundaria falla si la fila superior correspondiente no existe. La fila superior ya puede existir en la base de datos o puede agregarse antes en la misma transacción que agrega una fila a la tabla secundaria.

  • La cláusula ON DELETE opcional define el comportamiento de las filas en ChildTable cuando una mutación intenta borrar la fila superior. Estas son las opciones compatibles:

    • CASCADE: las filas secundarias se borran.
    • NO ACTION: las filas secundarias no se borran. La operación de escritura fallará si la eliminación de un elemento superior no tuviera en cuenta a las filas secundarias, lo que infringiría la integridad referencial superior-secundario.

    Puedes omitir la cláusula ON DELETE, en cuyo caso se usa el valor predeterminado ON DELETE NO ACTION.

  • Una anotación NOT NULL hace que una columna sea obligatoria para todas las mutaciones que insertan una fila nueva.

    No puedes agregar una columna NOT NULL a una tabla existente. Para la mayoría de los tipos de columnas, puedes evitar esta limitación:

    • En las columnas de tipo ARRAY, cuando creas la tabla es el único momento en que puedes usar una anotación NOT NULL. Después de eso, no podrás agregar una anotación NOT NULL a una columna de tipo ARRAY.
    • En todos los demás tipos de columnas, puedes agregar una columna con valores nulos, escribir valores en todas las filas para llenar esa columna y actualizar tu esquema con una anotación NOT NULL en esa columna.

  • Nombres de tablas y columnas:

    • Puede tener entre 1 y 128 caracteres.
    • Debe comenzar con una letra mayúscula o minúscula.
    • Puede contener letras mayúsculas y minúsculas, números y guiones bajos, pero no guiones.
    • No distinguen mayúsculas de minúsculas. Por ejemplo, no puedes crear tablas denominadas mytable y MyTable en los mismos nombres de base de datos o columnas mycolumn y MyColumn en la misma tabla.

  • La opción allow_commit_timestamp permite insertar y actualizar operaciones para solicitar que Cloud Spanner escriba la marca de tiempo de confirmación de la transacción en la columna. Para obtener más información, consulta cómo confirmar las marcas de tiempo.

ALTER TABLE

Usa la declaración ALTER TABLE para cambiar las definiciones de la tabla.

ALTER TABLE table_name { table_alteration | table_column_alteration }

table_alteration:
{ ADD COLUMN column_def | DROP COLUMN column_name |
      SET ON DELETE { CASCADE | NO ACTION } }

table_column_alteration:
  ALTER COLUMN column_name { { scalar_type | array_type } [NOT NULL] | SET options_def }

options_def:
  OPTIONS (allow_commit_timestamp = { true | null })

La opción (allow_commit_timestamp=true) permite insertar y actualizar operaciones para solicitar que Cloud Spanner escriba la marca de tiempo de confirmación de la transacción en la columna. Para obtener más información, consulta cómo confirmar las marcas de tiempo.

DROP TABLE

Usa la declaración DROP TABLE para descartar las tablas. DROP TABLE no se puede recuperar.

DROP TABLE table_name

Declaraciones INDEX

CREATE INDEX

Usa la declaració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ón a los datos que se indexan. La restricción UNIQUE provoca que se rechace cualquier transacción que genere una clave de índice duplicada. Consulta Índices únicos para obtener más información.

  • NULL_FILTERED indica que este índice secundario no indexa valores NULL. Consulta cómo indexar valores NULL para obtener más información.

  • INTERLEAVE IN define una tabla para intercalar el índice. Si T es la tabla en la que se intercala el índice, entonces:

    • T debe ser un elemento superior de la tabla que se está indexando.
    • La clave primaria de T debe ser el prefijo de la clave del índice.

    ¿Cuándo deberías crear un índice intercalado? Si la clave de índice que deseas usar para operaciones de índice coincide con la clave de una tabla, puedes intercalar el índice en esa tabla si la fila debe tener una relación de localidad de datos con las filas indexadas correspondientes.

    Por ejemplo, si deseas indexar todas las filas de Songs para una fila específica de Singers, tus claves de índice contendrían SingerId y SongName y el índice sería un buen candidato para intercalar Singers si recuperas con frecuencia información sobre un cantante cuando recuperas las canciones de ese cantante desde el índice. La definición de SongsBySingerSongName en Crea un índice secundario es un ejemplo de creación de ese índice intercalado.

    Al igual que las tablas intercaladas, las entradas de un índice intercalado se almacenan con la fila correspondiente de la tabla superior. Consulta las divisiones de bases de datos para obtener más detalles.

  • DESC define el orden de análisis descendente para la columna de índice correspondiente. Cuando se analiza una tabla con una columna de índice marcada DESC, las filas analizadas aparecen en orden descendente con respecto a esta columna de índice. Si no especificas un orden de clasificación, el valor predeterminado es ascendente (ASC).

  • STORING proporciona un mecanismo para duplicar los datos de la tabla en uno o más índices secundarios de esa tabla. A costa del 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 STORING para ver un ejemplo.

  • Nombres de índices:

    • Puede tener entre 1 y 128 caracteres.
    • Debe comenzar con una letra mayúscula o minúscula.
    • Puede contener letras mayúsculas y minúsculas, números y guiones bajos, pero no guiones.
    • No distinguen mayúsculas de minúsculas. Por ejemplo, no puedes crear índices llamados myindex y MyIndex en la misma base de datos

DROP INDEX

Usa la declaración DROP INDEX para descartar un índice secundario.

DROP INDEX index_name
¿Te sirvió esta página? Envíanos tu opinión:

Enviar comentarios sobre…

Esta página
Comentarios sobre la documentación
Cloud Spanner
Comentarios sobre el producto
¿Necesitas ayuda? Visita nuestra página de asistencia.