Referência do Oracle NoSQL Database Cloud Service

Tipos de Dados Suportados

O Oracle NoSQL Database Cloud Service suporta muitos tipos de dados comuns.

Tipo de Dados	Descrição
`BINARY`	Uma sequência de zero ou mais bytes. O tamanho do armazenamento é o número de bytes mais uma codificação do tamanho do array de bytes, que é uma variável, dependendo do tamanho do array.
`FIXED_BINARY`	Um array de bytes de tamanho fixo. Não há sobrecarga de codificação extra para este tipo de dados.
`BOOLEAN`	Um tipo de dados com um dos dois valores possíveis: `TRUE` ou `FALSE`. O tamanho de armazenamento do booliano é 1 byte.
`DOUBLE`	Um número de ponto flutuante longo, codificado usando 8 bytes de armazenamento para chaves de índice. Se for uma chave primária, ela usará 10 bytes de armazenamento.
`FLOAT`	Um número de ponto flutuante longo, codificado usando 4 bytes de armazenamento para chaves de índice. Se for uma chave primária, ela usará 5 bytes de armazenamento.
`LONG`	Um número inteiro longo tem uma codificação de tamanho variável que usa de 1 a 8 bytes de armazenamento, dependendo do valor. Se for uma chave primária, ela usará 10 bytes de armazenamento.
`INTEGER`	Um número inteiro longo tem uma codificação de tamanho variável que usa de 1 a 4 bytes de armazenamento, dependendo do valor. Se for uma chave primária, ela usará 5 bytes de armazenamento.
`STRING`	Uma sequência de zero ou mais caracteres Unicode. O tipo String é codificado como UTF-8 e armazenado nessa codificação. O tamanho do armazenamento é o número de bytes UTF-8 mais o tamanho, que pode ser de 1 a 4 bytes, dependendo do número de bytes na codificação. Quando armazenado em uma chave de índice, o tamanho do armazenamento é o número de bytes UTF-8 mais um único byte de encerramento nulo.
`NUMBER`	Um número decimal assinado com precisão arbitrária. É serializado em um formato de matriz de bytes que pode ser usado para comparações ordenadas. O formato tem 2 partes: O sinal e o expoente mais um único dígito. Isso leva de 1 a 6 bytes, mas normalmente é 2, a menos que o expoente seja muito grande A mantissa do valor que é aproximadamente um byte para cada 2 dígitos Exemplos: 12.345678 serializa em 6 bytes 1.234E+102 serializa em 5 bytes Observação: Quando você precisar usar valores numéricos em seu esquema, é recomendável decidir sobre os tipos de dados na ordem fornecida a seguir: INTEGER, LONG, FLOAT, DOUBLE, NUMBER Evite NUMBER, a menos que você realmente precise dele para seu caso de uso, pois NUMBER é caro tanto em termos de armazenamento quanto em poder de processamento usado.
`TIMESTAMP`	Um ponto no tempo com uma precisão. A precisão afeta o tamanho e o uso do armazenamento. O carimbo de data/hora é armazenado e gerenciado no horário UTC (Coordinated Universal Time). O tipo de dados Timestamp requer de 3 a 9 bytes, dependendo da precisão usada. O detalhamento a seguir ilustra o armazenamento usado por este tipo de dados: bit[0~13] ano - 14 bits bit[14~17] mês - 4 bits bit[18~22] dia - 5 bits bit[23 ~ 27] hora - 5 bits [opcional] bit[28 ~ 33] minuto - 6 bits [opcional] bit[34~39] segundo - 6 bits [opcional] bit[40~71] segundo fracionário [opcional com comprimento variável]
`UUID`	Observação: O tipo de dados UUID é considerado um subtipo do tipo de dados STRING. O tamanho do armazenamento é de 16 bytes como uma chave de índice. Se usado como chave primária, o tamanho do armazenamento será de 19 bytes.
`ENUM`	Uma enumeração é representada como um array de strings. Os valores `ENUM` são identificadores simbólicos (tokens) e são armazenados como um pequeno valor inteiro que representa uma posição ordenada na enumeração.
`ARRAY`	Uma coleção ordenada de zero de itens mais tipados. Os arrays não definidos como JSON não podem conter valores `NULL`. Os arrays declarados como JSON podem conter qualquer JSON válida, incluindo o valor especial, nulo, que é relevante para JSON.
`MAP`	Uma coleção não ordenada de zero ou mais pares de chave/item, na qual todas as chaves são strings e todos os itens são do mesmo tipo. Todas as chaves devem ser exclusivas. Os pares chave/item são chamados de fields, as chaves são field names e os itens associados são field values. Os valores de campos podem ter diferentes tipos, mas os mapas não podem conter valores de campos NULL.
`RECORD`	Uma coleção fixa de um ou mais pares de item/chave, em que todas as chaves são strings. Todas as chaves de um registro devem ser exclusivas.
`JSON`	Qualquer dado JSON válido.

