Linguagem de definição de dados

Use a linguagem de definição de dados (DDL, na sigla em inglês) do Cloud Spanner para:

  • criar um banco de dados;
  • criar, alterar ou remover tabelas em um banco de dados;
  • adicionar, alterar ou soltar colunas em uma tabela;
  • criar ou soltar índices em um banco de dados.

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

Notação:

  • Colchetes "[ ]" indicam cláusulas opcionais.
  • Parênteses "( )" indicam parênteses literais.
  • A barra vertical "|" indica um OU lógico.
  • Chaves "{ }" delimitam um conjunto de opções.
  • Uma vírgula seguida por reticências indica que o item anterior pode se repetir em uma lista separada por vírgulas. item [, ...] indica um ou mais itens, e [item, ...] indica zero ou mais itens.
  • Uma vírgula "," indica a vírgula literal.
  • Colchetes angulares "<>" indicam colchetes angulares literais.
  • Um mdash "—" indica uma gama de valores entre os itens de cada lado.
  • O sinal de adição "+" indica que o item anterior pode se repetir.

Palavras-chave reservadas

Algumas palavras, como nomes de tipo, são reservadas na DDL do Cloud Spanner. Se você precisar usar uma palavra-chave reservada como um identificador em seu esquema, coloque-a entre acentos graves (`). Para obter a lista completa de palavras-chave reservadas no Cloud Spanner, consulte Estrutura e sintaxe léxicas.

Por exemplo:

CREATE TABLE MyTable (
  RowId INT64 NOT NULL,
  `Int64` INT64
) PRIMARY KEY (RowId);

Instruções DATABASE

CREATE DATABASE

Ao criar um banco de dados do Cloud Spanner, você deve fornecer uma instrução CREATE DATABASE, que define o código do banco de dados:

CREATE DATABASE database_id

database_id:
    {a—z}[{a—z|0—9|_|-}+]{a—z|0—9}

Os códigos do banco de dados:

  • precisam começar com uma letra minúscula;
  • podem conter letras minúsculas, números, sublinhados e hifens, mas não letras maiúsculas;
  • não podem terminar com um sublinhado ou hífen;
  • precisam estar entre acentos graves (``) se for uma palavra reservada ou incluir um hífen;
  • podem ter entre 2 e 30 caracteres;
  • não podem ser alterados depois de criados.

Tipos de dados

Escalares

A sintaxe para usar um tipo escalar em 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}+

Um int64_value deve corresponder a um número inteiro de -9.223.372.036.854.775.808 (-2 63) a 9.223.372.036.854.775.807 (2 63 - 1). Ele pode ser especificado com notação decimal ou hexadecimal. O formato hexadecimal requer um prefixo 0x, com um x minúsculo.

STRING

STRING é uma sequência de caracteres Unicode de comprimento variável. Seu valor precisa ser uma string Unicode válida. O comprimento é necessário e representa o número máximo de caracteres Unicode (não bytes) que podem ser armazenados no campo.

Observações:

  • As gravações na coluna são validadas e serão rejeitadas se o novo valor não for uma string Unicode válida ou exceder o comprimento especificado.

  • length pode ser um número inteiro no intervalo [1, 2621440] (2,5 MB).

  • Para um campo cujo comprimento é imprevisível ou não precisa ser limitado, é possível definir length para o valor de conveniência MAX, que é equivalente a 2621440 para fins de validação.

    Apenas o comprimento real da string armazenada afeta os custos de armazenamento. O uso de MAX não consome nenhuma capacidade de armazenamento adicional.

  • O Cloud Spanner requer que as strings Unicode sejam codificadas em UTF-8 no recebimento no servidor.

  • A compilação é feita pelo valor numérico do caractere Unicode, tecnicamente por ponto de código, que é sutilmente diferente devido à combinação de caracteres. Para strings ASCII, esta é a ordem de classificação tradicional.

  • É possível reduzir o comprimento de uma coluna depois que a tabela foi criada, mas para isso o Cloud Spanner terá que validar que os dados atuais obedecem à restrição de comprimento.

BYTES

BYTES é uma string binária de comprimento variável. O comprimento é necessário e representa o número máximo de bytes que podem ser armazenados no campo.

Observações:

  • As gravações na coluna são validadas e serão rejeitadas se o novo valor exceder o comprimento especificado.

  • length pode ser um número inteiro no intervalo [1, 10485760] (10 MB) ou o valor de conveniência MAX, que é equivalente a 10485760 para fins de validação.

    Apenas os bytes armazenados reais afetam os custos de armazenamento. O uso de MAX não consome nenhuma capacidade de armazenamento adicional.

  • É possível reduzir o comprimento de uma coluna depois que a tabela foi criada, mas para isso o Cloud Spanner terá que validar que os dados atuais obedecem à restrição de comprimento.

DATE

  • Uma data independente do fuso horário.
  • O intervalo [0001-01-01, 9999-12-31] é o intervalo legal para datas. Uma gravação à uma coluna de data será rejeitada se o valor estiver fora desse intervalo.
  • Consulte mais informações e o formato canônico em Tipos de dados.

TIMESTAMP

  • Um carimbo de data/hora com precisão de nanossegundos.
  • Independente do fuso horário, na faixa [0001-01-01 00:00:00 a 10000-01-01 00:00:00).
  • Consulte mais informações e o formato canônico em Tipos de dados.

Matrizes

A sintaxe para usar o tipo ARRAY em DDL é:

ARRAY< scalar_type >

O Cloud Spanner aceita matrizes de escalares. O objetivo principal de matrizes é armazenar uma coleção de valores em um espaço de maneira eficiente. As matrizes não foram criadas para fornecer acesso a elementos individuais; para ler ou gravar um único elemento, você deve ler ou gravar toda a matriz.

Se seu aplicativo usar estruturas de dados como vetores ou campos repetidos, é possível manter o estado deles em uma matriz do Cloud Spanner.

Veja um exemplo de uma definição alternativa de Singers que usa várias colunas do tipo ARRAY:

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

Observações:

  • Matrizes com subtipo ARRAY (matrizes aninhadas) não são aceitas.
  • Matrizes, como valores escalares, jamais podem ultrapassar 10 MiB no total.
  • Matrizes não podem ser usadas como colunas de chave.

  • Em uma instrução CREATE TABLE, é possível criar colunas do tipo ARRAY com uma anotação NOT NULL.

    Depois de criar a tabela, não será possível adicionar uma coluna do tipo ARRAY com uma anotação NOT NULL nem será possível adicionar uma anotação NOT NULL a uma coluna existente do tipo .

Instruções TABLE

CREATE TABLE

Use a instrução CREATE TABLE para definir tabelas.

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 })

Observações:

  • Adicionar a anotação DESC em um nome de coluna de chave primária altera o layout físico de dados de ordem ascendente (padrão) para ordem decrescente.

  • INTERLEAVE IN PARENT define uma relação de tabela entre pai e filho, que resulta em um intercalamento físico de linhas pai e filho. As colunas de chave primária de um pai precisam ser correspondentes em termos de posição, em nome e tipo, a um prefixo das colunas de chave primária de qualquer filho. Adicionar linhas à tabela filho falhará se a linha pai correspondente não existir. A linha pai pode já existir no banco de dados ou pode ter sido adicionada anteriormente, na mesma transação que adiciona uma linha à tabela filha.

  • A instrução ON DELETE opcional define o comportamento de linhas em ChildTable quando uma mutação tenta excluir a linha pai. Veja a seguir as opções aceitas:

    • CASCADE: as linhas filho são excluídas.
    • NO ACTION: as linhas filho não são excluídas. Se a exclusão de um pai deixar linhas filho para trás, o que viola a integridade referencial pai-filho, a gravação falhará.

    É possível omitir a instrução ON DELETE, caso em que o padrão de ON DELETE NO ACTION é usado.

  • Uma anotação NOT NULL torna uma coluna obrigatória para todas as mutações que inserem uma nova linha.

    Não é possível adicionar uma coluna NOT NULL a uma tabela existente. Para a maioria dos tipos de coluna, é possível contornar essa limitação:

    • Para colunas do tipo ARRAY, o único momento em que é possível usar uma anotação NOT NULL é quando cria a tabela. Depois disso, não é possível adicionar uma anotação NOT NULL a uma coluna do tipo ARRAY.
    • Para todos os outros tipos de coluna, é possível adicionar uma coluna anulável. Preencha essa coluna gravando valores em todas as linhas e atualize seu esquema com uma anotação NOT NULL nessa coluna.

  • Os nomes de tabela e coluna:

    • podem ter entre 1 e 128 caracteres;
    • precisam começar com uma letra maiúscula ou minúscula;
    • podem conter letras maiúsculas e minúsculas, números e sublinhados, mas não hifens;
    • diferenciam maiúsculas e minúsculas. Por exemplo, não é possível criar tabelas chamadas mytable e MyTable no mesmo banco de dados ou nomes de colunas mycolumn e MyColumn na mesma tabela.

  • A opção allow_commit_timestamp permite inserir e atualizar operações para solicitar que o Cloud Spanner grave o carimbo de data/hora de confirmação da transação na coluna. Para detalhes, consulte Carimbos de data/hora de confirmação.

ALTER TABLE

Use a instrução ALTER TABLE para alterar as definições da tabela.

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 })

A opção (allow_commit_timestamp=true) permite inserir e atualizar operações para solicitar que o Cloud Spanner grave o carimbo de data/hora de confirmação da transação na coluna. Para detalhes, consulte Carimbos de data/hora de confirmação.

DROP TABLE

Use a instrução DROP TABLE para remover tabelas. DROP TABLE não é recuperável.

DROP TABLE table_name

Instruções INDEX

CREATE INDEX

Use a instrução CREATE INDEX para definir índices secundários.

Sintaxe

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

Observações:

  • UNIQUE indica que este índice secundário impõe uma restrição aos dados que estão sendo indexados. A restrição UNIQUE causa a rejeição de qualquer transação que resultaria em uma chave de índice duplicada. Consulte Índices exclusivos para saber mais informações.

  • NULL_FILTERED indica que este índice secundário não indexa valores NULL. Consulte Indexação de valores NULL para obter mais informações.

  • INTERLEAVE IN define uma tabela para intercalar o índice. Se T é a tabela na qual o índice é intercalado, então:

    • T precisa ser um pai da tabela sendo indexada; e
    • a chave primária de T precisa ser o prefixo de chave do índice.

    Quando é preciso criar um índice intercalado? Se a chave de índice que você pretende usar para operações de índice corresponde à chave de uma tabela, pense em intercalar o índice nessa tabela caso a linha na tabela tenha uma relação de localidade de dados com as linhas indexadas correspondentes.

    Por exemplo, se você quiser indexar todas as linhas de Songs para uma linha específica de Singers, suas chaves de índice conteriam SingerId e SongName e seu índice seria um bom candidato para intercalar Singers se você costuma buscar informações sobre um cantor enquanto busca as músicas do cantor no índice. A definição de SongsBySingerSongName em Como um índice secundário é um exemplo de como criar um índice intercalado.

    Como tabelas entrelaçadas, as entradas em índices entrelaçados são armazenadas com a linha correspondente da tabela pai. Consulte Divisões do banco de dados para ver mais detalhes.

  • DESC define ordem de verificação decrescente para a coluna de índice correspondente. Ao verificar uma tabela usando uma coluna de índice marcada com DESC, as linhas verificadas aparecem na ordem decrescente em relação a essa coluna de índice. Se não especificar uma ordem de classificação, o padrão é crescente (ASC).

  • STORING fornece um mecanismo para duplicar dados da tabela em um ou mais índices secundários nessa tabela. Ao custo de armazenamento extra, isso pode reduzir a latência de leitura ao pesquisar dados usando um índice secundário, já que elimina a necessidade de recuperar dados da tabela principal depois de ter encontrado as entradas esperadas no índice. Consulte a instrução STORING para um exemplo.

  • Os nomes de índice:

    • podem ter entre 1 e 128 caracteres;
    • precisam começar com uma letra maiúscula ou minúscula;
    • podem conter letras maiúsculas e minúsculas, números e sublinhados, mas não hifens;
    • diferenciam maiúsculas e minúsculas. Por exemplo, não é possível criar índices chamados myindex e MyIndex no mesmo banco de dados.

DROP INDEX

Use a instrução DROP INDEX para descartar um índice secundário.

DROP INDEX index_name