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 tipos, são reservadas no DDL do Cloud Spanner. Se precisar usar uma palavra-chave reservada como um identificador em seu esquema, coloque-a entre acentos graves (`). Para a lista completa de palavras-chave reservadas no Cloud Spanner, consulte Estrutura e sintaxe lexical.

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, forneça 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}+

int64_values:

  • podem estar no intervalo de -9.223.372.036.854.775.808 a 9.223.372.036.854.775.807;
  • podem ser um dígito hexadecimal, precedido de "0x" (diferencia maiúsculas e minúsculas).

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 na faixa [1, 2621440] (2,5 MB).

  • Em campos em que o comprimento é imprevisível ou não há restrições, é possível definir length para o valor de conveniência MAX, o que equivale 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 são projetadas para fornecer acesso de elementos individual. Para ler ou gravar um único elemento, é necessário ler ou gravar a matriz inteira.

Se seu aplicativo usa estruturas de dados, como vetores ou campos repetidos, você pode facilmente persistir seu estado em uma matriz do Cloud Spanner.

Veja um exemplo de uma definição alternativa de Singers que usa várias colunas de 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.

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, o que resulta em uma intercalação física 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 cláusula opcional ON DELETE 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 cláusula ON DELETE porque, neste caso, o padrão 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 atual. No entanto, como uma solução alternativa, adicione uma coluna anulável, preencha essa coluna com gravações a todas as linhas e, em seguida, 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;
    • não diferenciam maiúsculas e minúsculas. Por exemplo, não é possível criar tabelas chamadas mytable e MyTable no mesmo banco ou nomes de coluna mycolumn e MyColumn na mesma tabela.

  • A opção allow_commit_timestamp permite que operações de inserção e atualização solicitem 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 de 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 que operações de inserção e atualização solicitem 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 soltar 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 UNIQUE 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 NULLs para saber mais informações.

  • INTERLEAVE IN define uma tabela para fazer a intercalação do í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ê pretende indexar todas as linhas de Songs para uma determinada linha de Singers, suas chaves de índice incluiriam SingerId e SongName, e o índice seria um bom candidato para intercalação em Singers. Isso se você busca frequentemente informações sobre um cantor à medida que busca músicas desse cantor no índice. A definição de SongsBySingerSongName em Como criar um índice secundário é um exemplo de como criar esse í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 cláusula 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;
    • não 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 remover um índice secundário.

DROP INDEX index_name
Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Esta página
Comentários sobre a documentação
Documentação do Cloud Spanner
Comentários sobre o produto