Estados da tabela e ciclos de vida

Saiba mais sobre os diferentes estados de tabela e seu significado ( processo de ciclo de vida de tabela).

Cada tabela passa por uma série de diferentes estados, desde a criação da tabela até a exclusão (eliminação). Por exemplo, uma tabela no estado DROPPING não pode prosseguir para o estado ACTIVE, e uma tabela no estado ACTIVE pode mudar para o estado UPDATING. Você pode rastrear os diferentes estados da tabela monitorando o ciclo de vida da tabela. Esta seção descreve os diversos estados da tabela.

A seguir, descrição da tabela-state.png
Descrição da tabela de ilustração-state.png

Estado da Tabela	Descrição
`CREATING`	A tabela está em processo de criação. Não está pronta para ser usada.
`UPDATING`	A atualização da tabela está em andamento. Não é possível alterar mais a tabela nesse estado. Uma tabela está no estado `UPDATING` quando: Os limites da tabela estão sendo alterados O esquema da tabela está evoluindo Adicionando ou eliminando um índice de tabela
`ACTIVE`	A tabela pode ser usada no estado atual. A tabela pode ter sido criada ou modificada recentemente, mas o estado da tabela agora é estável.
`DROPPING`	A tabela está sendo eliminada e não pode ser acessada para nenhuma finalidade.
`DROPPED`	A tabela foi eliminada e não existe mais para atividades de leitura, gravação ou consulta. Observação: Uma vez eliminada, uma tabela com o mesmo nome poderá ser criada novamente.

Depurando erros de instrução SQL na console do OCI

Ao usar a console do OCI para criar uma tabela usando uma instrução DDL ou DML para inserir ou atualizar dados ou usar uma consulta SELECT para extrair dados, você poderá obter um erro informando que a instrução está Incompleta ou com falha em um dos seguintes cenários comuns:

Se você tiver um ponto-e-vírgula no fim da instrução SQL.
Se houver um erro de sintaxe na instrução SQL, como o uso incorreto de vírgulas, o uso de qualquer caractere desnecessário na instrução etc.
Se houver um erro de ortografia na instrução SQL em qualquer uma das palavras-chave SQL ou na definição do tipo de dados.
Se você tiver definido a coluna como NOT NULL, mas não tiver atribuído um valor DEFAULT a ela.
Se você tiver definido a coluna como NOT NULL, mas não tiver atribuído um valor DEFAULT a ela.

Como tratar alguns erros Incompletos ou com falha ao usar a console do OCI para criar ou gerenciar dados:

Remova o ponto-e-vírgula (se estiver presente) no fim da instrução SQL.
Verifique se há algum caractere indesejado ou pontuação errada em sua instrução SQL.
Verifique se há erros de ortografia na instrução SQL.
Verifique se todas as definições de coluna estão completas e corretas.
Verifique se você definiu uma chave primária para sua tabela.

Se você ainda receber um erro após eliminar algumas das possíveis situações, conforme discutido acima, poderá usar o Cloud Shell para executar sua consulta e capturar o erro exato, conforme mostrado no exemplo abaixo.

Exemplo: Obtendo a mensagem de erro de uma instrução SELECT do cloud shell

O comando summarize verifica a sintaxe e retorna um breve resumo de uma instrução SQL.

Na console do OCI, Abra o Cloud Shell no menu superior direito.
Copie sua instrução SQL SELECT( por exemplo, query1.sql) em uma variável (SQL_SELECTSTMT).
Exemplo:
```
SQL_SELECTSTMT=$(cat ~/query1.sql | tr '\n' ' ')
```

Chame o comando oci abaixo para verificar a sintaxe da instrução SQL SELECT.

Observação:

Você precisa fornecer compartment_id para esta instrução SELECT.

oci raw-request --http-method GET --target-uri 
https://nosql.${OCI_REGION}.oci.oraclecloud.com/20190828/query/summarize?compartmentId=$NOSQL_COMPID\
&statement="$SQL_SELECTSTMT" | jq '.data'

Isso produzirá o erro exato na instrução SQL.

Referência de Definições de Dados

Saiba como usar a DDL no Oracle NoSQL Database Cloud Service.

Use códigos DDL no Oracle NoSQL Database Cloud Service para criar, alterar e eliminar tabelas e índices.

Para obter informações sobre a sintaxe da linguagem DDL, consulte o Table Data Definition Language Guide. Este guia documenta a linguagem DDL, conforme suportado pelo produto Oracle NoSQL Database local. O Oracle NoSQL Database Cloud Service suporta um subconjunto dessa funcionalidade e as diferenças são documentadas na seção Diferenças de DDL na Nuvem.

Além disso, cada driver NoSQL <language> fornece uma API para executar uma instrução DDL. Para gravar seu aplicativo, consulte Usando APIs para Criar Tabelas e Índices no Oracle NoSQL Database Cloud Service.

Instruções DDL típicas

Alguns exemplos de instruções DDL comuns são os seguintes:

Criar Tabela

CREATE TABLE [IF NOT EXISTS] (
    field-definition, field-definition-2 ...,
    PRIMARY KEY (field-name, field-name-2...),
) [USING TTL ttl]

Por exemplo:

CREATE TABLE IF NOT EXISTS audience_info (
    cookie_id LONG,
    ipaddr STRING,
    audience_segment JSON,
    PRIMARY KEY(cookie_id))

Alterar Tabela

ALTER TABLE table-name (ADD field-definition)
ALTER TABLE table-name (DROP field-name)
ALTER TABLE table-name USING TTL ttl

Por exemplo:

ALTER TABLE audience_info USING TTL 7 days

Criar Índice

CREATE INDEX [IF NOT EXISTS] index-name ON table-name (path_list)

Por exemplo:

CREATE INDEX segmentIdx ON audience_info
       (audience_segment.sports_lover AS STRING)

Eliminar Tabela

DROP TABLE [IF EXISTS] table-name

Por exemplo:

DROP TABLE audience_info

Consulte os guias de referência para obter uma lista completa:

Diferenças de DDL na Nuvem

A linguagem DDL do serviço de nuvem difere do que é descrito no guia de referência da seguinte maneira:

Nomes de Tabela

Limitados a 256 caracteres e estão limitados a caracteres alfanuméricos e sublinhados
Deve começar com uma letra
Não podem incluir caracteres especiais
Não há suporte para tabelas filhas

Conceitos não suportados

Instruções DESCRIBE e SHOW TABLE.
Índices de texto completo
Gerenciamento de usuários e atribuições
Regiões locais

Referência de Linguagem de Consulta

Saiba como usar instruções SQL para atualizar e consultar dados no Oracle NoSQL Database Cloud Service.

O Oracle NoSQL Database usa a linguagem de consulta SQL para atualizar e consultar dados em tabelas NoSQL. Consulte Referência SQL do Oracle NoSQL Database para obter a sintaxe da linguagem de consulta.

Consultas Típicas

SELECT <expression>
FROM <table name>
[WHERE <expression>]
[GROUP BY <expression>]
[ORDER BY <expression> [<sort order>]]
[LIMIT <number>]
[OFFSET <number>]; 

For example:
SELECT * FROM Users;
SELECT id, firstname, lastname FROM Users WHERE firstname = "Taylor";

UPDATE <table_name> [AS <table_alias>]
    <update_clause>[, <update_clause>]*
WHERE <expr>[<returning_clause>];

For example:
UPDATE JSONPersons $j
  SET TTL 1 DAYS
  WHERE id = 6
  RETURNING remaining_days($j) AS Expires;

diferenças de linguagem de consulta na nuvem

O suporte à consulta do serviço de nuvem difere do que é descrito no guia de referência de linguagem de consulta da seguinte maneira:

Restrições das expressões usadas na cláusula SELECT

O Oracle NoSQL Database Cloud Service oferece suporte a expressões de agrupamento ou expressões aritméticas entre funções agregadas. Não são permitidos outros tipos de expressões na cláusula SELECT. Por exemplo,

Cada driver de Banco de Dados NoSQL fornece uma API para executar uma instrução de consulta.

Referência do Plano de Consulta

Um plano de execução de consulta é a sequência de operações que o Oracle NoSQL Database executa para executar uma consulta.

Um plano de execução de consulta é uma árvore de iteradores de plano. Cada tipo de iterador avalia um tipo diferente de expressão que pode aparecer em uma consulta. Em geral, a escolha do índice e o tipo de predicados de índice associados podem ter um efeito drástico no desempenho da consulta. Como resultado, você, como usuário, geralmente quer ver qual índice é usado por uma consulta e quais predicados foram empurrados para ele. Com base nessas informações, talvez você queira forçar o uso de outro índice por meio de dicas de índice. Essas informações estão contidas no plano de execução da consulta. . Todos os drivers NoSQL da Oracle fornecem APIs para exibir o plano de execução de uma consulta.

Alguns dos iteradores mais comuns e importantes usados nas consultas são:

Iterador de tabela: Um iterador de tabela é responsável por:

Verificação do índice usado pela consulta (que pode ser o índice principal).
Aplicando predicados de filtragem enviados ao índice
Recupere as linhas apontadas pelas entradas de índice de qualificação, se necessário. Se o índice estiver cobrindo, o conjunto de resultados do iterador TABLE será um conjunto de entradas de índice; caso contrário, será um conjunto de linhas de tabela.

Observação:

Um índice é chamado de índice de cobertura em relação a uma consulta se a consulta puder ser avaliada usando apenas as entradas desse índice, ou seja, sem a necessidade de recuperar as linhas associadas.

SELECT iterator: É responsável por executar a expressão SELECT.

Toda consulta tem uma cláusula SELECT nela. Portanto, cada plano de consulta terá um iterador SELECT. Um iterador SELECT tem esta estrutura:


"iterator kind" : "SELECT",
"FROM" :
  {
  },
"FROM variable" : "...",
"SELECT expressions" : 
[
  {
  }
]

O iterador SELECT tem campos como: "FROM", "WHERE", "FROM variável" e "SELECT expressões". "FROM" e "FROM variable" representam a cláusula FROM da expressão SELECT, WHERE representa a cláusula de filtro, e "SELECT expression" representa a cláusula SELECT.

ATIVAR iterador: É um iterador interno especial que separa o plano de consulta em 2 partes:

O próprio iterador RECEIVE e todos os iteradores que estão acima dele na árvore de iteradores são executados no driver.
Todos os iteradores abaixo do iterador RECEIVE são executados nos nós de replicação (RNs); esses iteradores formam uma subárvore enraizada no filho exclusivo do iterador RECEIVE.

Em geral, o iterador RECEIVE atua como um coordenador de consultas. Ele envia seu subplano aos RNs apropriados para execução e coleta os resultados. Ele pode executar operações adicionais, como classificação e eliminação duplicada, e propagar os resultados para seus iteradores ancestrais (se houver) para processamento posterior.

Tipos da distribuição:

Um tipo de distribuição especifica como a consulta será distribuída para execução entre os RNs participantes de um banco de dados Oracle NoSQL (uma loja). O tipo de distribuição é uma propriedade do iterador RECEIVE.

Diferentes opções de tipos de distribuição são:

SINGLE_PARTITION: Uma consulta SINGLE_PARTITION especifica uma chave de shard completa em sua cláusula WHERE. Como resultado, seu conjunto completo de resultados está contido em uma única partição, e o iterador RECEIVE enviará seu subplano para um único RN que armazena essa partição. Uma consulta SINGLE_PARTITION pode usar o índice de chave primária ou um índice secundário.
ALL_PARTITIONS: As consultas usam o índice de chave primária aqui e não especificam uma chave de partição completa. Como resultado, se a loja tiver partições M, o iterador RECEIVE enviará cópias M de seu subplano para serem executadas em uma das partições M cada uma.
ALL_SHARDS: As consultas usam um índice secundário aqui e não especificam uma chave de partição completa. Como resultado, se a loja tiver N shards, o iterador RECEIVE enviará N cópias de seu subplano para serem executadas sobre um dos N shards cada.

Anatomia de um plano de execução da consulta:

A execução da consulta ocorre em lotes. Quando um subplano de consulta é enviado para uma partição ou shard para execução, ele será executado lá até que um limite de lote seja atingido. O limite do lote é um número de unidades de leitura consumidas localmente pela consulta. O padrão é 2000 unidades de leitura (cerca de 2 MB de dados) e só pode ser diminuído por meio de uma opção de nível de consulta.

Quando o limite do lote é atingido, todos os resultados locais que foram produzidos são enviados de volta ao iterador RECEIVE para processamento adicional, juntamente com um sinalizador booliano que diz se mais resultados locais podem estar disponíveis. Se o sinalizador for verdadeiro, a resposta incluirá informações de retomada. Se o iterador RECEIVE decidir reenviar a consulta para a mesma partição/shard, ele incluirá essas informações de retomada em sua solicitação, para que a execução da consulta seja reiniciada no ponto em que parou durante o batch anterior. Isso ocorre porque nenhum estado de consulta é mantido no RN após o término de um lote. O próximo lote para a mesma partição/shard pode ocorrer no mesmo RN que o lote anterior ou em um RN diferente que também armazena a mesma partição/shard.